herosdevices.helper
===================

.. py:module:: herosdevices.helper

.. autoapi-nested-parse::

   Helper functions for writing hardware drivers.









Module Contents
---------------

.. py:data:: SPAM
   :value: 5


.. py:class:: Logger(name, level=NOTSET)

   Bases: :py:obj:`logging.Logger`


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


   .. py:method:: setLevel(level: str | int, globally: bool = False) -> None

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



   .. py:method:: spam(msg: str, *args, **kwargs) -> None

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



.. py:data:: format_str
   :value: '%(asctime)-15s %(name)s: %(message)s'


.. py:data:: log

.. py:data:: SI_PREFIX_EXP

.. py:function:: limits(lower: float, upper: float) -> collections.abc.Callable[[float], str | bool]

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

   :param lower: The lower bound of the valid range.
   :param 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.


.. py:function:: 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.

   :param lower: The lower bound of the valid range.
   :param 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.


.. py:function:: 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.

   :param 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.


.. py:function:: extract_regex(pattern: str) -> collections.abc.Callable[[str], str]

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

   :param regex: regex pattern string.

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


.. py:function:: 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.

   :param in_unit: The input unit (e.g., 'k' for kilo, 'm' for milli). Use 'base' for no prefix.
   :param 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).


.. py:function:: merge_dicts(dict1: dict, dict2: dict) -> dict

   Recursively merge two dicts of dicts.


.. py:function:: 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.

   :param cls: Class to add the descriptor to
   :param attr_name: Name of the attribute the descriptor will be added to
   :param descriptor: The descriptor to be added


.. py:function:: 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

   :param 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.
   :param name: Name of the represented hardware as it should appear in the doc.
   :param info: Small info line which is shown as a subtitle in the doc.
   :param additional_docs: List of additional ``.rst`` files that are added to the documentation. For example to document
                           complicated vendor library installation procedures.
   :param requires: List of additional packages that are required to use the driver.
   :param product_page: URL to the vendor product page


