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