pycyphal2 2.0.0.dev0__py3-none-any.whl → 2.0.0.dev1__py3-none-any.whl

pycyphal2/__init__.py

@@ -1,9 +1,20 @@
 """
-`Cyphal <https://opencyphal.org>`_ in Python —
+[Cyphal](https://opencyphal.org) in Python —
 decentralized real-time pub/sub with tunable reliability, service discovery, and zero configuration.
-Works anywhere, `even baremetal MCUs <https://github.com/OpenCyphal-Garage/cy>`_.
+Works anywhere, [including baremetal MCUs](https://github.com/OpenCyphal-Garage/cy).
 
 Supports various transports such as Ethernet (UDP) and CAN FD with optional redundancy.
+
+## Installation
+
+Optional features inside the brackets can be removed if not needed; see `pyproject.toml` for the full list:
+
+```
+pip install pycyphal2[udp,pythoncan]
+```
+
+## Usage
+
 Set up a transport, make a node, publish and subscribe:
 
 ```python
@@ -25,22 +36,46 @@ All public symbols live at the top level — just `import pycyphal2`.
 Transport modules (`pycyphal2.udp`, `pycyphal2.can`) are imported separately
 so that only the needed dependencies are pulled in.
 
-The source repository contains a collection of runnable examples.
+### Name resolution
 
-Environment variables control name remapping similar to ROS:
+The topic naming system shares many similarities with ROS.
+A valid name contains printable ASCII characters except space (ASCII codes [33, 126]).
+Normalized names do not have leading or trailing segment separators `/` and do not have consecutive separators.
+Every node should have a unique name, which is called its *home*; home substitution is done via `~/`.
+
+| Input name        | Namespace | Home | Remap              | Resolved name         | Note                             |
+| ----------------- | --------- | ---- | ------------------ | --------------------- | -------------------------------- |
+| `foo/bar`         | `ns`      | `me` |                    | `ns/foo/bar`          | Relative name                    |
+| `/foo//bar/`      | `ns`      | `me` |                    | `foo/bar`             | Absolute name; namespace ignored |
+| `~/foo/bar`       | `ns`      | `me` |                    | `me/foo/bar`          | Homeful name                     |
+| `sensor/*/temp`   | `diag`    | `me` |                    | `diag/sensor/*/temp`  | Pattern with `*`                 |
+| `/sensor/>`       | `diag`    | `me` |                    | `sensor/>`            | Pattern with trailing `>`        |
+| `foo/bar`         | `ns`      | `me` | `foo/bar=~/zoo`    | `me/zoo`              | Remap first, then resolve        |
+
+Only exact `~` or `~/...` is homeful; `~ns` is literal. A matching remap overrides pinning.
+Pins are allowed only on verbatim names, not on patterns.
+
+Environment variables that control name remapping:
 
 - `CYPHAL_NAMESPACE` — default namespace prepended to relative topic names.
 - `CYPHAL_REMAP` — topic name remappings (`from=to` pairs, whitespace-separated).
 
-Publication is best-effort by default. Pass ``reliable=True`` when publishing to retry delivery until
+See also :meth:`Node.remap`.
+
+### Publish
+
+Publication is best-effort by default. Pass `reliable=True` when publishing to retry delivery until
 acknowledged by every known subscriber or until the deadline; if the remote side does not acknowledge in time,
 :class:`DeliveryError` is raised.
 
 ```python
+pub = node.advertise("sensor/temperature")
 await pub(Instant.now() + 1.0, b"payload", reliable=True)
 ```
 
-Subscriptions normally yield messages as soon as they arrive. Set ``reordering_window`` [seconds] on
+### Subscribe
+
+Subscriptions normally yield messages as soon as they arrive. Set `reordering_window` [seconds] on
 :meth:`Node.subscribe` to allow delaying out-of-order messages to reconstruct the original publication order.
 This is useful for sensor feeds and state estimators.
 
@@ -48,6 +83,20 @@ This is useful for sensor feeds and state estimators.
 sub = node.subscribe("sensor/temperature", reordering_window=0.1)
 ```
 
+Pattern matching is supported: use `*` to match one name segment (e.g., `sensor/*/temperature`)
+and a trailing `>` to match zero or more trailing segments (e.g., `sensor/>`).
+Pattern subscribers automatically join matching topics as they appear, and unsubscribe as they disappear.
+
+```python
+sub = node.subscribe("sensor/*/temperature")
+async for arrival in sub:
+    topic = arrival.breadcrumb.topic
+    captures = sub.substitutions(topic)
+    print(topic.name, captures)  # [('engine', 1)], where 1 is the pattern segment index
+```
+
+### RPC & streaming
+
 RPC is layered directly on top of pub/sub. Use :meth:`Publisher.request` to publish a message that expects
 responses, and use :attr:`Arrival.breadcrumb` on the subscriber side to send a unicast reply back to the requester.
 One request may yield responses from multiple subscribers.
@@ -66,8 +115,33 @@ await arrival.breadcrumb(Instant.now() + 1.0, b"chunk-1", reliable=True)
 await arrival.breadcrumb(Instant.now() + 1.0, b"chunk-2", reliable=True)
 ```
 
+### Topic pinning
+
+Topics may be pinned to a specific subject-ID using `name#1234` to bypass automatic assignment.
+This is useful for applications where a high degree of determinism is required and for Cyphal/CAN v1.0 interoperability.
+Pattern names (e.g., `sensor/*/temperature/>`) cannot be pinned.
+
+To join a Cyphal/CAN v1.0 subject, use topic name of the form `subject_id#subject_id`; e.g., `7509#7509`.
+
+```python
+pub = node.advertise("motor/status#1234")
+sub = node.subscribe("1234#1234")
+```
+
+Old Cyphal/CAN v1.0 nodes do not participate in the topic discovery protocol,
+so topics joined only by such nodes are not discoverable by pattern subscribers.
+
+## Remarks
+
 Cyphal does not define a serialization format. Previous versions used to define the DSDL format but it has been
 extracted into an independent project, and Cyphal was made serialization-agnostic in v1.1+.
+
+PyCyphal v2 is published on PyPI as [`pycyphal2`](https://pypi.org/project/pycyphal2/)
+to enable coexistence with the original [`pycyphal` v1](https://pypi.org/project/pycyphal/)
+in the same Python environment.
+The two packages have radically different APIs but are wire-compatible on Cyphal/CAN.
+The maintenance of the original `pycyphal` package will eventually cease;
+existing applications leveraging `pycyphal` should upgrade to the new API of `pycyphal2`.
 """
 
 from __future__ import annotations
