heros.capabilities
==================

.. py:module:: heros.capabilities


Classes
-------

.. autoapisummary::

   heros.capabilities.Parameter
   heros.capabilities.Capability
   heros.capabilities.AttributeCapability
   heros.capabilities.EventCapability
   heros.capabilities.MethodCapability


Functions
---------

.. autoapisummary::

   heros.capabilities.type_to_str
   heros.capabilities.build_capability


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

.. py:function:: type_to_str(annotation: type | str) -> str

   Transforms annotation given as `types` to strings.

   :param annotation: The typing annotation.

   :returns: Annotation as string.


.. py:function:: build_capability(hero_obj: heros.heros.LocalHERO, member_name: str, annotation: None | str = None) -> Capability | Literal[False]

   Build a capability object from a given member name and optional annotation to infer type.

   If no annotation is given the signature is inferred from the member itself by calling `getattr`. For callables (e.g.
   methods) this needs to be done, as the full signature is not inferable from the type annotation.

   :param hero_obj: host HERO object
   :param member_name: name of the attribute/method to build as capability
   :param annotation: optional annotation to infer signature.

   :returns: :py:class:`Capability` object for the given member, `False` if no signature can be inferred from the given
             input.


.. py:class:: Parameter

   .. py:attribute:: name
      :type:  str


   .. py:attribute:: type
      :type:  str


   .. py:attribute:: default
      :type:  str


   .. py:attribute:: kind
      :type:  inspect._ParameterKind


   .. py:method:: from_signature_parameter(p: inspect.Parameter)
      :staticmethod:



   .. py:method:: has_default()


   .. py:method:: to_dict()


   .. py:method:: from_dict(d: dict, proto_version: float = __proto_version__)
      :staticmethod:



.. py:class:: Capability

   .. py:attribute:: name
      :type:  str


   .. py:attribute:: flavor
      :type:  ClassVar[str]
      :value: 'undefined'



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


   .. py:method:: from_dict(d: dict, proto_version: float = __proto_version__)
      :staticmethod:



   .. py:method:: get_call_wrapper(hero_obj: heros.heros.LocalHERO) -> Callable[[zenoh.Query], None] | Literal[False]

      Construct a callback wrapper function for the Zenoh endpoint.

      :returns: A wrapper function which takes exactly one input, the :py:class:`zenoh.Query` object or `False` if
                the capability does not need a wrapper function.



.. py:class:: AttributeCapability

   Bases: :py:obj:`Capability`


   An attribute capability describes a single variable of the remote object.
   It is exposed under the name of the capability.

   :param name: name of the capability
   :param type: data type. E.g. "str", "int", "float", "list", ...
   :param access: Read and/or write access. "r" for read, "w" for write, and "rw" for both


   .. py:attribute:: flavor
      :type:  ClassVar[str]
      :value: 'attribute'



   .. py:attribute:: type
      :type:  str


   .. py:attribute:: access
      :type:  str
      :value: 'rw'



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


   .. py:method:: from_dict(d: dict, proto_version: float = __proto_version__) -> AttributeCapability
      :staticmethod:



   .. py:method:: get_call_wrapper(hero_obj: heros.heros.LocalHERO) -> Callable[[zenoh.Query], None]

      Construct a callback wrapper function for the Zenoh endpoint.

      :returns: A wrapper function which takes exactly one input, the :py:class:`zenoh.Query` object or `False` if
                the capability does not need a wrapper function.



.. py:class:: EventCapability

   Bases: :py:obj:`Capability`


   An event capability describes the ability of a remote object to notify upon a certain event.


   .. py:attribute:: flavor
      :type:  ClassVar[str]
      :value: 'event'



   .. py:method:: from_dict(d: dict, proto_version: float = __proto_version__) -> EventCapability
      :staticmethod:



.. py:class:: MethodCapability

   Bases: :py:obj:`Capability`


   .. py:attribute:: flavor
      :type:  ClassVar[str]
      :value: 'method'



   .. py:attribute:: parameters
      :type:  list[Parameter]
      :value: []



   .. py:attribute:: return_type
      :type:  str
      :value: 'None'



   .. py:method:: from_method(m: Callable, name: str | None = None) -> MethodCapability
      :staticmethod:



   .. py:method:: to_signature() -> inspect.Signature


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


   .. py:method:: get_call_wrapper(hero_obj: heros.heros.LocalHERO) -> Callable[[zenoh.Query], None]

      Construct a callback wrapper function for the Zenoh endpoint.

      :returns: A wrapper function which takes exactly one input, the :py:class:`zenoh.Query` object or `False` if
                the capability does not need a wrapper function.



   .. py:method:: from_dict(d: dict, proto_version: float = __proto_version__) -> MethodCapability
      :staticmethod:


      Generate a method capabilities object from a defining dictionary.

      Args: definition of the capability according to the standard



   .. py:method:: call_dict(*args, **kwargs) -> dict

      This returns a dict that assigns the given parameter to the parameters of
      ourself. It takes care that positional and keyword arguments are handled correctly

      .. note:: This function is deprecated and will be removed together with the transport protocol version 0.1

      :param \*args: positional arguments
      :param \*\*kwargs: keyword arguments

      :returns: dict with parameter assignments
      :rtype: dict



