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.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: list | 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. It does not have any effect beyond documentation

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.

• product_page – URL to the vendor product page