openrois-components-core 0.1.0a1__py3-none-any.whl

openrois/components/core/__init__.py

@@ -0,0 +1,41 @@
+"""OpenRoIS component SDK: write a RoIS HRI Component as a Python class.
+
+A component subclasses Component, declares its type with ``@component(profile)``, and
+marks the messages it implements::
+
+    from openrois.components.core import Component, component, invoke, subscribe
+    from openrois.interfaces.components import NAVIGATION_PROFILE
+
+    @component(NAVIGATION_PROFILE)
+    class Navigation(Component):
+        @invoke("start")
+        async def start(self) -> None:
+            ...
+
+The engine that hosts the component stores its parameters, answers component_status,
+tracks its commands and serves the part of the profile it implements. A connection that
+several components share is a Resource, which the engine opens and closes for them.
+"""
+
+from openrois.components.core.component import CommandFailed, Component, EngineBinding
+from openrois.components.core.decorators import (
+    component,
+    invoke,
+    on_set_parameter,
+    query,
+    subscribe,
+)
+from openrois.components.core.resource import Resource, ResourceBinding
+
+__all__ = [
+    "CommandFailed",
+    "Component",
+    "EngineBinding",
+    "Resource",
+    "ResourceBinding",
+    "component",
+    "invoke",
+    "on_set_parameter",
+    "query",
+    "subscribe",
+]

openrois/components/core/_spec.py