@@ -77,7 +151,7 @@ from ._transport import Transport as Transport
 from ._transport import TransportArrival as TransportArrival
 from ._transport import SubjectWriter as SubjectWriter
 
-__version__ = "2.0.0.dev0"
+__version__ = "2.0.0.dev1"
 
 # pdoc needs __all__ to display re-exported members.
 __all__ = [

pycyphal2/_api.py

@@ -131,7 +131,6 @@ class Closable(ABC):
 class Topic(ABC):
     """
     Topics are managed automatically by the library, created and destroyed as necessary.
-    This is just a compact view to expose some auxiliary information.
     """
 
     @property
@@ -144,6 +143,16 @@ class Topic(ABC):
     def name(self) -> str:
         raise NotImplementedError
 
+    @property
+    @abstractmethod
+    def evictions(self) -> int:
+        raise NotImplementedError
+
+    @abstractmethod
+    def subject_id(self, modulus: int) -> int:
+        """The modulus can be obtained from :attr:`Transport.subject_id_modulus`."""
+        raise NotImplementedError
+
     @abstractmethod
     def match(self, pattern: str) -> list[tuple[str, int]] | None:
         """
@@ -475,6 +484,11 @@ class Node(Closable, ABC):
     def namespace(self) -> str:
         raise NotImplementedError
 
+    @property
+    @abstractmethod
+    def transport(self) -> Transport:
+        raise NotImplementedError
+
     @abstractmethod
     def remap(self, spec: str | dict[str, str]) -> None:
         """

pycyphal2/_node.py

@@ -306,6 +306,7 @@ class _TopicFlyweight(Topic):
 
     _topic_hash: int
     _name: str
+    _evictions: int
 
     @property
     def hash(self) -> int:
@@ -315,6 +316,13 @@ class _TopicFlyweight(Topic):
     def name(self) -> str:
         return self._name
 
+    @property
+    def evictions(self) -> int:
+        return self._evictions
+
+    def subject_id(self, modulus: int) -> int:
+        return compute_subject_id(self._topic_hash, self._evictions, modulus)
+
     def match(self, pattern: str) -> list[tuple[str, int]] | None:
         return match_pattern(pattern, self._name)
 
@@ -364,7 +372,7 @@ class TopicImpl(Topic):
         self._node = node
         self._name = name
         self._topic_hash = rapidhash(name)
-        self.evictions = evictions
+        self._evictions = evictions
         self.ts_origin = now
         self.ts_animated = now
         self._pub_tag_baseline = int.from_bytes(os.urandom(8), "little")
@@ -392,14 +400,20 @@ class TopicImpl(Topic):
     def name(self) -> str:
         return self._name
 
+    @property
+    def evictions(self) -> int:
+        return self._evictions
+
+    def set_evictions(self, evictions: int) -> None:
+        self._evictions = evictions
+
+    def subject_id(self, modulus: int) -> int:
+        return compute_subject_id(self._topic_hash, self._evictions, modulus)
+
     def match(self, pattern: str) -> list[tuple[str, int]] | None:
         return match_pattern(pattern, self._name)
 
     # -- Internal --
-    @property
-    def subject_id(self) -> int:
-        return compute_subject_id(self._topic_hash, self.evictions, self._node.transport.subject_id_modulus)
-
     def lage(self, now: float) -> int:
         return log_age(self.ts_origin, now)
 
@@ -426,14 +440,14 @@ class TopicImpl(Topic):
 
     def ensure_writer(self) -> SubjectWriter:
         if self.pub_writer is None:
-            sid = self.subject_id
+            sid = self.subject_id(self._node.transport.subject_id_modulus)
             self.pub_writer = self._node.acquire_subject_writer(self, sid)
             _logger.info("Writer acquired for '%s' sid=%d", self._name, sid)
         return self.pub_writer
 
     def ensure_listener(self) -> None:
         if self.sub_listener is None and self.couplings:
-            sid = self.subject_id
+            sid = self.subject_id(self._node.transport.subject_id_modulus)
             self.sub_listener = self._node.acquire_subject_listener(self, sid)
             _logger.info("Listener acquired for '%s' sid=%d", self._name, sid)
 
@@ -441,12 +455,12 @@ class TopicImpl(Topic):
         if self.couplings:
             self.ensure_listener()
         elif self.sub_listener is not None:
-            self._node.release_subject_listener(self, self.subject_id)
+            self._node.release_subject_listener(self, self.subject_id(self._node.transport.subject_id_modulus))
             self.sub_listener = None
             _logger.info("Listener released for '%s'", self._name)
 
     def release_transport_handles(self) -> None:
-        sid = self.subject_id
+        sid = self.subject_id(self._node.transport.subject_id_modulus)
         if self.pub_writer is not None:
             self._node.release_subject_writer(self, sid)
             self.pub_writer = None
@@ -487,7 +501,7 @@ def left_wins(l_lage: int, l_hash: int, r_lage: int, r_hash: int) -> bool:
 
 class NodeImpl(Node):
     def __init__(self, transport: Transport, *, home: str, namespace: str) -> None:
-        self.transport = transport
+        self._transport = transport
         self._home = home
         self._namespace = namespace
         self._remaps: dict[str, str] = {}
@@ -555,6 +569,10 @@ class NodeImpl(Node):
     def namespace(self) -> str:
         return self._namespace
 
+    @property
+    def transport(self) -> Transport:
+        return self._transport
+
     def remap(self, spec: str | dict[str, str]) -> None:
         if isinstance(spec, str):
             spec = dict(x.split("=", 1) for x in spec.split() if "=" in x)
@@ -573,7 +591,12 @@ class NodeImpl(Node):
         topic.pub_count += 1
         topic.sync_implicit()
         topic.ensure_writer()
-        _logger.info("Advertise '%s' -> '%s' sid=%d", name, resolved, topic.subject_id)
+        _logger.info(
+            "Advertise '%s' -> '%s' sid=%d",
+            name,
+            resolved,
+            topic.subject_id(self.transport.subject_id_modulus),
+        )
         return PublisherImpl(self, topic)
 
     def subscribe(self, name: str, *, reordering_window: float | None = None) -> Subscriber:
@@ -662,29 +685,34 @@ class NodeImpl(Node):
             self.couple_topic_root(topic, root)
         topic.sync_listener()
         self.notify_implicit_gc()
-        _logger.info("Topic created '%s' hash=%016x sid=%d", name, topic.hash, topic.subject_id)
+        _logger.info(
+            "Topic created '%s' hash=%016x sid=%d",
+            name,
+            topic.hash,
+            topic.subject_id(self.transport.subject_id_modulus),
+        )
         return topic
 
     def topic_allocate(self, topic: TopicImpl, new_evictions: int, now: float) -> None:
         """Iterative subject-ID allocation with collision resolution. Mirrors topic_allocate() in cy.c."""
         # Work queue: list of (topic, new_evictions) pairs to process.
+        modulus = self.transport.subject_id_modulus
         work: list[tuple[TopicImpl, int]] = [(topic, new_evictions)]
         while work:
             t, ev = work.pop(0)
             # Remove from subject-ID index first.
-            old_sid = t.subject_id
+            old_sid = t.subject_id(modulus)
             if old_sid in self.topics_by_subject_id and self.topics_by_subject_id[old_sid] is t:
                 del self.topics_by_subject_id[old_sid]
 
             if ev >= EVICTIONS_PINNED_MIN:
                 # Pinned topic: no collision detection, shared subject-IDs are fine.
                 t.release_transport_handles()
-                t.evictions = ev
+                t.set_evictions(ev)
                 t.sync_listener()
                 self.schedule_gossip_urgent(t)
                 continue
 
-            modulus = self.transport.subject_id_modulus
             new_sid = compute_subject_id(t.hash, ev, modulus)
             collider = self.topics_by_subject_id.get(new_sid)
 
@@ -694,14 +722,14 @@ class NodeImpl(Node):
             if collider is None:
                 # No collision, install.
                 t.release_transport_handles()
-                t.evictions = ev
+                t.set_evictions(ev)
                 self.topics_by_subject_id[new_sid] = t
                 t.sync_listener()
                 self.schedule_gossip_urgent(t)
             elif left_wins(t.lage(now), t.hash, collider.lage(now), collider.hash):
                 # Our topic wins: take the slot, evict the collider.
                 t.release_transport_handles()
-                t.evictions = ev
+                t.set_evictions(ev)
                 del self.topics_by_subject_id[new_sid]
                 self.topics_by_subject_id[new_sid] = t
                 if collider.pub_writer is not None:
@@ -1293,7 +1321,7 @@ class NodeImpl(Node):
             self._notify_monitors(topic)
         else:
             self.on_gossip_unknown(hdr.topic_hash, hdr.topic_evictions, hdr.topic_log_age, ts)
-            self._notify_monitors(_TopicFlyweight(hdr.topic_hash, name))
+            self._notify_monitors(_TopicFlyweight(hdr.topic_hash, name, hdr.topic_evictions))
 
     def on_gossip_known(
         self,
@@ -1430,7 +1458,7 @@ class NodeImpl(Node):
             self.decouple_topic_root(topic, topic.couplings[0].root, sync_lifecycle=False)
         self.topics_by_name.pop(name, None)
         self.topics_by_hash.pop(topic.hash, None)
-        sid = topic.subject_id
+        sid = topic.subject_id(self.transport.subject_id_modulus)
         if self.topics_by_subject_id.get(sid) is topic:
             del self.topics_by_subject_id[sid]
         topic.associations.clear()

pycyphal2/can/__init__.py

@@ -12,7 +12,7 @@ transport = CANTransport.new(SocketCANInterface("can0"))
 ```
 
 Python-CAN is useful when the application runs not on GNU/Linux or already uses `python-can` or needs
-`one of its *many* hardware backends <https://python-can.readthedocs.io/en/stable/interfaces.html>`_
+[one of its *many* hardware backends](https://python-can.readthedocs.io/en/stable/interfaces.html)
 -- GS-USB, SLCAN, PCAN, etc:
 
 ```python

{pycyphal2-2.0.0.dev0.dist-info → pycyphal2-2.0.0.dev1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycyphal2
-Version: 2.0.0.dev0
+Version: 2.0.0.dev1
 Summary: Pure-Python implementation of Cyphal -- a simple and robust real-time publish/subscribe stack that runs anywhere.
 Author-email: Pavel Kirienko and OpenCyphal team <pavel@opencyphal.org>
 License: MIT
@@ -38,6 +38,7 @@ _pub/sub without steroids_
 
 [![Website](https://img.shields.io/badge/website-opencyphal.org-black?color=1700b3)](https://opencyphal.org/)
 [![Forum](https://img.shields.io/discourse/https/forum.opencyphal.org/users.svg?logo=discourse&color=1700b3)](https://forum.opencyphal.org)
+[![PyPI](https://img.shields.io/pypi/v/pycyphal2.svg)](https://pypi.org/project/pycyphal2/)
 [![Docs](https://img.shields.io/badge/Docs-rtfm-black?color=ff00aa&logo=readthedocs)](https://opencyphal.github.io/pycyphal)
 
 </div>
@@ -46,12 +47,10 @@ _pub/sub without steroids_
 
 Python implementation of the [Cyphal](https://opencyphal.org) stack that runs on GNU/Linux, Windows, and macOS.
 
-Install as follows.
-Optional features inside the brackets can be removed if not needed; see `pyproject.toml` for the full list:
-
-```
-pip install pycyphal2[udp,pythoncan]
-```
+PyCyphal v2 is published on PyPI as `pycyphal2` to enable coexistence with v1 `pycyphal` in the same Python environment.
+The two packages have radically different APIs but are wire-compatible on Cyphal/CAN.
+The maintenance of the original `pycyphal` package will eventually cease;
+existing applications leveraging `pycyphal` should upgrade to the new API of `pycyphal2`.
 
 📚 **Read the docs** at <https://opencyphal.github.io/pycyphal>.
 

{pycyphal2-2.0.0.dev0.dist-info → pycyphal2-2.0.0.dev1.dist-info}/RECORD

@@ -1,22 +1,22 @@
-pycyphal2/__init__.py,sha256=iFtaeiu8ETt9j2SISzkABbSIO_nu0VfMOn0YFVyU0wg,3385
-pycyphal2/_api.py,sha256=z4vbensO4RJbtCt0og1pd29dQNrFeE5NHku0832lRnU,22363
+pycyphal2/__init__.py,sha256=nxnNW6FRdNG9SkboIR3MvzZMmWi4IWw_iOq_0dSuvuA,6780
+pycyphal2/_api.py,sha256=fYtM9J0RmaEp30iSzebi6a0kLeINPRM0UvvAjevEV6E,22688
 pycyphal2/_hash.py,sha256=qdQ3A35oFy5mxPNO873OlLntVsCuOak6ckJf8r5j254,10621
 pycyphal2/_header.py,sha256=12r_jQQ1t3rrNG6si5C3-vNcUSkvYQCBo8YhG16g19Q,10448
-pycyphal2/_node.py,sha256=lzfUP0AAEsRyQDz8EgG1rmnzP72i4op2SjMuhtBHOvc,56717
+pycyphal2/_node.py,sha256=8MOV6GoROC55bczN8kcYi19IrdD4UF-U7mUaTAaPCJQ,57586
 pycyphal2/_publisher.py,sha256=e8ydodDeLTqrgeNnBj4hjz2gWqkGgODmUGER9YgyY10,15868
 pycyphal2/_subscriber.py,sha256=_BOeyjzSJel58GYRlfud0qpilFuaZEgBzBCGRFf4NtI,15721
 pycyphal2/_transport.py,sha256=C0-hMukqJ_wUbNkXMBpMSp78Rf9FE7rcBfZpLDMkNF4,3492
 pycyphal2/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pycyphal2/udp.py,sha256=xGrXQZQf-Tqo6em2rBxUTn373HYhaqb0B5nsf0b6SLQ,42389
-pycyphal2/can/__init__.py,sha256=n3zuGYPexGQSZdlNulNQyYk8WphmoQhmlIeEBn5QMeQ,1555
+pycyphal2/can/__init__.py,sha256=db9Miv0bKV591WiajAVijef2x7J5Y9-gu0G2mm7hHU4,1553
 pycyphal2/can/_interface.py,sha256=u2YmS-fUkThE75IRKmF_VoA_YCTMM4ADkfMAi25cOQY,4369
 pycyphal2/can/_reassembly.py,sha256=tDh0LubxANkOVIRCHG6zbABJEQD7WegxQS-UPqg__6E,5682
 pycyphal2/can/_transport.py,sha256=sWNoyUnVJnUuhQ8pEtzAkfJSuqvI0RzMVVDKA5j1NOk,21036
 pycyphal2/can/_wire.py,sha256=OSStXci7qzwnbz0YZ0H07rNU5bdi5fCLRNKVZmDOtdw,13696
 pycyphal2/can/pythoncan.py,sha256=-zgFhoKDvihlRpVZg3OV12ClBTsf5MNLf1eD9_HxDus,10845
 pycyphal2/can/socketcan.py,sha256=nBYzbAcoVXeGoRrovpJnCbTqs4MBabpt27QJw4JqUYc,8529
-pycyphal2-2.0.0.dev0.dist-info/licenses/LICENSE,sha256=ILoAsB6eavnHqYkHMZt5JIp4-2oIMglw7vQr2aizB8w,1101
-pycyphal2-2.0.0.dev0.dist-info/METADATA,sha256=e9IVFZLWa--8ZuOCsGNTaTtC1r4Y3-ONUeIGPe563V0,2313
-pycyphal2-2.0.0.dev0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-pycyphal2-2.0.0.dev0.dist-info/top_level.txt,sha256=m3-ZKFH4OwPKxa94jzEP4OCKx7B7qnONx3GYXgaw8BU,10
-pycyphal2-2.0.0.dev0.dist-info/RECORD,,
+pycyphal2-2.0.0.dev1.dist-info/licenses/LICENSE,sha256=ILoAsB6eavnHqYkHMZt5JIp4-2oIMglw7vQr2aizB8w,1101
+pycyphal2-2.0.0.dev1.dist-info/METADATA,sha256=QoXOiDmVMmg9p4swuXqlFSpeBSAApWNC_HmenAI7xok,2602
+pycyphal2-2.0.0.dev1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pycyphal2-2.0.0.dev1.dist-info/top_level.txt,sha256=m3-ZKFH4OwPKxa94jzEP4OCKx7B7qnONx3GYXgaw8BU,10
+pycyphal2-2.0.0.dev1.dist-info/RECORD,,