motorcortex-python 1.0.0rc1__py3-none-any.whl

motorcortex/nng_url.py

@@ -0,0 +1,49 @@
+#!/usr/bin/python3
+
+#
+#   Developer: Alexey Zakharov (alexey.zakharov@vectioneer.com)
+#   All rights reserved. Copyright (c) 2016-2026 VECTIONEER.
+#
+
+from pynng import ffi, lib  # type: ignore[import-untyped]
+from pynng.exceptions import check_err  # type: ignore[import-untyped]
+
+
+class NngUrl:
+    """Python wrapper for nng_url."""
+
+    def __init__(self, url: str) -> None:
+        self._url_p = ffi.new("nng_url **")
+        check_err(lib.nng_url_parse(self._url_p, url.encode()))
+
+    def __del__(self) -> None:
+        if self._url_p[0] != ffi.NULL:
+            lib.nng_url_free(self._url_p[0])
+
+    @property
+    def _url(self):  # type: ignore[no-untyped-def]
+        return self._url_p[0]
+
+    @property
+    def hostname(self) -> str | None:
+        if self._url.u_hostname == ffi.NULL:
+            return None
+        return ffi.string(self._url.u_hostname).decode()
+
+    @property
+    def port(self) -> str | None:
+        if self._url.u_port == ffi.NULL:
+            return None
+        return ffi.string(self._url.u_port).decode()
+
+    def __repr__(self) -> str:
+        return (
+            f"NngUrl(scheme={self.scheme!r}, "
+            f"hostname={self.hostname!r}, port={self.port!r})"
+        )
+
+    @property
+    def scheme(self) -> str | None:
+        if self._url.u_scheme == ffi.NULL:
+            return None
+        return ffi.string(self._url.u_scheme).decode()

motorcortex/parameter_tree.py

@@ -0,0 +1,86 @@
+#!/usr/bin/python3
+
+#
+#   Developer: Alexey Zakharov (alexey.zakharov@vectioneer.com)
+#   All rights reserved. Copyright (c) 2016-2026 VECTIONEER.
+#
+
+
+from typing import Any, Dict, List, Optional
+
+
+class ParameterTree(object):
+    """
+    Represents a parameter tree, obtained from the server.
+
+    Reference to a parameter tree instance is needed for resolving parameters,
+    data types and other information to build a correct request message.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initializes an empty ParameterTree.
+        """
+        self._parameter_tree: List[Any] = []
+        self._parameter_map: Dict[str, Any] = dict()
+
+    def __repr__(self) -> str:
+        return f"ParameterTree(params={len(self._parameter_tree)})"
+
+    def load(self, parameter_tree_msg: Any) -> None:
+        """
+        Loads a parameter tree from ParameterTreeMsg received from the server.
+
+        Args:
+            parameter_tree_msg (Any): Parameter tree message from the server (should have a .params attribute).
+
+        Examples:
+            >>> parameter_tree = motorcortex.ParameterTree()
+            >>> parameter_tree_msg = param_tree_reply.get()
+            >>> parameter_tree.load(parameter_tree_msg)
+        """
+        self._parameter_tree = parameter_tree_msg.params
+        for param in self._parameter_tree:
+            self._parameter_map[param.path] = param
+
+    def getParameterTree(self) -> List[Any]:
+        """
+        Returns the list of parameter descriptions in the tree.
+
+        Returns:
+            List[Any]: A list of parameter descriptions (ParameterInfo objects).
+        """
+        return self._parameter_tree
+
+    def getInfo(self, parameter_path: str) -> Optional[Any]:
+        """
+        Get the parameter description for a given path.
+
+        Args:
+            parameter_path (str): Path of the parameter.
+
+        Returns:
+            Optional[Any]: Parameter description (ParameterInfo) if found, else None.
+        """
+        return self._parameter_map.get(parameter_path)
+
+    def getDataType(self, parameter_path: str) -> Any:
+        """
+        Get the data type for a given parameter path.
+
+        Args:
+            parameter_path (str): Path of the parameter.
+
+        Returns:
+            The parameter's data type.
+
+        Raises:
+            KeyError: if ``parameter_path`` is not in the tree. Callers
+                that want lenient "maybe" semantics should use
+                :meth:`getInfo` (returns ``Optional[Any]``) and branch
+                on ``None`` themselves.
+        """
+        info = self.getInfo(parameter_path)
+        if info is None:
+            raise KeyError(parameter_path)
+        return info.data_type

