heros
=====

.. py:module:: heros


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/heros/capabilities/index
   /autoapi/heros/datasource/index
   /autoapi/heros/event/index
   /autoapi/heros/helper/index
   /autoapi/heros/heros/index
   /autoapi/heros/inspect/index
   /autoapi/heros/serdes/index
   /autoapi/heros/zenoh/index


Classes
-------

.. autoapisummary::

   heros.DatasourceObserver
   heros.LocalDatasourceHERO
   heros.PolledLocalDatasourceHERO
   heros.DatasourceReturnSet
   heros.DatasourceReturnValue


Functions
---------

.. autoapisummary::

   heros.event


Package Contents
----------------

.. py:class:: DatasourceObserver(object_selector: str = '*', *args, **kwargs)

   Bases: :py:obj:`heros.EventObserver`


   A class that can observe and handle the data emitted by one or more datasource HEROs.
   In particular, this class provides an efficient way to listen to the data emitted by all datasource HEROs in
   the realm. By not instantiating the HEROs themselves but just subscribing to the topics for the datasource, this
   reduces the pressure on the backing zenoh network. If, however, only the data of a few HEROs should be observed,
   it might make more sense to just instantiate the according RemoteHEROs and connect a callback to their `observable_data`
   signal.

   :param object_selector: selector to specify which objects to observe. This becomes part of a zenoh selector and thus
   :param can be anything that makes sense in the selector. Defaults to * to observe all HEROs in the realm.:


   .. py:method:: _handle_event(key_expr: str, data)


   .. py:method:: register_observable_data_callback(func: collections.abc.Callable)

      Register a callback that should be called on observable_data.
      This method passes the function to `EventObserver.register_callback`

      :param func: function to call on observable_data.



.. py:class:: LocalDatasourceHERO(*args, observables: dict | None = None, **kwargs)

   Bases: :py:obj:`heros.LocalHERO`


   A datasource is a HERO that can provide information on a standardized interface.
   This interface is the event `observable_data`. Instances in the zenoh network interested in the data provided
   by data sources can simply subscribe to the key expression `@objects/realm/*/observable_data` or use
   the :class:`DatasourceObserver`.

   To make your class a LocalDatasourceHERO make it inherit this class.
   This class is meant for datasources that create asynchronous events on their own. When processing such an event
   call `observable_data` to publish the data from this datasource.

   :param name: name/identifier under which the object is available. Make sure this name is unique in the realm.
   :param realm: realm the HERO should exist in. default is "heros"


   .. py:attribute:: _observables


   .. py:attribute:: observable_processor


   .. py:method:: _process_data(data)


   .. py:method:: observable_data(data)


.. py:class:: PolledLocalDatasourceHERO(*args, loop, interval: float = 5, **kwargs)

   Bases: :py:obj:`LocalDatasourceHERO`


   This local HERO periodically triggers the event "observable_data" to poll and publish data.
   This class is meant for datasources that do not generate events on their own an thus should be polled
   on a periodical basis.

   To make your class a PolledLocalDatasourceHERO make it inherit this class an implement the method `_observable_data`.
   The method will get called periodically and the return value will be published as an event.

   .. note:: The periodic calling is realized via asyncio and will thus only work if the asyncio mainloop is started.

   :param name: name/identifier under which the object is available. Make sure this name is unique in the realm.
   :param realm: realm the HERO should exist in. default is "heros"
   :param interval: time interval in seconds between consecutive calls of `observable_data` event


   .. py:attribute:: datasource_interval
      :value: 5



   .. py:attribute:: _loop


   .. py:attribute:: _stop_loop


   .. py:attribute:: _loop_task


   .. py:method:: _trigger_datasource()
      :async:



   .. py:method:: _destroy_hero()


   .. py:method:: observable_data()


   .. py:method:: _observable_data() -> dict


.. py:class:: DatasourceReturnSet

   Bases: :py:obj:`tuple`


   Collection of multiple :class:`DatasourceReturnValue`.


   .. py:method:: from_data(data)
      :staticmethod:


      We try to build a DatasourceReturnSet by guessing the data format from the following options:
          * [FLOAT, FLOAT, ..] -> A list of raw_values
          * [(FLOAT, STR), (FLOAT, STR), ..] -> a list of (raw_value, raw_unit) tuples
          * {STR: FLOAT, STR: FLOAT, ..} -> a dict with id: raw_value
          * {STR: (FLOAT, STR), STR: (FLOAT, STR), ...} a dict with id: (raw_value, raw_unit)
          * FLOAT -> raw_value
          * (FLOAT, STR) -> (raw_value, raw_unit)



.. py:class:: DatasourceReturnValue(id: str | None = None, time: float | None = None, value: float | None = None, unit: str | None = None, raw_value: float | None = None, raw_unit: str | None = None, inbound: int = -1, calibrated: bool = False, **kwargs)

   Bases: :py:obj:`dict`


   A structure to store data returned from a single entity in a datasource.
   A datasource can return multiple entities at once. In this case many DatasourceReturnValues are stored in
   a :class:`DatasourceReturnSet`.

   Default return values from datasource. They can be converted using a calibration.
    :param raw_value: (float)
    :param raw_unit: (str[10])
    :param time: (int) creation time of the rawValue.


   .. py:property:: id


   .. py:property:: raw_value


   .. py:property:: raw_unit


   .. py:property:: value

      (float) value in specified units.


   .. py:property:: unit

      SI Unit of the current tuple.


   .. py:property:: time


   .. py:property:: inbound

      Boundary level (int) -1=unbound, 0=ok, 1=warn,error, fault


   .. py:method:: __str__()

      Return str(self).



   .. py:method:: __repr__()

      Return repr(self).



.. py:function:: event(func: collections.abc.Callable)

   Decorator for events.

   .. note:: Only use on methods bound to objects.


