motorcortex-python 1.0.0rc1__py3-none-any.whl

motorcortex/subscription.py

@@ -0,0 +1,414 @@
+#!/usr/bin/python3
+
+#
+#   Developer: Alexey Zakharov (alexey.zakharov@vectioneer.com)
+#   All rights reserved. Copyright (c) 2016-2026 VECTIONEER.
+#
+
+import warnings
+from collections import namedtuple
+from struct import unpack_from
+from concurrent.futures import Future
+import time
+from typing import Any, Callable, List, Optional, Union
+from motorcortex.timespec import Timespec
+
+
+# Default wait when the caller passes neither ``timeout_sec`` nor
+# ``timeout_ms``. Kept at 1 s for backwards compatibility with the
+# pre-T1.2 signature ``def get(self, timeout_sec: float = 1.0)``.
+_DEFAULT_TIMEOUT_SEC = 1.0
+
+# timespec = namedtuple('timespec', 'sec, nsec')
+
+
+Parameter = namedtuple('Parameter', 'timestamp, value')
+
+
+class Subscription(object):
+    """
+    Represents a subscription to a group of parameters in Motorcortex.
+
+    The Subscription class allows you to:
+    - Access the latest values and timestamps for a group of parameters.
+    - Poll for updates or use observer callbacks for real-time notifications.
+    - Chain asynchronous operations using `then` and `catch` (promise-like interface).
+
+    Attributes:
+        group_alias (str): Alias for the parameter group.
+        protobuf_types (Any): Protobuf type definitions.
+        frq_divider (int): Frequency divider for the group.
+        pool (Any): Thread or process pool for observer callbacks.
+
+    Methods:
+        id() -> int
+            Returns the subscription identifier.
+
+        alias() -> str
+            Returns the group alias.
+
+        frqDivider() -> int
+            Returns the frequency divider of the group.
+
+        read() -> Optional[List[Parameter]]
+            Returns the latest values of the parameters in the group.
+
+        layout() -> Optional[List[str]]
+            Returns the ordered list of parameter paths in the group.
+
+        done() -> bool
+            Returns True if the subscription is finished or cancelled.
+
+        get(timeout_sec: float = 1.0) -> Optional[Any]
+            Waits for the subscription to complete, returns the result or None on timeout.
+
+        then(subscribed_clb: Callable[[Any], None]) -> Subscription
+            Registers a callback for successful subscription completion.
+
+        catch(failed: Callable[[], None]) -> Subscription
+            Registers a callback for subscription failure.
+
+        notify(observer_list: Union[Callable, List[Callable]]) -> None
+            Registers observer(s) to be notified on every group update.
+
+    Examples:
+        >>> # Make sure you have a valid connection
+        >>> subscription = sub.subscribe(paths, "group1", 100)
+        >>> result = subscription.get()
+        >>> if result is not None and result.status == motorcortex.OK:
+        ...     print(f"Subscription successful, layout: {subscription.layout()}")
+        ... else:
+        ...     print(f"Subscription failed. Check parameter paths: {paths}")
+        ...     sub.close()
+        ...     exit()
+        >>> # Use promise-like interface
+        >>> subscription.then(lambda res: print("Subscribed:", res)).catch(lambda: print("Failed"))
+        >>> # Use observer for real-time updates
+        >>> def on_update(parameters):
+        ...     for param in parameters:
+        ...         timestamp = param.timestamp.sec + param.timestamp.nsec * 1e-9
+        ...         print(f"Update: {timestamp:.6f}, {param.value}")
+        >>> subscription.notify(on_update)
+        >>> print("Waiting for parameter updates...")
+        >>> import time
+        >>> while True:
+        ...     time.sleep(1)
+    """
+
+    def __init__(
+            self,
+            group_alias: str,
+            protobuf_types: Any,
+            frq_divider: int,
+            pool: Any
+    ) -> None:
+        # ``_info`` is the server's reply message (typed as ``Any`` since
+        # it's an opaque protobuf). Starts ``None``; populated by
+        # ``_complete()`` once the subscribe handshake lands. Use sites
+        # only fire after ``_is_complete`` is True, so the value is safe
+        # to access without a guard — the typed-as-Any gives up the mypy
+        # Optional check, which is fine here (the field's real type is
+        # dynamic anyway).
+        self._info: Any = None
+        self._group_alias: str = group_alias
+        self._protobuf_types: Any = protobuf_types
+        self._decoder: List[Any] = []
+        self._future: Future = Future()
+        # ``_values`` / ``_layout`` default to empty lists so indexing
+        # and slicing are type-safe. ``read()`` / ``layout()`` still
+        # return ``Optional`` by gating on ``_is_complete``, preserving
+        # the public "None until ready" contract.
+        self._values: List["Parameter"] = []
+        self._layout: List[str] = []
+        self._is_complete: bool = False
+        self._observer_list: List[Callable[[List["Parameter"]], None]] = []
+        self._pool: Any = pool
+        self._frq_divider: int = frq_divider
+        self._dropped_frames: int = 0
+
+    def __repr__(self) -> str:
+        return (
+            f"Subscription(alias={self._group_alias!r}, "
+            f"frq_divider={self._frq_divider!r}, "
+            f"layout_size={len(self._layout)}, "
+            f"done={self._future.done()}, "
+            f"dropped={self._dropped_frames})"
+        )
+
+    def id(self) -> int:
+        """
+            Returns:
+                int: subscription identifier
+        """
+        return self._info.id
+
+    def alias(self) -> str:
+        """
+            Returns:
+                str: group alias
+        """
+        return self._group_alias
+
+    def frqDivider(self) -> int:
+        """
+            Returns:
+                int: frequency divider of the group
+        """
+        return self._frq_divider
+
+    def read(self) -> Optional[List["Parameter"]]:
+        """Read the latest values of the parameters in the group.
+
+            Returns:
+                list of Parameter: list of parameters
+        """
+        return self._values[:] if self._is_complete else None
+
+    def layout(self) -> Optional[List[str]]:
+        """Get a layout of the group.
+
+            Returns:
+                list of str: ordered list of the parameters in the group
+        """
+        return self._layout[:] if self._is_complete else None
+
+    def done(self) -> bool:
+        """
+            Returns:
+                bool: True if the call was successfully canceled or finished running.
+
+            Examples:
+                >>> subscription = sub.subscribe("root/logger/logOut", "log")
+                >>> while not subscription.done():
+                >>>     time.sleep(0.1)
+        """
+        return self._future.done()
+
+    def get(
+            self,
+            timeout_sec: Optional[float] = None,
+            *,
+            timeout_ms: Optional[int] = None,
+    ) -> Optional[Any]:
+        """Wait for the subscribe handshake to resolve.
+
+        Args:
+            timeout_sec: **Deprecated** (since 0.28.0, removal
+                planned for 2.0). Legacy seconds-based timeout,
+                kept as the first positional arg so existing code
+                (``subscription.get(5.0)``) keeps working. Prefer
+                ``timeout_ms`` for new code — the rest of the
+                library is ms-based (see ARCHITECTURE.md §2a).
+                Explicit use emits a ``DeprecationWarning``.
+            timeout_ms: Timeout in milliseconds (keyword-only).
+
+        Returns:
+            The subscribe-reply message on success, ``None`` on timeout.
+
+        Examples:
+            >>> subscription = sub.subscribe("root/logger/logOut", "log")
+            >>> msg = subscription.get(timeout_ms=2000)
+        """
+        if timeout_ms is not None:
+            return self._future.result(timeout_ms / 1000.0)
+
+        if timeout_sec is not None:
+            warnings.warn(
+                "Subscription.get(timeout_sec=...) is deprecated; "
+                "use timeout_ms= instead. timeout_sec will be removed "
+                "in motorcortex-python 2.0.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return self._future.result(timeout_sec)
+
+        return self._future.result(_DEFAULT_TIMEOUT_SEC)
+
+    def then(self, subscribed_clb: Callable[[Any], None]) -> "Subscription":
+        """JavaScript-like promise, which is resolved when the subscription is completed.
+
+            Args:
+                subscribed_clb: callback which is resolved when the subscription is completed.
+
+            Returns:
+                self pointer to add 'catch' callback
+
+            Examples:
+                >>> subscription = sub.subscribe("root/logger/logOut", "log")
+                >>> subscription.then(lambda val: print("got: %s"%val)).catch(lambda d: print("failed"))
+        """
+
+        self._future.add_done_callback(
+            lambda msg: subscribed_clb(msg.result()) if msg.result() else None
+        )
+        return self
+
+    def catch(self, failed: Callable[[], None]) -> "Subscription":
+        """JavaScript-like promise, which is resolved when subscription has failed.
+
+            Args:
+                failed: callback which is resolved when the subscription has failed
+
+            Returns:
+                self pointer to add 'then' callback
+
+            Examples:
+                >>> subscription = sub.subscribe("root/logger/logOut", "log")
+                >>> subscription.catch(lambda d: print("failed")).then(lambda val: print("got: %s"%val))
+        """
+
+        self._future.add_done_callback(
+            lambda msg: failed() if not msg.result() else None
+        )
+        return self
+
+    def notify(self, observer_list: Union[
+        Callable[[List["Parameter"]], None], List[Callable[[List["Parameter"]], None]]]) -> None:
+        """Set an observer, which is notified on every group update.
+
+            Args:
+                observer_list: a callback function (or list of callback functions)
+                to notify when new values are available
+
+            Examples:
+                  >>> def update(parameters):
+                  >>>   print(parameters) #list of Parameter tuples
+                  >>> ...
+                  >>> data_sub.notify(update)
+
+        """
+        # Narrow the union properly so mypy can pick the right branch
+        # — ``type(x) is list`` is opaque to the type checker.
+        if isinstance(observer_list, list):
+            self._observer_list = observer_list
+        else:
+            self._observer_list = [observer_list]
+
+    def _complete(self, msg: Any) -> bool:
+        """Marks the subscription as complete and initializes decoders.
+
+            Args:
+                msg: Protobuf message containing subscription info.
+                
+            Returns:
+                bool: True if completed successfully, False otherwise.
+        """
+        self._decoder = []
+        self._values = []
+        self._layout = []
+        if msg.status == 0:
+            self._info = msg
+            for param in msg.params:
+                data_type = param.info.data_type
+                self._decoder.append(self._protobuf_types.getTypeByHash(data_type))
+                self._values.append(Parameter(Timespec(0, 0), [0] * param.info.number_of_elements))
+                self._layout.append(param.info.path)
+
+            self._is_complete = True
+            self._future.set_result(msg)
+            return True
+        else:
+            self._failed()
+
+        return False
+
+    def _updateId(self, new_id: int) -> None:
+        """Updates the subscription identifier.
+
+            Args:
+                new_id: New subscription identifier.
+        """
+        self._info.id = new_id
+
+    def _decode_frame(self, counter: int, value_bytes: bytes, timestamp: Timespec) -> None:
+        """Decode one parameter's value bytes and store the result.
+
+        Shared tail of both protocol paths — the only difference
+        between protocol 0 and protocol 1 is where ``timestamp`` and
+        ``value_bytes`` come from; from here on the work is identical.
+        """
+        param = self._info.params[counter]
+        value = self._decoder[counter].decode(
+            value_bytes, len(value_bytes) / param.info.data_size,
+        )
+        self._values[counter] = Parameter(timestamp, value)
+
+    def _notify_observers(self) -> None:
+        """Snapshot current values and fan out to observers via the pool."""
+        if not self._observer_list:
+            return
+        snapshot = self._values[:]
+        for observer in self._observer_list:
+            self._pool.submit(observer, snapshot)
+
+    def _updateProtocol0(self, sub_msg: bytes, length: int) -> None:
+        """Updates the subscription values using protocol version 0
+        (per-param 16-byte timestamp prepended to every payload).
+
+            Args:
+                sub_msg: Subscription message bytes.
+                length: Length of the subscription message.
+        """
+        if not sub_msg:
+            return
+        n_params = len(self._info.params)
+        for counter, param in enumerate(self._info.params):
+            offset = param.offset
+            size = param.size
+
+            # the last element in the group may have a variable size
+            if counter + 1 == n_params and (offset + size) > length:
+                size = length - offset
+
+            # Each frame is 16B timestamp + payload. Require both the
+            # full frame AND enough bytes for the timestamp itself —
+            # size can be trimmed to 0 by the last-param branch above,
+            # in which case there's nothing to unpack.
+            if size < 16 or (offset + size) > length:
+                continue
+
+            timestamp = Timespec.from_iterable(unpack_from('QQ', sub_msg, offset))
+            self._decode_frame(counter, sub_msg[offset + 16: offset + size], timestamp)
+
+        self._notify_observers()
+
+    def _updateProtocol1(self, sub_msg: bytes, length: int) -> None:
+        """Updates the subscription values using protocol version 1
+        (single leading 16-byte timestamp, shared by all params)."""
+        if not sub_msg or length < 16:
+            return
+        timestamp = Timespec.from_iterable(unpack_from('QQ', sub_msg, 0))
+        n_params = len(self._info.params)
+        for counter, param in enumerate(self._info.params):
+            offset = param.offset + 16
+            size = param.size
+
+            # the last element in the group may have a variable size
+            if counter + 1 == n_params and (offset + size) > length:
+                size = length - offset
+
+            if (offset + size) > length:
+                continue
+
+            self._decode_frame(counter, sub_msg[offset: offset + size], timestamp)
+
+        self._notify_observers()
+
+    def _failed(self) -> None:
+        self._future.set_result(None)
+
+    def droppedFrameCount(self) -> int:
+        """Number of wire frames dropped by the dispatcher for this group.
+
+        Incremented when a frame carries an unrecognised protocol version
+        or is otherwise undeliverable. Exposed for diagnostics — a
+        subscription that is silently missing updates will show a rising
+        count here while its callback stays quiet.
+        """
+        return self._dropped_frames
+
+    def _recordDroppedFrame(self) -> None:
+        """Called by the dispatcher when a frame for this subscription
+        can't be decoded. Keeps the count visible to ``droppedFrameCount()``.
+        """
+        self._dropped_frames += 1

motorcortex/timespec.py

@@ -0,0 +1,173 @@
+class Timespec:
+    """
+    Represents a timestamp with seconds and nanoseconds.
+
+    Provides conversion properties for seconds, milliseconds, microseconds, and nanoseconds.
+    Prefer using this class for new code instead of standalone functions.
+    """
+
+    def __init__(self, sec: int, nsec: int):
+        self._sec = sec
+        self._nsec = nsec
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Compare two Timespec objects for equality.
+
+        Args:
+            other (object): Another Timespec instance.
+
+        Returns:
+            bool: True if both timestamps are equal, False otherwise.
+        """
+        if not isinstance(other, Timespec):
+            return NotImplemented
+        return self._sec == other._sec and self._nsec == other._nsec
+
+    def __lt__(self, other: "Timespec") -> bool:
+        return (self._sec, self._nsec) < (other._sec, other._nsec)
+
+    def __le__(self, other: "Timespec") -> bool:
+        return (self._sec, self._nsec) <= (other._sec, other._nsec)
+
+    def __add__(self, other: "Timespec") -> "Timespec":
+        total_nsec = self._nsec + other._nsec
+        total_sec = self._sec + other._sec + total_nsec // 1_000_000_000
+        total_nsec = total_nsec % 1_000_000_000
+        return Timespec(total_sec, total_nsec)
+
+    def __str__(self) -> str:
+        return f"{self._sec}s {self._nsec}ns"
+
+    def __repr__(self) -> str:
+        return f"Timespec(sec={self._sec}, nsec={self._nsec})"
+
+    @classmethod
+    def from_iterable(cls, iterable):
+        """
+        Create a Timespec instance from an iterable containing seconds and nanoseconds.
+        
+        Args:
+            iterable: An iterable with two elements: (sec, nsec).
+            
+        Returns:
+            Timespec: A new Timespec instance.
+        """
+        sec, nsec = iterable
+        return cls(sec, nsec)
+
+    @staticmethod
+    def from_msec(msec: float) -> "Timespec":
+        """
+        Create a Timespec instance from milliseconds.
+        
+        Args:
+            msec (float): Time in milliseconds.
+            
+        Returns:
+            Timespec: A new Timespec instance.
+        """
+        sec = int(msec // 1000)
+        nsec = int((msec % 1000) * 1_000_000)
+        return Timespec(sec, nsec)
+
+    @property
+    def sec(self) -> int:
+        """
+        Returns the seconds component of the timestamp.
+        """
+        return self._sec
+
+    @property
+    def nsec(self) -> int:
+        """
+        Returns the nanoseconds component of the timestamp.
+        """
+        return self._nsec
+
+    def to_tuple(self) -> tuple[int, int]:
+        """
+        Returns the timestamp as a (sec, nsec) tuple.
+        """
+        return self._sec, self._nsec
+
+
+def compare_timespec(timestamp1: Timespec, timestamp2: Timespec) -> bool:
+    """
+    Compare two timestamps.
+
+    Args:
+        timestamp1 (timespec): First timestamp to compare.
+        timestamp2 (timespec): Second timestamp to compare.
+
+    Returns:
+        bool: True if both timestamps are equal, False otherwise.
+
+    Note:
+        For new code, use Timespec.__eq__ instead.
+    """
+    return True if (timestamp1.sec == timestamp2.sec) and (timestamp1.nsec == timestamp2.nsec) else False
+
+
+def timespec_to_sec(timestamp: Timespec) -> float:
+    """
+    Convert a timestamp to seconds.
+
+    Args:
+        timestamp (timespec): Timestamp to convert.
+
+    Returns:
+        float: Time in seconds.
+
+    Note:
+        For new code, use Timespec.sec_value instead.
+    """
+    return timestamp.sec + timestamp.nsec / 1000000000.0
+
+
+def timespec_to_msec(timestamp: Timespec) -> float:
+    """
+    Convert a timestamp to milliseconds.
+
+    Args:
+        timestamp (timespec): Timestamp to convert.
+
+    Returns:
+        float: Time in milliseconds.
+
+    Note:
+        For new code, use Timespec.msec instead.
+    """
+    return timestamp.sec * 1000 + timestamp.nsec / 1000000
+
+
+def timespec_to_usec(timestamp: Timespec) -> float:
+    """
+    Convert a timestamp to microseconds.
+
+    Args:
+        timestamp (timespec): Timestamp to convert.
+
+    Returns:
+        float: Time in microseconds.
+
+    Note:
+        For new code, use Timespec.usec instead.
+    """
+    return timestamp.sec * 1000000 + timestamp.nsec / 1000
+
+
+def timespec_to_nsec(timestamp: Timespec) -> int:
+    """
+    Convert a timestamp to nanoseconds.
+
+    Args:
+        timestamp (timespec): Timestamp to convert.
+
+    Returns:
+        int: Time in nanoseconds.
+
+    Note:
+        For new code, use Timespec.nsec_value instead.
+    """
+    return timestamp.sec * 1000000000 + timestamp.nsec

motorcortex/version.py

@@ -0,0 +1 @@
+__version__ = '1.0.0rc1'

motorcortex_python-1.0.0rc1.dist-info/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright 2018 Vectioneer B.V. <info@vectioneer.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+"motorcortex" is a trademark of Vectioneer (www.vectioneer.com)