Source code for heros.ref

from dataclasses import dataclass

_FORBIDDEN_CHARS = frozenset("/*?#$")




@dataclass(frozen=True, slots=True)
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.

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

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

    name: str
    realm: str



    def __post_init__(self):
        for field_name in ("name", "realm"):
            value = getattr(self, field_name)
            if not isinstance(value, str):
                raise TypeError(f"{field_name} must be a str, got {type(value).__name__}")
            if not value:
                raise ValueError(f"{field_name} must not be empty")
            if bad := sorted(_FORBIDDEN_CHARS & set(value)):
                raise ValueError(f"{field_name} must not contain {' '.join(bad)}: {value!r}")