herosdevices.helper

Helper functions for writing hardware drivers.

Module Contents

herosdevices.helper.SPAM = 5

class herosdevices.helper.Logger(name, level=NOTSET)

Bases: logging.Logger

Extend logger to include a spam level for debugging device communication.

setLevel(level: str | int, globally: bool = False) → None

Set the logging level of this logger. level must be an int or a str.

spam(msg: str, *args, **kwargs) → None

Log a message with severity SPAM, even lower than DEBUG.

herosdevices.helper.format_str = '%(asctime)-15s %(name)s: %(message)s'

herosdevices.helper.log

herosdevices.helper.SI_PREFIX_EXP

herosdevices.helper.limits(lower: float, upper: float) → collections.abc.Callable[[float], str | bool]

Create a function which checks if a value is within the specified range.

Parameters:

• lower – The lower bound of the valid range.

• upper – The upper bound of the valid range.

Returns:

A function that takes a value and returns True if within the range, or a message indicating it’s out of range.

herosdevices.helper.limits_int(lower: int, upper: int) → collections.abc.Callable[[int], str | bool]

Create a function to check if a value is within a specified range and is an integer.

Parameters:

• lower – The lower bound of the valid range.

• upper – The upper bound of the valid range.

Returns:

A function that takes a value and returns True if within the range and is an integer, or a message indicating why it’s invalid.

herosdevices.helper.explicit(values: list[Any]) → collections.abc.Callable[[Any], str | bool]

Create a function to check if a value is in a list of allowed values.

Parameters:

values – A list of allowed values.

Returns:

A function that takes a value and returns True if within the list, or a message indicating it’s not in the list.

herosdevices.helper.extract_regex(pattern: str) → collections.abc.Callable[[str], str]

Create a function to extract a value from a string via regex pattern matching.

Parameters:

regex – regex pattern string.

Returns:

A function that takes a string and returns the first match group.

herosdevices.helper.transform_unit(in_unit: str, out_unit: str) → collections.abc.Callable[[float, bool], float]

Create a function to transform a value from one unit to another using SI prefixes.

Parameters:

• in_unit – The input unit (e.g., ‘k’ for kilo, ‘m’ for milli). Use ‘base’ for no prefix.

• out_unit – The output unit (e.g., ‘k’ for kilo, ‘m’ for milli). Use ‘base’ for no prefix.

Returns:

A function that transforms a given value from the input unit to the output unit, optionally allowing reverse transformation (second argument True).

herosdevices.helper.merge_dicts(dict1: dict, dict2: dict) → dict

Recursively merge two dicts of dicts.

herosdevices.helper.get_or_create_dynamic_subclass(base_cls: Any, *args: Any, **kwargs: Any) → type

Return a cached dynamic subclass of base_cls based on the input arguments.

This helper generates a subclass of base_cls whose identity is determined by *args and **kwargs. The argument signature is serialized into a hash, which is then used as both a cache key and the dynamic subclass name. If the subclass for a given argument combination already exists, it is returned from cache.

The generated subclass replaces __new__ with a dummy implementation to prevent recursive invocation of base_cls.__new__.

Parameters:

• base_cls – The base class to derive from. Must be passed positionally.

• *args – Positional values that should influence subclass identity.

• **kwargs – Keyword values that should influence subclass identity.

Returns:

A dynamically generated subclass of base_cls.

Raises:

TypeError – If arguments cannot be serialized for hashing.

herosdevices.helper.add_class_descriptor(cls: type, attr_name: str, descriptor) → None

Add a descriptor to a class.

This is a simple helper function which uses setattr to add an attribute to the class and then also calls __set_name__ on the attribute.

Parameters:

• cls – Class to add the descriptor to

• attr_name – Name of the attribute the descriptor will be added to

• descriptor – The descriptor to be added

herosdevices.helper.mark_driver(name: str | None = None, info: str | None = None, state: str = 'unknown', additional_docs: list | None = None, requires: dict | None = None, product_page: str | None = None) → collections.abc.Callable

Mark a class as a driver.

This decorator can be used to mark a class as a driver and attach meta data to it, which is then accessed by the sphinx documentation. All drivers marked with this decorator will be listed on the “Hardware” page. Wraps the __init__ function of the decorated class to check if all required packages are installed.

Parameters:

• state – State of the driver, can be “alpha” for very untested code “beta” for tested but under active development or “stable” for well tested and stable drivers.

• name – Name of the represented hardware as it should appear in the doc.

• info – Small info line which is shown as a subtitle in the doc.

• additional_docs – List of additional .rst files that are added to the documentation. For example to document complicated vendor library installation procedures.

• requires – List of additional packages that are required to use the driver, given in the form of a dictionary with the package name used in an import statement as key and a PyPi package name or url to the package as value. The import name is used to check if the required package is available.

• product_page – URL to the vendor product page

herosdevices.helper.cast_iterable(it: collections.abc.Iterable, target_type: Any) → list

Convert an iterable to a list of specified target type.

Parameters:

• it – An iterable object containing elements to be converted.

• target_type – The type to which each element in the iterable should be converted.

Returns:

A list containing elements from the input iterable converted to the target type.

Example

>>> cast_iterable([1, 2, 3], str)
['1', '2', '3']
>>> cast_iterable(['1', '2', '3'], int)
[1, 2, 3]