motorcortex-python 1.0.0__py3-none-any.whl

motorcortex/__init__.py

@@ -0,0 +1,362 @@
+#!/usr/bin/python3
+
+#
+#   Developer: Alexey Zakharov (alexey.zakharov@vectioneer.com)
+#   All rights reserved. Copyright (c) 2016 - 2026 VECTIONEER.
+#
+
+"""
+motorcortex-python
+
+Motorcortex is a Python library for connecting to Motorcortex servers, handling requests, subscriptions, and parameter trees.
+Provides high-level APIs for communication, login, and data exchange using protocol buffers.
+
+See documentation for usage examples.
+"""
+
+from enum import IntEnum as _IntEnum
+from typing import Any
+
+from motorcortex.version import __version__
+from motorcortex.parameter_tree import ParameterTree
+from motorcortex.message_types import MessageTypes
+from motorcortex.request import Request, ConnectionState
+from motorcortex.reply import Reply
+from motorcortex.subscribe import Subscribe
+from motorcortex.subscription import Subscription
+from motorcortex.timespec import (
+    Timespec,
+    compare_timespec,
+    timespec_to_sec,
+    timespec_to_msec,
+    timespec_to_usec,
+    timespec_to_nsec,
+)
+from motorcortex.init_threads import init_nng_threads
+from motorcortex.session import Session
+from motorcortex.exceptions import (
+    McxError,
+    McxConnectionError,
+    McxLoginError,
+    McxTimeout,
+)
+from motorcortex.motorcortex_pb2 import StatusCode as _PbStatusCode
+from motorcortex.setup_logger import logger  # not re-exported — ``__all__`` gates package surface
+
+# Build an ``IntEnum`` facade over the protobuf ``StatusCode`` enum so
+# callers can write ``motorcortex.StatusCode.OK`` without reaching into
+# the generated protobuf module. Subclassing ``int`` means comparisons
+# like ``reply.status == StatusCode.OK`` work against the raw ints that
+# come back on the wire.
+StatusCode = _IntEnum(
+    "StatusCode",
+    {v.name: v.number for v in _PbStatusCode.DESCRIPTOR.values},
+)
+StatusCode.__doc__ = (
+    "Motorcortex response status codes. Members mirror the ``StatusCode`` "
+    "enum in the wire protocol. Use ``motorcortex.StatusCode.OK`` (or the "
+    "flat re-exports such as ``motorcortex.OK``) to compare against "
+    "``reply.status``."
+)
+
+# Flat re-exports for the conventional ``motorcortex.OK`` idiom. Values
+# are members of :class:`StatusCode` and therefore also ``int``.
+OK = StatusCode.OK
+READ_ONLY_MODE = StatusCode.READ_ONLY_MODE
+FAILED = StatusCode.FAILED
+FAILED_TO_DECODE = StatusCode.FAILED_TO_DECODE
+SUB_LIST_IS_FULL = StatusCode.SUB_LIST_IS_FULL
+WRONG_PARAMETER_PATH = StatusCode.WRONG_PARAMETER_PATH
+FAILED_TO_SET_REQUESTED_FRQ = StatusCode.FAILED_TO_SET_REQUESTED_FRQ
+FAILED_TO_OPEN_FILE = StatusCode.FAILED_TO_OPEN_FILE
+GROUP_LIST_IS_FULL = StatusCode.GROUP_LIST_IS_FULL
+WRONG_PASSWORD = StatusCode.WRONG_PASSWORD
+USER_NOT_LOGGED_IN = StatusCode.USER_NOT_LOGGED_IN
+PERMISSION_DENIED = StatusCode.PERMISSION_DENIED
+
+# ``__all__`` is the 1.0 public API surface. Anything not listed here —
+# including module-level helpers defined below (``parseUrl``,
+# ``makeUrl``, ``statusToStr``) and submodule imports like
+# ``motorcortex.setup_logger`` — is implicitly private and may change
+# between minor releases. For logging, do
+# ``logging.getLogger("mcx")`` instead of reaching into the package.
+__all__ = [
+    "__version__",
+    # Entry points
+    "connect",
+    "Session",
+    # Connection / protocol classes
+    "Request",
+    "Subscribe",
+    "Subscription",
+    "Reply",
+    "ConnectionState",
+    # Protobuf / parameters
+    "MessageTypes",
+    "ParameterTree",
+    # Time
+    "Timespec",
+    "compare_timespec",
+    "timespec_to_sec",
+    "timespec_to_msec",
+    "timespec_to_usec",
+    "timespec_to_nsec",
+    # Exceptions
+    "McxError",
+    "McxConnectionError",
+    "McxLoginError",
+    "McxTimeout",
+    # Status codes
+    "StatusCode",
+    "OK",
+    "READ_ONLY_MODE",
+    "FAILED",
+    "FAILED_TO_DECODE",
+    "SUB_LIST_IS_FULL",
+    "WRONG_PARAMETER_PATH",
+    "FAILED_TO_SET_REQUESTED_FRQ",
+    "FAILED_TO_OPEN_FILE",
+    "GROUP_LIST_IS_FULL",
+    "WRONG_PASSWORD",
+    "USER_NOT_LOGGED_IN",
+    "PERMISSION_DENIED",
+    # Tuning
+    "init_nng_threads",
+]
+
+init_nng_threads()
+
+
+def parseUrl(url: str) -> tuple[str, str, int | None, int | None]:
+    """
+    Parses a Motorcortex connection URL to extract request and subscribe addresses and ports.
+
+    Args:
+        url (str): The connection URL, expected in the format 'address:req_port:sub_port'.
+
+    Returns:
+        tuple: (req_address, sub_address, req_port, sub_port)
+            - req_address (str): Address for request connection.
+            - sub_address (str): Address for subscribe connection.
+            - req_port (int or None): Port for request connection.
+            - sub_port (int or None): Port for subscribe connection.
+
+    If the URL does not contain ports, default endpoints '/mcx_req' and '/mcx_sub' are appended.
+    """
+    # IPv6 host literals embed colons (``wss://[::1]``), so the rfind-based
+    # port scan has to start *after* the closing bracket of the host
+    # literal — otherwise it walks into the address bytes and either
+    # mis-parses the ports or (in the no-ports case) tries to int() an
+    # empty slice. For IPv4 / hostname URLs there is no bracket, so
+    # ``port_start`` stays at 0 and behavior matches the pre-fix code.
+    host_end = url.rfind(']')
+    port_start = host_end + 1 if host_end != -1 else 0
+
+    end = url.rfind(':')
+    if end < port_start:
+        return url + '/mcx_req', url + '/mcx_sub', None, None
+    start = url.rfind(':', port_start, end)
+    if start == -1:
+        return url + '/mcx_req', url + '/mcx_sub', None, None
+    req_port = int(url[start + 1:end])
+    sub_port = int(url[end + 1:])
+    address = url[:start]
+    return address, address, req_port, sub_port
+
+
+def makeUrl(address: str, port: int | None) -> str:
+    """
+    Constructs a URL string from an address and port.
+
+    Args:
+        address (str): The base address.
+        port (int or None): The port number.
+
+    Returns:
+        str: The combined address and port in the format 'address:port', or just 'address' if port is None.
+    """
+    if port:
+        return "{}:{}".format(address, port)
+
+    return address
+
+
+def connect(
+        url: str,
+        motorcortex_types: "MessageTypes",
+        param_tree: "ParameterTree",
+        reconnect: bool = True,
+        **kwargs: Any,
+) -> tuple["Request", "Subscribe"]:
+    """
+    Establishes connections to Motorcortex request and subscribe endpoints, performs login, and loads the parameter tree.
+
+    Args:
+        url (str): Connection URL in the format 'address:req_port:sub_port' or 'wss://address'.
+        motorcortex_types (MessageTypes): Motorcortex message types instance.
+        param_tree (ParameterTree): ParameterTree instance to load parameters into.
+        reconnect (bool, optional): Whether to enable automatic reconnection. Defaults to True.
+        **kwargs: Additional keyword arguments:
+            login (str): Username for authentication.
+            password (str): Password for authentication.
+            certificate (str, optional): Path to a TLS certificate file for secure connections.
+            timeout_ms (int, optional): Connection timeout in milliseconds. Defaults to 1000.
+            recv_timeout_ms (int, optional): Receive timeout in milliseconds. Defaults to 500.
+            token_update_interval_ms (int, optional): Session token refresh interval in milliseconds. Defaults to 30000.
+            state_update (Callable, optional): Custom callback for connection state changes.
+                If provided, disables the built-in reconnect logic.
+            req_number_of_threads (int, optional): Thread pool size for request connection. Defaults to 2.
+            sub_number_of_threads (int, optional): Thread pool size for subscribe connection. Defaults to 2.
+
+    Returns:
+        tuple: (req, sub)
+            - req (Request): Established request connection.
+            - sub (Subscribe): Established subscribe connection.
+
+    Raises:
+        RuntimeError: If connection or login fails.
+
+    Examples:
+        >>> from motorcortex import connect, MessageTypes, ParameterTree
+        >>> types = MessageTypes()
+        >>> tree = ParameterTree()
+        >>> req, sub = connect("wss://192.168.2.100", types, tree,
+        ...                    certificate="mcx.cert.crt", timeout_ms=1000,
+        ...                    login="admin", password="admin",
+        ...                    token_update_interval_ms=15000)
+    """
+
+    token_interval_sec = kwargs.get("token_update_interval_ms", 30000) / 1000.0
+
+    initial_connect_done = [False]  # Now reconnections will trigger callback login
+
+    if reconnect and not kwargs.get("state_update"):
+
+        def stateUpdate(req, sub, state):
+            if state == ConnectionState.CONNECTION_OK and initial_connect_done[0]:
+                # Try to restore session using token, fall back to login
+                restored = False
+                if req.token:
+                    try:
+                        restore_reply = req.restoreSession(req.token)
+                        restore_msg = restore_reply.get(timeout_ms=5000)
+                        motorcortex_msg = motorcortex_types.motorcortex()
+                        if restore_msg and restore_msg.status == motorcortex_msg.OK:
+                            restored = True
+                            logger.debug("[SESSION] Session restored using token")
+                    except Exception as e:
+                        logger.debug(f"[SESSION] Token restore failed: {e}")
+
+                if not restored:
+                    logger.debug("[SESSION] Falling back to login")
+                    req.login(kwargs.get("login"), kwargs.get("password")).get()
+
+                req._startTokenRefresh(token_interval_sec)
+                sub.resubscribe()
+
+        kwargs.update(state_update=stateUpdate)
+
+    # Parse address
+    req_address, sub_address, req_port, sub_port = parseUrl(url)
+    # Open request connection
+    req = Request(motorcortex_types, param_tree, kwargs.get("req_number_of_threads", 2))
+    sub = None
+    # Wrap every post-construction failure point so half-opened sockets
+    # get closed; otherwise the Subscribe receive thread stays blocked in
+    # recv() forever and pins the Python interpreter on exit (an atexit
+    # ``_python_exit`` handler then joins the worker indefinitely).
+    try:
+        kwargs_copy = kwargs.copy()
+        kwargs_copy.update(state_update=None)
+        if not req.connect(makeUrl(req_address, req_port), **kwargs_copy).get():
+            raise McxConnectionError(
+                "Failed to establish request connection: {}:{}".format(req_address, req_port)
+            )
+        # Open subscribe connection
+        sub = Subscribe(req, motorcortex_types, kwargs.get("sub_number_of_threads", 2))
+        if not sub.connect(makeUrl(sub_address, sub_port), **kwargs).get():
+            raise McxConnectionError(
+                "Failed to establish subscribe connection: {}:{}".format(sub_address, sub_port)
+            )
+        # Login. With ``Login: disable`` servers the credentials can legitimately
+        # be omitted — default to empty strings so the helper does not raise
+        # ``KeyError`` on valid callers.
+        login_reply = req.login(kwargs.get('login', ''), kwargs.get('password', ''))
+        login_reply_msg = login_reply.get()
+
+        motorcortex_msg = motorcortex_types.motorcortex()
+        if not login_reply_msg.status == motorcortex_msg.OK:
+            raise McxLoginError(
+                "Login failed, status: {}".format(login_reply_msg.status),
+                status=login_reply_msg.status,
+            )
+
+        # Requesting a parameter tree
+        param_tree_reply = req.getParameterTree()
+        tree = param_tree_reply.get()
+        param_tree.load(tree)
+    except Exception:
+        if sub is not None:
+            try:
+                sub.close()
+            except Exception:
+                pass
+        try:
+            req.close()
+        except Exception:
+            pass
+        raise
+
+    # Start session token refresh
+    req._startTokenRefresh(token_interval_sec)
+
+    initial_connect_done[0] = True  # Now reconnections will trigger callback login
+
+    return req, sub
+
+
+def statusToStr(motorcortex_msg: Any, code: int) -> str:
+    """Converts status codes to a readable message.
+
+        Args:
+            motorcortex_msg(Module): reference to a motorcortex module
+            code(int): status code
+
+        Returns:
+            str: status message
+
+        Examples:
+            >>> login_reply = req.login("admin", "iddqd")
+            >>> login_reply_msg = login_reply.get()
+            >>> if login_reply_msg.status != motorcortex_msg.OK:
+            >>>     print(motorcortex.statusToStr(motorcortex_msg, login_reply_msg.status))
+
+    """
+
+    status = 'Unknown code'
+    if code == motorcortex_msg.OK:
+        status = 'Success'
+    elif code == motorcortex_msg.FAILED:
+        status = 'Failed'
+    elif code == motorcortex_msg.FAILED_TO_DECODE:
+        status = 'Failed to decode request'
+    elif code == motorcortex_msg.SUB_LIST_IS_FULL:
+        status = 'Failed to subscribe, subscription list is full'
+    elif code == motorcortex_msg.WRONG_PARAMETER_PATH:
+        status = 'Failed to find parameter'
+    elif code == motorcortex_msg.FAILED_TO_SET_REQUESTED_FRQ:
+        status = 'Failed to set requested frequency'
+    elif code == motorcortex_msg.FAILED_TO_OPEN_FILE:
+        status = 'Failed to open file'
+    elif code == motorcortex_msg.READ_ONLY_MODE:
+        status = 'Logged in, read-only mode'
+    elif code == motorcortex_msg.WRONG_PASSWORD:
+        status = 'Wrong login or password'
+    elif code == motorcortex_msg.USER_NOT_LOGGED_IN:
+        status = 'Operation is not permitted, user is not logged in'
+    elif code == motorcortex_msg.PERMISSION_DENIED:
+        status = 'Operation is not permitted, user has no rights'
+
+    status += str(' (%s)' % hex(code))
+
+    return status