motorcortex/reply.py

@@ -0,0 +1,108 @@
+#!/usr/bin/python3
+
+#
+#   Developer: Alexey Zakharov (alexey.zakharov@vectioneer.com)
+#   All rights reserved. Copyright (c) 2016-2026 VECTIONEER.
+#
+
+
+from concurrent.futures import Future, TimeoutError as _FutureTimeout
+from typing import Any, Callable, Generic, Optional, TypeVar
+
+from motorcortex.exceptions import McxTimeout
+
+
+T = TypeVar("T")
+
+
+class Reply(Generic[T]):
+    """Reply handle is a JavaScript-like Promise, generic over the
+    message type returned by the underlying RPC.
+
+    ``Reply[T].get()`` returns ``T`` — the decoded protobuf message
+    class for the specific RPC. For example,
+    ``Request.getParameter`` returns ``Reply[ParameterMsg]``, so
+    ``req.getParameter(path).get()`` is a ``ParameterMsg`` at the
+    type-check level, not ``Any``.
+
+    Runtime behavior is unchanged — ``Reply[X]`` is a typing-time
+    construct; at runtime it is just ``Reply``. Pre-generic annotations
+    like ``reply: Reply`` still work (equivalent to ``Reply[Any]``).
+    """
+
+    def __init__(self, future: "Future[Any]") -> None:
+        self._future = future
+
+    def __repr__(self) -> str:
+        return f"Reply(done={self._future.done()})"
+
+    def get(self, timeout_ms: Optional[int] = None) -> T:
+        """A blocking call to wait for the reply and returns a value.
+
+            Args:
+                timeout_ms(integer): timeout for reply in milliseconds
+
+            Returns:
+                A protobuf message with a parameter description and value.
+
+            Raises:
+                McxTimeout: ``timeout_ms`` elapsed before the reply
+                    arrived. ``McxTimeout`` inherits ``TimeoutError``
+                    so ``except TimeoutError`` still catches it.
+
+            Examples:
+                  >>> param_tree_reply = req.getParameterTree()
+                  >>> value = param_tree_reply.get()
+
+        """
+        try:
+            return self._future.result(timeout_ms / 1000.0 if timeout_ms else None)
+        except _FutureTimeout as e:
+            # Keep the typed-exception contract from ARCHITECTURE.md §2b:
+            # reply-level timeouts raise McxTimeout, not the stdlib
+            # TimeoutError that concurrent.futures would leak.
+            raise McxTimeout(
+                f"Reply.get timed out after {timeout_ms}ms"
+            ) from e
+
+    def done(self) -> bool:
+        """
+            Returns:
+                bool: True if the call was successfully canceled or finished running.
+        """
+        return self._future.done()
+
+    def then(self, received_clb: Callable[..., Any], *args: Any, **kwargs: Any) -> "Reply[T]":
+        """JavaScript-like promise, which is resolved when a reply is received.
+
+                Args:
+                    received_clb: callback which is resolved when the reply is received.
+
+                Returns:
+                    self pointer to add 'catch' callback
+
+                Examples:
+                    >>> param_tree_reply.then(lambda reply: print("got reply: %s"%reply))
+                    >>>                 .catch(lambda g: print("failed"))
+        """
+        self._future.add_done_callback(
+            lambda msg: received_clb(msg.result(), *args, **kwargs) if msg.result() else None
+        )
+        return self
+
+    def catch(self, failed_clb: Callable[..., Any], *args: Any, **kwargs: Any) -> "Reply[T]":
+        """JavaScript-like promise, which is resolved when receive has failed.
+
+            Args:
+                failed_clb: callback which is resolved when receive has failed
+
+            Returns:
+                self pointer to add 'then' callback
+
+            Examples:
+                >>> param_tree_reply.catch(lambda g: print("failed")).then(lambda reply: print("got reply: %s"%reply))
+        """
+        self._future.add_done_callback(
+            lambda msg: failed_clb(*args, **kwargs) if not msg.result() else None
+        )
+        return self