@@ -0,0 +1,180 @@
+"""What a decorated component class declares, checked against its profile.
+
+``@component`` builds a ComponentSpec when a class is defined: which method handles
+each command, query and event, the hook for new parameter values, and the profile the
+engine serves for the class. A handler that does not match the profile fails here, at
+class definition, so a typo cannot advertise a message the profile does not define.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Literal
+
+from openrois.interfaces.components import ROIS_COMMON_PROFILE, ROIS_COMMON_URN
+from openrois.interfaces.profiles import (
+    CommandMessageProfile,
+    EventMessageProfile,
+    HRIComponentProfile,
+    QueryMessageProfile,
+)
+
+type HandlerKind = Literal["command", "query", "event", "set_parameter"]
+
+# The messages whose handlers take arguments by name.
+type MessageWithArguments = CommandMessageProfile | QueryMessageProfile | EventMessageProfile
+
+# The attribute the method decorators set on the functions they mark.
+HANDLER_ATTRIBUTE = "__rois_handler__"
+
+# The engine answers these itself, so a component never handles them.
+ENGINE_COMMANDS = frozenset({"set_parameter"})
+ENGINE_QUERIES = frozenset({"component_status"})
+
+# A component whose profile includes RoISCommon serves these, handler or not.
+ROIS_COMMON_COMMANDS = frozenset(m.name for m in ROIS_COMMON_PROFILE.command_profiles)
+
+
+@dataclass(frozen=True, slots=True)
+class Handler:
+    """The message a method handles, set on the method by a decorator."""
+
+    kind: HandlerKind
+    name: str
+
+
+@dataclass(frozen=True, slots=True)
+class ComponentSpec:
+    """The messages a component class handles and the profile it serves.
+
+    Attributes:
+        declared: The profile the class declares, usually a profile constant.
+        served: The declared profile with only the messages the class answers: the
+            commands, queries and events it has handlers for, the four RoIS_Common
+            commands when the profile includes RoISCommon (the engine answers them by
+            default), otherwise ``stop`` when it handles ``start``, and
+            ``component_status``, which the engine answers. Every parameter of the
+            declared profile stays.
+        commands: The method that handles each command, by command name.
+        queries: The method that handles each query, by query name.
+        events: The method that runs on a new subscription, by event name.
+        set_parameter_hook: The method that applies new parameter values, if any.
+    """
+
+    declared: HRIComponentProfile
+    served: HRIComponentProfile
+    commands: Mapping[str, str]
+    queries: Mapping[str, str]
+    events: Mapping[str, str]
+    set_parameter_hook: str | None
+
+
+def build_spec(cls: type, profile: HRIComponentProfile) -> ComponentSpec:
+    """Collect the handlers of a class and check them against its profile.
+
+    Raises:
+        TypeError: A handler is not a coroutine function or has parameters its message
+            does not define.
+        ValueError: A handler names a message the profile does not define, a message the
+            engine answers itself, or a message another handler already handles.
+    """
+    owner = f"{cls.__qualname__}"
+    kind_of_type = f"{profile.identifier.authority} {profile.identifier.code}".strip()
+    defined: dict[HandlerKind, set[str]] = {
+        "command": {m.name for m in profile.command_profiles},
+        "query": {m.name for m in profile.query_profiles},
+        "event": {m.name for m in profile.event_profiles},
+    }
+    tables: dict[HandlerKind, dict[str, str]] = {"command": {}, "query": {}, "event": {}}
+    hook: str | None = None
+
+    for attribute in dir(cls):
+        method = getattr(cls, attribute, None)
+        handler = getattr(method, HANDLER_ATTRIBUTE, None)
+        if not isinstance(handler, Handler):
+            continue
+        where = f"{owner}.{attribute}"
+        if not inspect.iscoroutinefunction(method):
+            raise TypeError(f"{where} must be an async def")
+        parameters = list(inspect.signature(method).parameters.values())[1:]
+
+        if handler.kind == "set_parameter":
+            if not profile.parameter_profiles:
+                raise ValueError(f"{where} is an @on_set_parameter hook, but the profile "
+                                 f"{kind_of_type} declares no parameters")
+            if hook is not None:
+                raise ValueError(f"{owner} has two @on_set_parameter hooks: {hook} and "
+                                 f"{attribute}")
+            if len(parameters) != 1:
+                raise TypeError(f"{where} must take one argument, the new values")
+            hook = attribute
+            continue
+
+        if handler.kind == "command" and handler.name in ENGINE_COMMANDS:
+            raise ValueError(f"{where} handles {handler.name}, which the engine runs itself. "
+                             "Apply new parameter values in an @on_set_parameter hook")
+        if handler.kind == "query" and handler.name in ENGINE_QUERIES:
+            raise ValueError(f"{where} answers {handler.name}, which the engine answers "
+                             "itself")
+        if handler.name not in defined[handler.kind]:
+            raise ValueError(f"{where} handles the {handler.kind} {handler.name!r}, which the "
+                             f"profile {kind_of_type} does not define")
+        table = tables[handler.kind]
+        if handler.name in table:
+            raise ValueError(f"{owner}.{table[handler.name]} and {where} both handle the "
+                             f"{handler.kind} {handler.name!r}")
+        message: MessageWithArguments
+        if handler.kind == "command":
+            message = next(m for m in profile.command_profiles if m.name == handler.name)
+        elif handler.kind == "query":
+            message = next(m for m in profile.query_profiles if m.name == handler.name)
+        else:
+            message = next(m for m in profile.event_profiles if m.name == handler.name)
+        _check_parameters(where, message, parameters)
+        table[handler.name] = attribute
+
+    commands, queries, events = tables["command"], tables["query"], tables["event"]
+    rois_common = ROIS_COMMON_URN in profile.sub_component_profiles
+    served = profile.model_copy(
+        update={
+            "command_profiles": [
+                m
+                for m in profile.command_profiles
+                if m.name in commands
+                or (rois_common and m.name in ROIS_COMMON_COMMANDS)
+                or (m.name == "stop" and "start" in commands)
+            ],
+            "query_profiles": [
+                m for m in profile.query_profiles if m.name in queries or m.name in ENGINE_QUERIES
+            ],
+            "event_profiles": [m for m in profile.event_profiles if m.name in events],
+        }
+    )
+    return ComponentSpec(
+        declared=profile,
+        served=served,
+        commands=MappingProxyType(commands),
+        queries=MappingProxyType(queries),
+        events=MappingProxyType(events),
+        set_parameter_hook=hook,
+    )
+
+
+def _check_parameters(
+    where: str,
+    message: MessageWithArguments,
+    parameters: list[inspect.Parameter],
+) -> None:
+    """A handler takes the arguments of its message by name, and nothing else."""
+    arguments = {a.name for a in message.arguments}
+    for parameter in parameters:
+        if parameter.kind is inspect.Parameter.VAR_KEYWORD:
+            continue
+        if parameter.kind is inspect.Parameter.VAR_POSITIONAL:
+            raise TypeError(f"{where} cannot take *{parameter.name}: arguments arrive by name")
+        if parameter.name not in arguments:
+            raise TypeError(f"{where} takes {parameter.name!r}, which the message "
+                            f"{message.name!r} does not define as an argument")

openrois/components/core/component.py

@@ -0,0 +1,412 @@
+"""The Component base class and what it needs from the engine that hosts it.
+
+A component is a subclass of Component declared with ``@component(profile)``. Its author
+writes handlers for the messages it supports and uses what the engine binds at
+registration: ``self.parameters``, the current parameter values, ``self.emit``, which
+sends an event to the clients that subscribed, and ``self.raise_status`` and
+``self.clear_status``, which report WARNING or ERROR.
+
+The methods whose names start with ``rois_`` are the side the engine calls. An engine
+that hosts components written with this SDK calls them to read the served profile, bind
+itself, run commands and queries, start subscriptions and apply new parameter values.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from types import MappingProxyType
+from typing import Any, ClassVar, Protocol
+
+from openrois.interfaces.common import ComponentStatus
+from openrois.interfaces.hri import Argument, Parameter, Result
+from openrois.interfaces.profiles import (
+    CommandMessageProfile,
+    EventMessageProfile,
+    HRIComponentProfile,
+    MessageProfile,
+    QueryMessageProfile,
+)
+from openrois.interfaces.service import CompletedStatus
+from openrois.interfaces.values import decode_value, encode_value
+
+from openrois.components.core._spec import ComponentSpec
+from openrois.components.core.resource import Resource, check_raisable
+
+
+class CommandFailed(Exception):  # noqa: N818, the name says what happened to the command.
+    """Raised by a command handler to end its command with a status other than OK.
+
+    Any other exception ends the command with ERROR.
+
+    Attributes:
+        status: How the command ended: ERROR, ABORT, OUT_OF_RESOURCES or TIMEOUT.
+    """
+
+    def __init__(self, status: CompletedStatus = CompletedStatus.ERROR, message: str = "") -> None:
+        if status is CompletedStatus.OK:
+            raise ValueError("A failed command cannot end with OK")
+        super().__init__(message or status.value)
+        self.status = status
+
+
+class EngineBinding(Protocol):
+    """What a component needs from the engine that hosts it.
+
+    The engine passes an object of this shape to ``Component.rois_bind`` when it
+    registers the component.
+    """
+
+    @property
+    def ref(self) -> str:
+        """The fully qualified ref of the component, ``engine_id/name``."""
+        ...
+
+    def parameters(self) -> Sequence[Parameter]:
+        """The current value of every parameter of the component."""
+        ...
+
+    def emit(
+        self,
+        event_type: str,
+        results: Sequence[Result],
+        concerning: Mapping[str, str] | None = None,
+    ) -> None:
+        """Send an event to its subscriptions. Safe to call from any thread.
+
+        ``concerning`` names the argument values the event is about, in their string
+        form. The event goes to the subscriptions whose arguments equal them, and to
+        every subscription of the event when it is empty.
+        """
+        ...
+
+    def raise_status(self, status: ComponentStatus, message: str) -> None:
+        """Report WARNING or ERROR for the component. Safe to call from any thread."""
+        ...
+
+    def clear_status(self) -> None:
+        """Withdraw the status the component raised. Safe to call from any thread."""
+        ...
+
+    def engine_status(self) -> ComponentStatus:
+        """The status of the engine: ERROR or WARNING as raised on it, or READY."""
+        ...
+
+
+class Component:
+    """Base class of a RoIS HRI Component.
+
+    Subclass it, declare the profile with ``@component``, and write handlers::
+
+        @component(NAVIGATION_PROFILE)
+        class Navigation(Component):
+            @invoke("start")
+            async def start(self) -> dict[str, object]:
+                target = self.parameters["target_positions"][0]
+                await self._robot.go_to(target)
+                self.emit("reached_target", target=target, is_final_target=True)
+                return {}
+
+            @subscribe("reached_target")
+            async def reached_target(self) -> None:
+                pass  # start emits the event when the robot arrives.
+
+    A command handler runs for as long as the command lasts. It takes the arguments of
+    its command by name, converted from their profile types, and returns the values of
+    the command's results by name, or None. Raising CommandFailed ends the command with
+    the status it names, and any other exception ends it with ERROR. A query handler
+    returns the values of the query's results the same way.
+
+    The engine calls ``connect()`` before the component takes requests and
+    ``disconnect()`` when it stops. Override them to open and close the connection to
+    the backend. A connection that several components share is a Resource: the
+    component records it with ``self.uses(resource)``, and the engine opens it before
+    the first of them connects.
+    """
+
+    # Set by @component on the class it declares.
+    __rois_spec__: ClassVar[ComponentSpec | None] = None
+
+    # Set by rois_bind when the engine registers the component.
+    _rois_binding: EngineBinding | None = None
+
+    # Set by uses(), in the order the component recorded them.
+    _rois_resources: list[Resource] | None = None
+
+    # -- For component authors ---------------------------------------------------------
+
+    @property
+    def ref(self) -> str:
+        """The fully qualified ref the engine registered the component under."""
+        return self._binding().ref
+
+    @property
+    def parameters(self) -> Mapping[str, Any]:
+        """The current parameter values, converted from their profile types.
+
+        A ``string[]`` parameter reads as a list of str and an ``int`` as an int. The
+        engine stores the values and changes them on ``set_parameter``. A parameter with
+        no value yet, because its profile gives no default and no client has set it, is
+        missing from the mapping.
+        """
+        types = {p.name: p.data_type_ref.code for p in self._spec().declared.parameter_profiles}
+        return MappingProxyType(
+            {
+                p.name: decode_value(types.get(p.name, p.data_type_ref), p.value)
+                for p in self._binding().parameters()
+                if p.value != ""
+            }
+        )
+
+    def emit(
+        self,
+        event_type: str,
+        *,
+        concerning: Mapping[str, object] | None = None,
+        **values: object,
+    ) -> None:
+        """Send an event to the clients that subscribed to it.
+
+        The values are the event's results by name, converted to their profile types. A
+        result left out is not sent. Safe to call from any thread, for example a ROS 2
+        callback.
+
+        An event whose profile has arguments, such as the ``stream_id`` of
+        ``notify_stream_status``, names in ``concerning`` the argument values it is
+        about. It then reaches the subscriptions that gave those values, or none, and an
+        event that names no values reaches every subscription.
+
+        Raises:
+            ValueError: The component does not serve the event, a value has no result
+                of that name or does not fit its type, or ``concerning`` names an
+                argument the event does not have.
+            RuntimeError: No engine hosts the component yet.
+        """
+        spec = self._spec()
+        if event_type not in spec.events:
+            raise ValueError(
+                f"{type(self).__qualname__} does not serve the event {event_type!r}. "
+                "Mark it with @subscribe"
+            )
+        message = _message(spec.served.event_profiles, event_type)
+        concerns = _concerns(message, concerning or {})
+        self._binding().emit(event_type, _results(message, values), concerns)
+
+    def uses[R: Resource](self, resource: R) -> R:
+        """Record a resource the component shares with others, and return it.
+
+        Call it in ``__init__``. The engine opens every resource a component uses before
+        the component connects, and a status the resource raises becomes the
+        component's.
+        """
+        if self._rois_resources is None:
+            self._rois_resources = []
+        if not any(r is resource for r in self._rois_resources):
+            self._rois_resources.append(resource)
+        return resource
+
+    def raise_status(self, status: ComponentStatus, message: str = "") -> None:
+        """Report WARNING or ERROR, with a message, until ``clear_status``.
+
+        component_status reports the raised status, and the engine sends
+        ``rois.system.notify_error`` to the sessions that bound the component or
+        subscribed to its events. While ERROR is raised, the engine refuses the
+        component's commands and queries and holds back its events. Safe to call from
+        any thread.
+
+        Raises:
+            ValueError: The status is neither WARNING nor ERROR.
+            RuntimeError: No engine hosts the component yet.
+        """
+        check_raisable(status)
+        self._binding().raise_status(status, message)
+
+    def clear_status(self) -> None:
+        """Withdraw the status the component raised. Safe to call from any thread.
+
+        Raises:
+            RuntimeError: No engine hosts the component yet.
+        """
+        self._binding().clear_status()
+
+    def engine_state(self) -> ComponentStatus:
+        """The status of the engine that hosts the component.
+
+        ERROR or WARNING while one is raised on the engine, READY otherwise. A
+        SystemInformation component answers ``engine_status`` with it.
+
+        Raises:
+            RuntimeError: No engine hosts the component yet.
+        """
+        return self._binding().engine_status()
+
+    async def connect(self) -> None:
+        """Open the connection to the backend. The default does nothing."""
+
+    async def disconnect(self) -> None:
+        """Close the connection to the backend. The default does nothing."""
+
+    # -- Called by the engine ----------------------------------------------------------
+
+    @classmethod
+    def rois_profile(cls) -> HRIComponentProfile:
+        """The profile the engine serves for this class: what it implements."""
+        return cls._spec().served
+
+    def rois_bind(self, binding: EngineBinding) -> None:
+        """Attach the engine that hosts this component."""
+        self._rois_binding = binding
+
+    def rois_resources(self) -> Sequence[Resource]:
+        """The resources the component uses, in the order it recorded them."""
+        return list(self._rois_resources or ())
+
+    async def rois_command(
+        self,
+        command_type: str,
+        arguments: Sequence[Argument] = (),
+    ) -> list[Result]:
+        """Run one command until it completes, and return its results.
+
+        A served command without a handler returns at once. That is ``stop`` alongside
+        ``start``, and the four RoIS_Common commands of a profile that includes
+        RoISCommon: the engine holds, releases and aborts commands itself, and a start
+        without a handler is done once it begins.
+
+        Raises:
+            CommandFailed: The handler ended the command with another status.
+            ValueError: The component does not serve the command, or an argument does
+                not fit its profile.
+        """
+        spec = self._spec()
+        message = _message(spec.served.command_profiles, command_type)
+        method = spec.commands.get(command_type)
+        if method is None:
+            return []
+        values = await getattr(self, method)(**_arguments(message, arguments))
+        return _results(message, values)
+
+    async def rois_query(
+        self,
+        query_type: str,
+        arguments: Sequence[Argument] = (),
+    ) -> list[Result]:
+        """Answer one query with its results.
+
+        Raises:
+            ValueError: The component has no handler for the query, or an argument does
+                not fit its profile.
+        """
+        spec = self._spec()
+        method = spec.queries.get(query_type)
+        if method is None:
+            raise ValueError(f"{type(self).__qualname__} does not answer {query_type!r}")
+        message = _message(spec.served.query_profiles, query_type)
+        values = await getattr(self, method)(**_arguments(message, arguments))
+        return _results(message, values)
+
+    async def rois_subscribed(self, event_type: str, arguments: Sequence[Argument] = ()) -> None:
+        """Run the @subscribe method of an event for a new subscription.
+
+        The method receives the arguments the subscription gave, by name.
+
+        Raises:
+            ValueError: The component does not serve the event, or an argument does not
+                fit its profile.
+        """
+        spec = self._spec()
+        method = spec.events.get(event_type)
+        if method is None:
+            raise ValueError(f"{type(self).__qualname__} does not serve {event_type!r}")
+        message = _message(spec.served.event_profiles, event_type)
+        await getattr(self, method)(**_arguments(message, arguments))
+
+    async def rois_set_parameters(self, parameters: Sequence[Parameter]) -> None:
+        """Run the @on_set_parameter hook with new values, before the engine stores them.
+
+        Without a hook this returns at once. An exception from the hook refuses the
+        values, and the engine keeps the old ones.
+
+        Raises:
+            ValueError: A parameter is not in the profile or its value does not fit.
+        """
+        spec = self._spec()
+        if spec.set_parameter_hook is None:
+            return
+        types = {p.name: p.data_type_ref.code for p in spec.declared.parameter_profiles}
+        values: dict[str, Any] = {}
+        for parameter in parameters:
+            if parameter.name not in types:
+                raise ValueError(f"The profile defines no parameter {parameter.name!r}")
+            values[parameter.name] = decode_value(types[parameter.name], parameter.value)
+        await getattr(self, spec.set_parameter_hook)(MappingProxyType(values))
+
+    # -- Internals ---------------------------------------------------------------------
+
+    @classmethod
+    def _spec(cls) -> ComponentSpec:
+        spec = cls.__rois_spec__
+        if spec is None:
+            raise TypeError(f"{cls.__qualname__} is not declared with @component(profile)")
+        return spec
+
+    def _binding(self) -> EngineBinding:
+        if self._rois_binding is None:
+            raise RuntimeError(f"No engine hosts this {type(self).__qualname__} yet")
+        return self._rois_binding
+
+
+def _message[M: MessageProfile](messages: Sequence[M], name: str) -> M:
+    """The message profile of one name, among the served ones."""
+    for message in messages:
+        if message.name == name:
+            return message
+    raise ValueError(f"The component does not serve {name!r}")
+
+
+type _WithArguments = CommandMessageProfile | QueryMessageProfile | EventMessageProfile
+
+
+def _arguments(message: _WithArguments, arguments: Sequence[Argument]) -> dict[str, Any]:
+    """The arguments of a message by name, converted from their profile types."""
+    types = {a.name: a.data_type_ref.code for a in message.arguments}
+    values: dict[str, Any] = {}
+    for argument in arguments:
+        if argument.name not in types:
+            raise ValueError(f"{message.name!r} has no argument {argument.name!r}")
+        values[argument.name] = decode_value(types[argument.name], argument.value)
+    return values
+
+
+def _concerns(message: EventMessageProfile, values: Mapping[str, object]) -> dict[str, str]:
+    """The argument values an event concerns, in the form their types take on the wire."""
+    types = {a.name: a.data_type_ref.code for a in message.arguments}
+    concerns: dict[str, str] = {}
+    for name, value in values.items():
+        if name not in types:
+            raise ValueError(f"{message.name!r} has no argument {name!r}")
+        concerns[name] = encode_value(types[name], value)
+    return concerns
+
+
+def _results(message: MessageProfile, values: object) -> list[Result]:
+    """The results of a message from their values by name, in the order of the profile."""
+    if values is None:
+        return []
+    if not isinstance(values, Mapping):
+        raise TypeError(
+            f"A handler of {message.name!r} returns its result values by name, or None, "
+            f"not {type(values).__name__}"
+        )
+    declared = {r.name for r in message.results}
+    unknown = sorted(set(values) - declared)
+    if unknown:
+        raise ValueError(f"{message.name!r} has no result named {', '.join(unknown)}")
+    return [
+        Result(
+            name=r.name,
+            data_type_ref=r.data_type_ref.code,
+            value=encode_value(r.data_type_ref.code, values[r.name]),
+        )
+        for r in message.results
+        if r.name in values
+    ]