heros.ref
=========

.. py:module:: heros.ref


Attributes
----------

.. autoapisummary::

   heros.ref._FORBIDDEN_CHARS


Classes
-------

.. autoapisummary::

   heros.ref.HERORef


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

.. py:data:: _FORBIDDEN_CHARS

.. py:class:: HERORef

   Identity of a HERO, given by its name and realm.

   A ``HERORef`` is a plain value. It holds no connection and does not look up or contact the HERO.
   Two references are equal if name and realm are equal.

   Name and realm must be non-empty strings without any of the characters ``/ * ? # $``. These characters have
   a special meaning in zenoh key expressions or in HEROS configuration strings. The check is strict on purpose.

   Connection settings are not fields of this class. If a field is ever needed that must not take part in
   comparison, add it as ``field(default=..., compare=False, kw_only=True)`` so existing calls keep working.

   ``HERORef`` has no CBOR encoding. If a ``HERORef`` is returned or sent as argument, the fallback in
   :py:func:`heros.serdes.cbor_default_encoder` stores it in the object store of the sender and transmits an
   unserializable-object tag with the class name, an identifier and ``str(value)``. The receiver gets a
   ``heros.serdes.UnserializableRemoteObject``. Sending that object back yields the original ``HERORef``
   on the side that stored it.

   :param name: Name of the HERO.
   :param realm: Realm of the HERO.

   :raises TypeError: If name or realm is not a string.
   :raises ValueError: If name or realm is empty or contains a forbidden character.


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


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


   .. py:method:: __post_init__()