motorcortex/_connection_state.py

@@ -0,0 +1,58 @@
+#
+#   Developer: Alexey Zakharov (alexey.zakharov@vectioneer.com)
+#   All rights reserved. Copyright (c) 2026 VECTIONEER.
+#
+
+"""Connection-state enum + pure state-transition helpers.
+
+``ConnectionState`` was historically defined in ``motorcortex.request`` and
+is still re-exported from there (and from ``motorcortex``) for backward
+compatibility. It lives here so pure helpers can depend on it without
+dragging the whole ``request`` module — which would cause a circular
+import.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ConnectionState(Enum):
+    """Enumeration of connection states.
+
+        - CONNECTING:           Connection is being established.
+        - CONNECTION_OK:        Connection is successfully established.
+        - CONNECTION_LOST:      Connection was lost.
+        - CONNECTION_FAILED:    Connection attempt failed.
+        - DISCONNECTING:        Connection is being closed.
+        - DISCONNECTED:         Connection is closed.
+    """
+    CONNECTING = 0
+    CONNECTION_OK = 1
+    CONNECTION_LOST = 2
+    CONNECTION_FAILED = 3
+    DISCONNECTING = 4
+    DISCONNECTED = 5
+
+
+def next_state_after_pipe_remove(current: ConnectionState) -> ConnectionState:
+    """Map the current state to the one we enter when the remote pipe goes away.
+
+    nng fires its post-remove callback when a peer socket is torn down, but
+    the callback itself can't tell *why*: we might have called
+    ``close()`` (clean shutdown) or the remote might have died (lost /
+    failed). The only disambiguator is the state we were already in.
+
+    Transitions:
+        DISCONNECTING    → DISCONNECTED        (clean close we initiated)
+        CONNECTING       → CONNECTION_FAILED   (never finished handshake)
+        CONNECTION_OK    → CONNECTION_LOST     (remote went away mid-session)
+        anything else    → unchanged           (idempotent / re-entry safe)
+    """
+    if current == ConnectionState.DISCONNECTING:
+        return ConnectionState.DISCONNECTED
+    if current == ConnectionState.CONNECTING:
+        return ConnectionState.CONNECTION_FAILED
+    if current == ConnectionState.CONNECTION_OK:
+        return ConnectionState.CONNECTION_LOST
+    return current

motorcortex/_request_builders.py

@@ -0,0 +1,157 @@
+#
+#   Developer: Alexey Zakharov (alexey.zakharov@vectioneer.com)
+#   All rights reserved. Copyright (c) 2026 VECTIONEER.
+#
+
+"""Pure protobuf message builders used by :class:`motorcortex.Request`.
+
+These used to be private static methods on ``Request``. Moving them to
+a free-function module so they can be unit-tested without spinning up a
+socket or stubbing the class.
+
+Everything here is side-effect-free w.r.t. the wire — the builders just
+produce protobuf messages that the caller later hands to
+``Request.send()``. They may log an error when no encoder resolves, but
+they do not touch sockets, files, or global state.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+from motorcortex.setup_logger import logger
+
+if TYPE_CHECKING:
+    from motorcortex.message_types import MessageTypes
+    from motorcortex.parameter_tree import ParameterTree
+
+
+def _resolve_encoder(
+        path: str,
+        type_name: Optional[str],
+        protobuf_types: "MessageTypes",
+        parameter_tree: "ParameterTree",
+) -> Any:
+    """Find the encoder for ``path`` — by explicit ``type_name`` first,
+    otherwise by hash looked up in the parameter tree.
+
+    Returns ``None`` when neither resolution succeeds. Callers (see
+    ``build_set_parameter_msg`` / ``build_overwrite_parameter_msg``)
+    log and fall back to sending an empty-value message, which the
+    server rejects with a clean status code — beats raising
+    ``AttributeError`` at the client on ``.encode()``.
+    """
+    if type_name:
+        return protobuf_types.createType(type_name)
+    try:
+        type_id = parameter_tree.getDataType(path)
+    except KeyError:
+        return None
+    return protobuf_types.getTypeByHash(type_id)
+
+
+def build_set_parameter_msg(
+        path: str,
+        value: Any,
+        type_name: Optional[str],
+        protobuf_types: "MessageTypes",
+        parameter_tree: "ParameterTree",
+) -> Any:
+    """``SetParameterMsg`` for a single parameter (whole-value write).
+
+    When the encoder cannot be resolved (unknown path, no ``type_name``),
+    the message is built with an empty ``value`` byte string and sent as-is
+    — the server rejects it with a proper error status, which beats
+    raising ``AttributeError`` at the client.
+    """
+    param_value = _resolve_encoder(path, type_name, protobuf_types, parameter_tree)
+    msg = protobuf_types.createType("motorcortex.SetParameterMsg")
+    msg.path = path
+    if param_value is None:
+        logger.error("No encoder for path %s (type=%s) — sending empty value", path, type_name)
+        msg.value = b""
+    else:
+        msg.value = param_value.encode(value)
+    return msg
+
+
+def build_set_parameter_with_offset_msg(
+        offset: int,
+        length: int,
+        path: str,
+        value: Any,
+        type_name: Optional[str],
+        protobuf_types: "MessageTypes",
+        parameter_tree: "ParameterTree",
+) -> Any:
+    """``SetParameterMsg`` with an ``offset`` + ``length`` slice window.
+
+    Negative offsets are clamped to zero. ``length == 0`` means "write
+    all of ``value``" and is inferred from ``len(value)`` (or 1 for
+    scalars). Unknown encoder → empty ``value``, see
+    :func:`build_set_parameter_msg`.
+    """
+    param_value = _resolve_encoder(path, type_name, protobuf_types, parameter_tree)
+
+    if offset < 0:
+        offset = 0
+    if length < 0:
+        length = 0
+    if length == 0:
+        length = len(value) if hasattr(value, "__len__") else 1
+
+    msg = protobuf_types.createType("motorcortex.SetParameterMsg")
+    msg.offset.type = 1
+    msg.offset.offset = offset
+    msg.offset.length = length
+    msg.path = path
+    if param_value is None:
+        logger.error("No encoder for path %s (type=%s) — sending empty value", path, type_name)
+        msg.value = b""
+    else:
+        msg.value = param_value.encode(value)
+    return msg
+
+
+def build_get_parameter_msg(
+        path: str,
+        protobuf_types: "MessageTypes",
+) -> Any:
+    """``GetParameterMsg`` — trivial, just carries the path."""
+    msg = protobuf_types.createType("motorcortex.GetParameterMsg")
+    msg.path = path
+    return msg
+
+
+def build_overwrite_parameter_msg(
+        path: str,
+        value: Any,
+        activate: bool,
+        type_name: Optional[str],
+        protobuf_types: "MessageTypes",
+        parameter_tree: "ParameterTree",
+) -> Any:
+    """``OverwriteParameterMsg`` — pins a value until release or deactivate.
+
+    Unknown encoder → empty ``value``, see :func:`build_set_parameter_msg`.
+    """
+    param_value = _resolve_encoder(path, type_name, protobuf_types, parameter_tree)
+    msg = protobuf_types.createType("motorcortex.OverwriteParameterMsg")
+    msg.path = path
+    msg.activate = activate
+    if param_value is None:
+        logger.error("No encoder for path %s (type=%s) — sending empty value", path, type_name)
+        msg.value = b""
+    else:
+        msg.value = param_value.encode(value)
+    return msg
+
+
+def build_release_parameter_msg(
+        path: str,
+        protobuf_types: "MessageTypes",
+) -> Any:
+    """``ReleaseParameterMsg`` — drop any active overwrite on ``path``."""
+    msg = protobuf_types.createType("motorcortex.ReleaseParameterMsg")
+    msg.path = path
+    return msg