motorcortex-python 1.0.0rc1__py3-none-any.whl

motorcortex/session.py

@@ -0,0 +1,194 @@
+#
+#   Developer: Alexey Zakharov (alexey.zakharov@vectioneer.com)
+#   All rights reserved. Copyright (c) 2026 VECTIONEER.
+#
+
+"""High-level context-manager wrapper around ``(Request, Subscribe)``.
+
+``motorcortex.Session`` owns both channels, constructs sensible defaults
+for ``MessageTypes`` and ``ParameterTree``, and guarantees ``close()``
+on the way out — including on exceptions inside the ``with`` block.
+Nothing about the underlying API changes: ``session.req`` and
+``session.sub`` are the same ``Request`` / ``Subscribe`` instances the
+user would get from :func:`motorcortex.connect`, so every existing
+method call keeps working unchanged.
+
+The class is intentionally thin. It does not replicate the RPC surface
+of ``Request`` / ``Subscribe`` — pass-through getters would drift from
+the real objects over time. A couple of convenience properties
+(``connectionState``, ``token``) are provided because they're the two
+things users poll most often.
+
+Example::
+
+    with motorcortex.Session(
+        "wss://robot.local:5568:5567",
+        login="administrator",
+        password="administrator",
+        certificate="/etc/ssl/certs/motorcortex.pem",
+    ) as s:
+        reply = s.req.getParameter("root/Control/x").get()
+        s.sub.subscribe(["root/Control/x"], "grp", frq_divider=10)
+
+The existing :func:`motorcortex.connect` entrypoint is unchanged; code
+that manages ``(req, sub)`` explicitly keeps working.
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any, Optional, Type, TYPE_CHECKING
+
+from motorcortex.exceptions import McxConnectionError
+
+if TYPE_CHECKING:
+    from motorcortex.request import Request, ConnectionState
+    from motorcortex.subscribe import Subscribe
+    from motorcortex.message_types import MessageTypes
+    from motorcortex.parameter_tree import ParameterTree
+
+
+class Session:
+    """Context-manager owning a ``(Request, Subscribe)`` pair.
+
+    Args:
+        url: Connection URL (``scheme://host:req_port:sub_port``).
+        motorcortex_types: Optional pre-built ``MessageTypes``. A fresh
+            one is constructed when omitted.
+        param_tree: Optional pre-built ``ParameterTree``. A fresh one
+            is constructed when omitted. After :meth:`connect` /
+            entering the ``with`` block, the tree is populated from
+            the server.
+        **kwargs: Forwarded verbatim to :func:`motorcortex.connect` —
+            ``login``, ``password``, ``certificate``, ``timeout_ms``,
+            ``reconnect``, ``token_update_interval_ms``,
+            ``req_number_of_threads``, ``sub_number_of_threads``,
+            ``state_update``.
+
+    The session is lazy — it does not dial until :meth:`connect` is
+    called or the ``with`` block is entered. That way constructing a
+    Session on its own is cheap and can't raise ``RuntimeError``.
+    """
+
+    def __init__(
+            self,
+            url: str,
+            motorcortex_types: Optional["MessageTypes"] = None,
+            param_tree: Optional["ParameterTree"] = None,
+            **kwargs: Any,
+    ) -> None:
+        # Imported lazily so the `motorcortex` package can be imported
+        # without pulling in pynng during static analysis.
+        from motorcortex.message_types import MessageTypes
+        from motorcortex.parameter_tree import ParameterTree
+
+        self._url = url
+        self._kwargs = kwargs
+        self._types: "MessageTypes" = motorcortex_types or MessageTypes()
+        self._tree: "ParameterTree" = param_tree or ParameterTree()
+        self._req: Optional["Request"] = None
+        self._sub: Optional["Subscribe"] = None
+
+    # -- lifecycle -----------------------------------------------------
+
+    def connect(self) -> "Session":
+        """Open the underlying ``Request`` / ``Subscribe`` pair.
+
+        Idempotent — a second call while already connected is a no-op.
+        Returns ``self`` so ``with Session(...).connect() as s:`` works
+        (though entering the ``with`` block alone is enough).
+        """
+        if self._req is not None:
+            return self
+        from motorcortex import connect as _connect
+        self._req, self._sub = _connect(
+            self._url, self._types, self._tree, **self._kwargs,
+        )
+        return self
+
+    def close(self) -> None:
+        """Close subscribe then request. Idempotent; safe on failure."""
+        if self._sub is not None:
+            try:
+                self._sub.close()
+            except Exception:
+                pass
+            self._sub = None
+        if self._req is not None:
+            try:
+                self._req.close()
+            except Exception:
+                pass
+            self._req = None
+
+    def __enter__(self) -> "Session":
+        return self.connect()
+
+    def __exit__(
+            self,
+            exc_type: Optional[Type[BaseException]],
+            exc: Optional[BaseException],
+            tb: Optional[TracebackType],
+    ) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        if self._req is None:
+            state = "not-connected"
+        else:
+            state = self._req.connectionState().name
+        return f"Session(url={self._url!r}, state={state})"
+
+    # -- accessors -----------------------------------------------------
+
+    @property
+    def req(self) -> "Request":
+        """The underlying ``Request``. Raises if :meth:`connect` hasn't run."""
+        if self._req is None:
+            raise McxConnectionError(
+                "Session is not connected. Use 'with Session(...) as s:' "
+                "or call session.connect() first."
+            )
+        return self._req
+
+    @property
+    def sub(self) -> "Subscribe":
+        """The underlying ``Subscribe``."""
+        if self._sub is None:
+            raise McxConnectionError(
+                "Session is not connected. Use 'with Session(...) as s:' "
+                "or call session.connect() first."
+            )
+        return self._sub
+
+    @property
+    def types(self) -> "MessageTypes":
+        """The ``MessageTypes`` instance this session uses."""
+        return self._types
+
+    @property
+    def tree(self) -> "ParameterTree":
+        """The populated ``ParameterTree`` after connect; empty before."""
+        return self._tree
+
+    @property
+    def url(self) -> str:
+        return self._url
+
+    def connectionState(self) -> "ConnectionState":
+        """Convenience shortcut for ``session.req.connectionState()``.
+
+        Returns ``DISCONNECTED`` before :meth:`connect` has run so
+        callers don't need to guard against ``None``.
+        """
+        from motorcortex._connection_state import ConnectionState
+        if self._req is None:
+            return ConnectionState.DISCONNECTED
+        return self._req.connectionState()
+
+    @property
+    def token(self) -> Optional[str]:
+        """Convenience shortcut for ``session.req.token`` — the session
+        token issued by the engine at login, or ``None`` before connect.
+        """
+        return None if self._req is None else self._req.token

motorcortex/setup_logger.py

@@ -0,0 +1,10 @@
+#!/usr/bin/python3
+
+#
+#   Developer: Alexey Zakharov (alexey.zakharov@vectioneer.com)
+#   All rights reserved. Copyright (c) 2021 VECTIONEER.
+#
+
+import logging
+
+logger = logging.getLogger('mcx')

motorcortex/state_callback_handler.py

@@ -0,0 +1,92 @@
+#!/usr/bin/python3
+
+#
+#   Developer: Alexey Zakharov (alexey.zakharov@vectioneer.com)
+#   All rights reserved. Copyright (c) 2025-2026 VECTIONEER.
+#
+
+from queue import Queue, Empty
+import threading
+from motorcortex.setup_logger import logger
+
+from typing import Any, Callable, Optional, Tuple
+
+
+class StateCallbackHandler:
+    """
+    Handles state change callbacks processing.
+
+    This class manages a background thread and a queue to process state update notifications
+    using a user-provided callback function.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initializes the StateCallbackHandler.
+        """
+        self.running: bool = False
+        self.callback_queue: Queue = Queue()
+        self.callback_thread: Optional[threading.Thread] = None
+        self.state_update_handler: Optional[Callable[..., Any]] = None
+
+    def start(self, state_update_handler: Callable[..., Any]) -> None:
+        """
+        Start the callback handler with the given update function.
+
+        Args:
+            state_update_handler (Callable[..., Any]):
+                The function to call when a state update is notified. Should accept arbitrary arguments.
+        """
+        if state_update_handler is not None:
+            self.state_update_handler = state_update_handler
+            self.running = True
+            self.callback_thread = threading.Thread(
+                target=self._process_callbacks,
+                daemon=True
+            )
+            self.callback_thread.start()
+
+    def stop(self) -> None:
+        """
+        Stop the callback handler and clean up resources.
+        """
+        self.running = False
+        if self.callback_thread:
+            self.callback_queue.put(None)  # Signal thread to exit
+            self.callback_thread.join(timeout=1.0)
+            self.callback_thread = None
+        self.state_update_handler = None
+
+    def notify(self, *args: Any) -> None:
+        """
+        Queue a state update notification.
+
+        Args:
+            *args (Any): Arguments to pass to the state update handler.
+        """
+        if self.state_update_handler:
+            self.callback_queue.put(args)
+
+    def _process_callbacks(self) -> None:
+        """
+        Process callbacks in a dedicated thread.
+        """
+        while self.running:
+            try:
+                args = self.callback_queue.get(timeout=0.1)
+                if args is None:  # Stop signal
+                    break
+                # The worker thread is only spawned by start() after
+                # state_update_handler is set, so it's guaranteed
+                # non-None here.
+                handler = self.state_update_handler
+                assert handler is not None
+                try:
+                    handler(*args)
+                except Exception as e:
+                    logger.exception("Error in state callback: %s", e)
+            except Empty:
+                continue
+            except Exception as e:
+                if self.running:
+                    logger.exception("Error processing callbacks: %s", e)

motorcortex/subscribe.py

@@ -0,0 +1,400 @@
+#!/usr/bin/python3
+
+#
+#   Developer: Alexey Zakharov (alexey.zakharov@vectioneer.com)
+#   All rights reserved. Copyright (c) 2016-2026 VECTIONEER.
+#
+
+import atexit
+
+import pynng  # type: ignore[import-untyped]
+from pynng import Sub0, TLSConfig  # type: ignore[import-untyped]
+from concurrent.futures import ThreadPoolExecutor
+from threading import Event
+from typing import Any, Callable, Dict, Optional, List, TYPE_CHECKING
+
+from motorcortex.request import Request, Reply, ConnectionState
+from motorcortex.subscription import Subscription
+from motorcortex.state_callback_handler import StateCallbackHandler
+from motorcortex.setup_logger import logger
+from motorcortex.nng_url import NngUrl
+from motorcortex import _connection_state, _request_utils, _subscribe_dispatch
+
+if TYPE_CHECKING:
+    from motorcortex.message_types import MessageTypes
+
+
+def _close_at_exit(inst: "Subscribe") -> None:
+    """Shutdown hook mirroring ``motorcortex.request._close_at_exit``.
+
+    Subscribe is the one that actually hangs interpreter shutdown when
+    forgotten — its receive-loop worker is blocked in ``socket.recv()``
+    and Python's ``concurrent.futures._python_exit`` waits for it
+    forever. This closes the socket (→ recv raises pynng.Closed) and
+    shuts down the pool before ``_python_exit`` gets a chance to join
+    it, so the worker exits cleanly.
+
+    Strong reference instead of weakref — when the user's main function
+    returns, local ``sub`` goes out of scope and a weakref would resolve
+    to None before our hook fires, defeating the purpose.
+    """
+    try:
+        if getattr(inst, "_closed", True):
+            return
+        inst.close()
+    except Exception:
+        pass
+
+
+def _register_shutdown(inst: "Subscribe") -> None:
+    """Register ``_close_at_exit(inst)`` to fire before Python joins
+    ThreadPoolExecutor workers.
+
+    ``concurrent.futures._python_exit`` uses ``threading._register_atexit``
+    (not regular ``atexit``) so it runs ahead of user-level atexit
+    handlers. We hook the same threading-level registry — that way our
+    cleanup runs just before ``_python_exit`` gets its turn and the
+    pool.shutdown inside close() completes cleanly instead of deadlocking.
+
+    ``threading._register_atexit`` is a private API but has been stable
+    since 3.9. Fall back to regular ``atexit`` on older interpreters /
+    if it disappears in a future version — that's strictly worse but
+    still better than nothing.
+    """
+    try:
+        import threading
+        threading._register_atexit(_close_at_exit, inst)  # type: ignore[attr-defined]
+    except (AttributeError, ImportError):
+        atexit.register(_close_at_exit, inst)
+
+
+class Subscribe:
+    """
+    Subscribe class is used to receive continuous parameter updates from the motorcortex server.
+
+    This class simplifies creating and removing subscription groups, managing the connection,
+    and handling the reception of parameter updates.
+    """
+
+    def __init__(self, req: Request, protobuf_types: "MessageTypes", number_of_threads: int = 2) -> None:
+        """
+        Initialize a Subscribe object.
+
+        Args:
+            req (Request): Reference to a Request instance.
+            protobuf_types (MessageTypes): Reference to a MessageTypes instance.
+            number_of_threads (int): Thread pool size (minimum 2, None - use default (CPU-based)).
+        """
+        self._socket: Optional[Sub0] = None
+        self._connected_event: Optional[Event] = None
+        self._is_connected: bool = False
+        self._url: Optional[str] = None
+        self._req: Request = req
+        self._protobuf_types: Any = protobuf_types
+        self._subscriptions: Dict[int, Subscription] = dict()
+        if number_of_threads and number_of_threads < 2:
+            number_of_threads = 2
+        self._pool: ThreadPoolExecutor = ThreadPoolExecutor(
+            max_workers=number_of_threads, thread_name_prefix="mcx_sub")
+        self._callback_handler: StateCallbackHandler = StateCallbackHandler()
+        self._connection_state: ConnectionState = ConnectionState.DISCONNECTED
+        # Net safeguard against the "forgot to call close()" hang —
+        # see motorcortex.subscribe._close_at_exit for the rationale.
+        self._closed: bool = False
+        _register_shutdown(self)
+
+    def __repr__(self) -> str:
+        return (
+            f"Subscribe(url={self._url!r}, "
+            f"state={self._connection_state.name}, "
+            f"groups={len(self._subscriptions)})"
+        )
+
+    # -- NNG pipe callbacks -------------------------------------------
+    #
+    # Methods instead of closures — direct invocation in tests, shorter
+    # connect(), same runtime behavior. See ``motorcortex.request`` for
+    # the mirror pair. The ``pipe`` arg from NNG is unused.
+
+    def _on_pipe_connect(self, _pipe: Any) -> None:
+        """Subscribe socket accepted a peer pipe — transition to
+        ``CONNECTION_OK`` and wake waiters.
+        """
+        old_state = self._connection_state.name
+        self._is_connected = True
+        self._connection_state = ConnectionState.CONNECTION_OK
+        logger.debug(
+            "[SUBSCRIBE-CALLBACK] PRE_CONNECT fired — %s -> %s",
+            old_state, self._connection_state.name,
+        )
+        self._callback_handler.notify(self._req, self, self.connectionState())
+        if self._connected_event is not None:
+            self._connected_event.set()
+
+    def _on_pipe_remove(self, _pipe: Any) -> None:
+        """Subscribe socket pipe torn down. Delegates to the shared
+        state-transition helper.
+        """
+        old_state = self._connection_state.name
+        self._connection_state = _connection_state.next_state_after_pipe_remove(
+            self._connection_state
+        )
+        logger.debug(
+            "[SUBSCRIBE-CALLBACK] POST_REMOVE fired — %s -> %s",
+            old_state, self._connection_state.name,
+        )
+        self._is_connected = False
+        self._callback_handler.notify(self._req, self, self.connectionState())
+        if self._connected_event is not None:
+            self._connected_event.set()
+
+    def connect(self, url: str, **kwargs: Any) -> "Reply[bool]":
+        """
+        Open a subscription connection.
+
+        Args:
+            url (str): Motorcortex server URL.
+            **kwargs: Additional connection parameters. Supported keys include:
+                certificate (str, optional): Path to a TLS certificate file for secure connections.
+                conn_timeout_ms (int, optional): Connection timeout in milliseconds (default: 1000).
+                recv_timeout_ms (int, optional): Receive timeout in milliseconds (default: 500).
+                login (str, optional): Username for authentication (if required by server).
+                password (str, optional): Password for authentication (if required by server).
+                state_update (Callable, optional): Callback function to be called on connection state changes.
+                timeout_ms (int, optional): Alternative timeout in milliseconds (used by Request.parse).
+
+        Returns:
+            Reply: A promise that resolves when the connection is established.
+        """
+        self._connection_state = ConnectionState.CONNECTING
+        conn_timeout_ms, recv_timeout_ms, certificate, state_update = _request_utils.parse_connect_kwargs(**kwargs)
+
+        if state_update:
+            self._callback_handler.start(state_update)
+
+        if not recv_timeout_ms:
+            recv_timeout_ms = 500
+
+        self._url = url
+        tls_config = None
+        if certificate:
+            parsed = NngUrl(url)
+            # See request.py for the rationale — pynng defaults auth_mode to
+            # REQUIRED, but mbedTLS 3.6+ rejects the self-signed end-entity
+            # cert motorcortex ships as a trust anchor. OPTIONAL verifies
+            # best-effort without failing on the CA:FALSE check.
+            tls_config = TLSConfig(
+                TLSConfig.MODE_CLIENT,
+                ca_files=certificate,
+                server_name=parsed.hostname,
+                auth_mode=TLSConfig.AUTH_MODE_OPTIONAL,
+            )
+
+        self._socket = Sub0(recv_timeout=recv_timeout_ms, tls_config=tls_config)
+
+        self._connected_event = Event()
+        self._is_connected = False
+
+        self._socket.add_pre_pipe_connect_cb(self._on_pipe_connect)
+        self._socket.add_post_pipe_remove_cb(self._on_pipe_remove)
+
+        logger.debug(
+            "[SUBSCRIBE] dialing %s (timeout=%dms, tls=%s)",
+            url, conn_timeout_ms, bool(tls_config),
+        )
+        self._socket.dial(url, block=False)
+
+        self._pool.submit(self.run, self._socket)
+
+        return Reply(self._pool.submit(
+            _request_utils.wait_for_connection, self._connected_event,
+            conn_timeout_ms / 1000.0, lambda: self._is_connected,
+        ))
+
+    def close(self) -> None:
+        """
+        Close connection to the server and clean up resources.
+        """
+        if self._closed:
+            return
+        self._closed = True
+        logger.debug(
+            "[SUBSCRIBE] closing (state=%s, groups=%d)",
+            self._connection_state.name, len(self._subscriptions),
+        )
+
+        self._connection_state = ConnectionState.DISCONNECTING
+        if self._connected_event:
+            self._is_connected = False
+            self._connected_event.set()
+
+        if self._socket:
+            self._socket.close()
+
+        self._callback_handler.stop()
+        self._pool.shutdown(wait=True)
+
+    def run(self, socket: Sub0) -> None:
+        """
+        Main receive loop for the subscription socket.
+
+        Args:
+            socket (Sub0): The subscription socket to receive messages from.
+        """
+        # run() is submitted to the pool from connect() right after
+        # ``_connected_event`` is created, so it's guaranteed non-None.
+        assert self._connected_event is not None
+        # Wait for initial connection
+        while not self._is_connected:
+            self._connected_event.wait()  # Wait until connected
+
+            # Check if we're shutting down
+            if not self._is_connected:
+                if self._connection_state in (ConnectionState.DISCONNECTING,
+                                               ConnectionState.DISCONNECTED,
+                                               ConnectionState.CONNECTION_FAILED):
+                    return
+
+        while True:
+            try:
+                buffer = socket.recv()
+
+            except pynng.Timeout:
+                # This is normal - just continue
+                continue
+
+            except pynng.Closed:
+                break
+
+            except RuntimeError as e:
+                if "pool" in str(e).lower():
+                    break
+                logger.error("[SUBSCRIBE] RuntimeError in recv loop: %s", e)
+                continue
+
+            except Exception as e:
+                logger.error("[SUBSCRIBE] %s in recv loop: %s", type(e).__name__, e)
+                continue
+
+            # Header parsing + per-protocol routing lives in
+            # motorcortex._subscribe_dispatch so it can be unit-tested
+            # against synthetic frames.
+            _subscribe_dispatch.dispatch_frame(buffer, self._subscriptions)
+
+    def subscribe(self, param_list: List[str], group_alias: str, frq_divider: int = 1) -> Subscription:
+        """
+        Create a subscription group for a list of parameters.
+
+        Args:
+            param_list (List[str]): List of the parameters to subscribe to.
+            group_alias (str): Name of the group.
+            frq_divider (int, optional): Frequency divider for the group publish rate. Defaults to 1.
+
+        Returns:
+            Subscription: A subscription handle, which acts as a JavaScript Promise. It is resolved when the
+            subscription is ready or failed. After the subscription is ready, the handle is used to retrieve the latest data.
+        """
+        subscription = Subscription(group_alias, self._protobuf_types, frq_divider, self._pool)
+        reply = self._req.createGroup(param_list, group_alias, frq_divider)
+        reply.then(self._complete, subscription, self._socket).catch(subscription._failed)
+
+        return subscription
+
+    def unsubscribe(self, subscription: Subscription) -> "Reply[Any]":
+        """
+        Unsubscribe from the group.
+
+        Args:
+            subscription (Subscription): Subscription handle.
+
+        Returns:
+            Reply: A promise that resolves when the unsubscribe operation is complete, fails otherwise.
+        """
+        sub_id = subscription.id()
+        sub_id_buf = Subscribe._idBuf(subscription.id())
+
+        # Reachable only after connect() wired up the socket.
+        assert self._socket is not None
+
+        # stop receiving sub
+        try:
+            self._socket.unsubscribe(sub_id_buf)
+        except Exception as e:
+            logger.debug("[SUBSCRIBE] socket.unsubscribe(%d) failed: %s", sub_id, e)
+
+        # find and remove subscription
+        if sub_id in self._subscriptions:
+            sub = self._subscriptions[sub_id]
+            # stop sub update thread
+            sub.done()
+            del self._subscriptions[sub_id]
+
+        # send remove group request to the server
+        return self._req.removeGroup(subscription.alias())
+
+    def connectionState(self) -> ConnectionState:
+        """
+        Get the current connection state.
+
+        Returns:
+            ConnectionState: The current state of the subscription connection.
+        """
+        return self._connection_state
+
+    def resubscribe(self) -> None:
+        """
+        Resubscribe all current groups after a reconnect.
+        """
+        logger.debug("[SUBSCRIBE] resubscribing %d groups", len(self._subscriptions))
+        # Reachable only after a successful connect().
+        assert self._socket is not None
+        old_sub = self._subscriptions.copy()
+        self._subscriptions.clear()
+
+        for sub_id, s in old_sub.items():
+            try:
+                # unsubscribe from the old group
+                self._socket.unsubscribe(Subscribe._idBuf(s.id()))
+            except Exception as e:
+                logger.debug("[SUBSCRIBE] failed to unsubscribe old id %d: %s", sub_id, e)
+
+            # Subscriptions in ``_subscriptions`` were already completed,
+            # so ``layout()`` is non-None by construction.
+            layout = s.layout()
+            assert layout is not None
+            msg = self._req.createGroup(layout, s.alias(), s.frqDivider()).get()
+            s._updateId(msg.id)
+            self._socket.subscribe(Subscribe._idBuf(s.id()))
+            self._subscriptions[s.id()] = s
+
+    @staticmethod
+    def _idBuf(msg_id: int) -> bytes:
+        """
+        Convert a message id to a 3-byte buffer.
+
+        Args:
+            msg_id (int): The message id.
+
+        Returns:
+            bytes: The id buffer.
+        """
+        return bytes([msg_id & 0xff, (msg_id >> 8) & 0xff, (msg_id >> 16) & 0xff])
+
+    def _complete(self, msg: Any, subscription: Subscription, socket: Sub0) -> None:
+        """
+        Complete the subscription setup after receiving a reply from the server.
+
+        Args:
+            msg (Any): The reply message from the server.
+            subscription (Subscription): The subscription object.
+            socket (Sub0): The subscription socket.
+        """
+        if subscription._complete(msg):
+            id_buf = Subscribe._idBuf(msg.id)
+            socket.subscribe(id_buf)
+            self._subscriptions[msg.id] = subscription
+        else:
+            logger.debug(
+                "[SUBSCRIBE] failed to complete group %r (id=%d)",
+                subscription.alias(), msg.id,
+            )