pycyphal2 2.0.0.dev5__tar.gz → 2.0.0.dev6__tar.gz

{pycyphal2-2.0.0.dev5/src/pycyphal2.egg-info → pycyphal2-2.0.0.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycyphal2
-Version: 2.0.0.dev5
+Version: 2.0.0.dev6
 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

{pycyphal2-2.0.0.dev5 → pycyphal2-2.0.0.dev6}/src/pycyphal2/__init__.py

@@ -155,7 +155,7 @@ from ._transport import SubjectWriter as SubjectWriter
 from ._transport import Transport as Transport
 from ._transport import TransportArrival as TransportArrival
 
-__version__ = "2.0.0.dev5"
+__version__ = "2.0.0.dev6"
 
 # pdoc needs __all__ to display re-exported members.
 __all__ = [

{pycyphal2-2.0.0.dev5 → pycyphal2-2.0.0.dev6}/src/pycyphal2/_api.py

@@ -219,7 +219,7 @@ class Publisher(Closable, ABC):
     Represents the intent to send messages on a topic.
 
     Calling the publisher sends one message.
-    By default this is best-effort publication: the message is sent once and only immediate send failures are reported.
+    By default this is best-effort publication: the message is sent once and delivery is not confirmed.
     With ``reliable=True``, the library retransmits until the deadline and waits for acknowledgments from remote
     subscribers.
 
@@ -262,6 +262,9 @@ class Publisher(Closable, ABC):
         Blocks at most until ``deadline``.
         Raises :class:`SendError` if the message could not be sent before the deadline.
 
+        Returning means the message has been handed over to the network, not that anyone received it.
+        The call waits for that handover, so a congested network applies backpressure to the publisher.
+
         If ``reliable`` is false, the message is sent once.
         If ``reliable`` is true, the library retransmits until ``deadline`` leveraging :attr:`ack_timeout`.
         """
@@ -552,21 +555,17 @@ class Node(Closable, ABC):
         """
         from ._node import NodeImpl
 
-        # Add random suffix if requested or generate pure random home.
         # Leading/trailing separators will be normalized away.
         home = home.strip() or "/"
         if home.endswith("/"):
             uid = transport.uid if hasattr(transport, "uid") else eui64()
             home += f"{uid:016x}"
 
-        # Initialize the namespace: if not given explicitly, read it from the standard environment.
         namespace = namespace.strip() or os.getenv("CYPHAL_NAMESPACE", "").strip()
 
-        # Construct the node.
         node = NodeImpl(transport, home=home, namespace=namespace)
         _logger.info("Constructed %s", node)
 
-        # Set up default name remapping.
         try:
             node.remap(os.getenv("CYPHAL_REMAP", ""))
         except Exception as ex:

{pycyphal2-2.0.0.dev5 → pycyphal2-2.0.0.dev6}/src/pycyphal2/_hash.py

@@ -1,11 +1,5 @@
-"""Hash and CRC utilities"""
-
 from __future__ import annotations
 
-# =====================================================================================================================
-# CRC-32C (Castagnoli)
-# =====================================================================================================================
-
 CRC32C_INITIAL = 0xFFFFFFFF
 CRC32C_OUTPUT_XOR = 0xFFFFFFFF
 CRC32C_RESIDUE = 0x48674BC7
@@ -59,10 +53,6 @@ def crc32c_full(data: bytes | memoryview) -> int:
     return crc32c_add(CRC32C_INITIAL, data) ^ CRC32C_OUTPUT_XOR
 
 
-# =====================================================================================================================
-# CRC-16/CCITT-FALSE
-# =====================================================================================================================
-
 CRC16CCITT_FALSE_INITIAL = 0xFFFF
 CRC16CCITT_FALSE_RESIDUE = 0x0000
 # fmt: off
@@ -103,10 +93,7 @@ def crc16ccitt_false_full(data: bytes | memoryview) -> int:
     return crc16ccitt_false_add(CRC16CCITT_FALSE_INITIAL, data)
 
 
-# =====================================================================================================================
 # rapidhash V3
-# =====================================================================================================================
-
 _RAPID_MASK = 0xFFFFFFFFFFFFFFFF
 _RAPID_SECRET = (
     0x2D358DCCAA6C78A5,

{pycyphal2-2.0.0.dev5 → pycyphal2-2.0.0.dev6}/src/pycyphal2/_header.py

@@ -11,11 +11,6 @@ LAGE_MIN = -1
 LAGE_MAX = 35
 
 
-# =====================================================================================================================
-# MSG headers
-# =====================================================================================================================
-
-
 @dataclass(frozen=True)
 class MsgBeHeader:
     TYPE = 0
@@ -76,11 +71,6 @@ def _deserialize_msg(buf: bytes | memoryview) -> tuple[int, int, int, int] | Non
     return (lage, evictions, topic_hash, tag)
 
 
-# =====================================================================================================================
-# MSG ACK/NACK headers
-# =====================================================================================================================
-
-
 @dataclass(frozen=True)
 class MsgAckHeader:
     TYPE = 2
@@ -131,11 +121,6 @@ def _deserialize_msg_ack(buf: bytes | memoryview) -> tuple[int, int] | None:
     return (topic_hash, tag)
 
 
-# =====================================================================================================================
-# RSP headers (responses)
-# =====================================================================================================================
-
-
 @dataclass(frozen=True)
 class RspBeHeader:
     TYPE = 4
@@ -172,11 +157,6 @@ class RspRelHeader:
         return RspRelHeader(*r) if r is not None else None
 
 
-# =====================================================================================================================
-# RSP ACK/NACK headers
-# =====================================================================================================================
-
-
 @dataclass(frozen=True)
 class RspAckHeader:
     TYPE = 6
@@ -237,11 +217,6 @@ def _deserialize_rsp(buf: bytes | memoryview) -> tuple[int, int, int, int] | Non
     return (tag, seqno, topic_hash, message_tag)
 
 
-# =====================================================================================================================
-# GOSSIP header
-# =====================================================================================================================
-
-
 @dataclass(frozen=True)
 class GossipHeader:
     TYPE = 8
@@ -275,11 +250,6 @@ class GossipHeader:
         return GossipHeader(lage, topic_hash, evictions, name_len)
 
 
-# =====================================================================================================================
-# SCOUT header
-# =====================================================================================================================
-
-
 @dataclass(frozen=True)
 class ScoutHeader:
     TYPE = 9
@@ -303,10 +273,6 @@ class ScoutHeader:
         return ScoutHeader(buf[23])
 
 
-# =====================================================================================================================
-# Dispatcher
-# =====================================================================================================================
-
 HeaderType = (
     MsgBeHeader
     | MsgRelHeader

{pycyphal2-2.0.0.dev5 → pycyphal2-2.0.0.dev6}/src/pycyphal2/_node.py

@@ -38,10 +38,6 @@ if TYPE_CHECKING:
 
 _logger = logging.getLogger(__name__)
 
-# =====================================================================================================================
-# Constants
-# =====================================================================================================================
-
 TOPIC_NAME_MAX = 200
 EVICTIONS_PINNED_MIN = 0xFFFFE000
 GOSSIP_PERIOD = 5.0
@@ -82,11 +78,6 @@ class GossipScope(Enum):
     INLINE = auto()
 
 
-# =====================================================================================================================
-# Name Resolution
-# =====================================================================================================================
-
-
 def _name_normalize(name: str) -> str:
     """Collapse separators, strip leading/trailing separators."""
     parts: list[str] = []
@@ -120,7 +111,6 @@ def _name_consume_pin_suffix(name: str) -> tuple[str, int | None]:
 
 
 def _name_join(left: str, right: str) -> str:
-    """Join two name parts with separator, normalizing the result."""
     left = _name_normalize(left)
     right = _name_normalize(right)
     if left and right:
@@ -163,7 +153,6 @@ def resolve_name(
     if not name:
         raise ValueError("Empty name")
 
-    # Strip pin suffix first.
     name, pin = _name_consume_pin_suffix(name)
 
     # Apply remapping: lookup on normalized pin-free name; matched rule replaces both name and pin.
@@ -173,7 +162,6 @@ def resolve_name(
             name = remaps[lookup]
             name, pin = _name_consume_pin_suffix(name)
 
-    # Classify and construct.
     if name.startswith("/"):
         resolved = _name_normalize(name)
     elif _name_is_homeful(name):
@@ -191,7 +179,6 @@ def resolve_name(
         raise ValueError("Name resolves to empty string")
     if len(resolved) > TOPIC_NAME_MAX:
         raise ValueError(f"Resolved name exceeds {TOPIC_NAME_MAX} characters")
-    # Validate characters: ASCII 33-126 and '/' only.
     for ch in resolved:
         o = ord(ch)
         if o < 33 or o > 126:
@@ -203,11 +190,6 @@ def resolve_name(
     return resolved, pin, verbatim
 
 
-# =====================================================================================================================
-# Pattern Matching
-# =====================================================================================================================
-
-
 def match_pattern(pattern: str, name: str) -> list[tuple[str, int]] | None:
     """
     Match a pattern against a topic name.
@@ -237,13 +219,7 @@ def match_pattern(pattern: str, name: str) -> list[tuple[str, int]] | None:
     return subs
 
 
-# =====================================================================================================================
-# Subject-ID Computation
-# =====================================================================================================================
-
-
 def compute_subject_id(topic_hash: int, evictions: int, modulus: int) -> int:
-    """Compute the subject-ID for a topic given its hash, evictions, and subject-ID modulus."""
     if evictions >= EVICTIONS_PINNED_MIN:
         return 0xFFFFFFFF - evictions
     h = topic_hash % modulus
@@ -251,11 +227,6 @@ def compute_subject_id(topic_hash: int, evictions: int, modulus: int) -> int:
     return SUBJECT_ID_PINNED_MAX + 1 + ((h + ((e * e) % modulus)) % modulus)
 
 
-# =====================================================================================================================
-# Internal Data Structures
-# =====================================================================================================================
-
-
 @dataclass
 class Association:
     """Tracks a known remote subscriber for reliable delivery ACK tracking."""
@@ -396,11 +367,6 @@ class PublishTracker:
             self.ack_event.set()
 
 
-# =====================================================================================================================
-# Topic
-# =====================================================================================================================
-
-
 class TopicImpl(Topic):
 
     def __init__(self, node: NodeImpl, name: str, evictions: int, now: float) -> None:
@@ -426,7 +392,6 @@ class TopicImpl(Topic):
         self.gossip_task_is_periodic = False
         self.gossip_counter = 0
 
-    # -- Topic ABC --
     @property
     def hash(self) -> int:
         return self._topic_hash
@@ -448,7 +413,6 @@ class TopicImpl(Topic):
     def match(self, pattern: str) -> list[tuple[str, int]] | None:
         return match_pattern(pattern, self._name)
 
-    # -- Internal --
     def lage(self, now: float) -> int:
         return log_age(self.ts_origin, now)
 
@@ -529,11 +493,6 @@ def left_wins(l_lage: int, l_hash: int, r_lage: int, r_hash: int) -> bool:
     return l_lage > r_lage if l_lage != r_lage else l_hash < r_hash
 
 
-# =====================================================================================================================
-# Node
-# =====================================================================================================================
-
-
 class NodeImpl(Node):
     def __init__(self, transport: Transport, *, home: str, namespace: str) -> None:
         self._transport = transport
@@ -545,26 +504,21 @@ class NodeImpl(Node):
         self._monitor_callbacks: dict[int, Callable[[Topic], None]] = {}
         self._next_monitor_callback_id = 0
 
-        # Topic indexes.
         self.topics_by_name: dict[str, TopicImpl] = {}
         self.topics_by_hash: dict[int, TopicImpl] = {}
         self.topics_by_subject_id: dict[int, TopicImpl] = {}  # non-pinned only
 
-        # Subscriber roots.
         self.sub_roots_verbatim: dict[str, SubscriberRoot] = {}
         self.sub_roots_pattern: dict[str, SubscriberRoot] = {}
 
-        # Respond futures for reliable responses.
         self.respond_futures: dict[tuple[int, ...], RespondTracker] = {}
 
-        # Compute broadcast and gossip shard subject IDs.
         modulus = transport.subject_id_modulus
         sid_max = SUBJECT_ID_PINNED_MAX + modulus
         self.broadcast_subject_id = (1 << (int(math.log2(sid_max)) + 1)) - 1
         self.gossip_shard_count = self.broadcast_subject_id - (sid_max + 1)
         assert self.gossip_shard_count > 0
 
-        # Set up broadcast writer and listener.
         self.broadcast_writer = transport.subject_advertise(self.broadcast_subject_id)
 
         def broadcast_handler(arrival: TransportArrival) -> None:
@@ -572,16 +526,13 @@ class NodeImpl(Node):
 
         self.broadcast_listener = transport.subject_listen(self.broadcast_subject_id, broadcast_handler)
 
-        # Gossip shard state: lazily created per shard.
         self.gossip_shard_writers: dict[int, SubjectWriter] = {}
         self.gossip_shard_listeners: dict[int, Closable] = {}
         self.shared_subject_writers: dict[int, SharedSubjectWriter] = {}
         self.shared_subject_listeners: dict[int, SharedSubjectListener] = {}
 
-        # Register unicast handler.
         transport.unicast_listen(self.on_unicast_arrival)
 
-        # Implicit topic GC task, driven by the earliest implicit-topic expiry.
         self._implicit_topics: OrderedDict[TopicImpl, None] = OrderedDict()
         self._implicit_gc_wakeup = asyncio.Event()
         self._gc_task = self.loop.create_task(self.implicit_gc_loop())
@@ -594,7 +545,6 @@ class NodeImpl(Node):
             self.gossip_shard_count,
         )
 
-    # -- Node ABC --
     @property
     def home(self) -> str:
         return self._home
@@ -666,7 +616,6 @@ class NodeImpl(Node):
         if pin is not None and not verbatim:
             raise ValueError("Pattern names cannot be pinned")
 
-        # Ensure subscriber root.
         if verbatim:
             root = self.sub_roots_verbatim.get(resolved)
             if root is None:
@@ -682,12 +631,10 @@ class NodeImpl(Node):
         root.subscribers.append(subscriber)
 
         if verbatim:
-            # Ensure topic exists and couple.
             topic = self.topic_ensure(resolved, pin)
             self.couple_topic_root(topic, root)
             topic.sync_implicit()
         else:
-            # Pattern subscriber: couple with all existing matching topics and scout once per root.
             for topic in list(self.topics_by_name.values()):
                 self.couple_topic_root(topic, root)
                 topic.sync_implicit()
@@ -725,10 +672,7 @@ class NodeImpl(Node):
         except Exception as ex:
             raise SendError(f"Scout send failed for '{resolved}'") from ex
 
-    # -- Topic Management --
-
     def topic_ensure(self, name: str, pin: int | None) -> TopicImpl:
-        """Get or create a topic by resolved name."""
         topic = self.topics_by_name.get(name)
         if topic is not None:
             return topic
@@ -742,7 +686,6 @@ class NodeImpl(Node):
         self.ensure_gossip_shard(self.gossip_shard_subject_id(topic.hash))
         self.touch_implicit_topic(topic)
         self.topic_allocate(topic, evictions, now)
-        # Couple with existing pattern subscriber roots.
         for root in self.sub_roots_pattern.values():
             self.couple_topic_root(topic, root)
         topic.sync_listener()
@@ -757,12 +700,10 @@ class NodeImpl(Node):
 
     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(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]
@@ -782,14 +723,12 @@ class NodeImpl(Node):
                 collider = None  # same topic, no real collision
 
             if collider is None:
-                # No collision, install.
                 t.release_transport_handles()
                 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.set_evictions(ev)
                 del self.topics_by_subject_id[new_sid]
@@ -798,11 +737,9 @@ class NodeImpl(Node):
                     t.pub_writer = self.acquire_subject_writer(t, new_sid)
                 t.sync_listener()
                 self.schedule_gossip_urgent(t)
-                # Schedule collider for reallocation.
                 collider.release_transport_handles()
                 work.append((collider, collider.evictions + 1))
             else:
-                # Our topic loses: increment evictions and retry.
                 work.append((t, ev + 1))
 
     def sync_topic_lifecycle(self, topic: TopicImpl) -> None:
@@ -877,17 +814,14 @@ class NodeImpl(Node):
 
     @staticmethod
     def couple_topic_root(topic: TopicImpl, root: SubscriberRoot) -> None:
-        """Create a coupling between a topic and a subscriber root if not already coupled."""
         for c in topic.couplings:
             if c.root is root:
-                return  # already coupled
+                return
         subs = match_pattern(root.name, topic.name) if root.is_pattern else ([] if root.name == topic.name else None)
         if subs is not None:
             topic.couplings.append(Coupling(root=root, substitutions=subs))
             _logger.debug("Coupled '%s' <-> root '%s'", topic.name, root.name)
 
-    # -- Gossip --
-
     def gossip_shard_subject_id(self, topic_hash: int) -> int:
         modulus = self.transport.subject_id_modulus
         sid_max = SUBJECT_ID_PINNED_MAX + modulus
@@ -950,9 +884,8 @@ class NodeImpl(Node):
             _logger.debug("Shared subject listener released sid=%d", subject_id)
 
     def schedule_gossip(self, topic: TopicImpl) -> None:
-        """Start periodic gossip for an explicit topic."""
         if topic.gossip_task is not None:
-            return  # already scheduled
+            return
         self._reschedule_gossip_periodic(topic, suppressed=False)
 
     @staticmethod
@@ -1066,8 +999,6 @@ class NodeImpl(Node):
         except (SendError, OSError) as e:
             _logger.warning("Gossip unicast send failed for '%s': %s", topic.name, e)
 
-    # -- Scout --
-
     async def _transmit_scout(self, pattern: str) -> None:
         pattern_bytes = pattern.encode("utf-8")
         hdr = ScoutHeader(pattern_len=len(pattern_bytes))
@@ -1096,14 +1027,10 @@ class NodeImpl(Node):
 
         root.scout_task = self.loop.create_task(do_send())
 
-    # -- Message Dispatch --
-
     def on_subject_arrival(self, subject_id: int, arrival: TransportArrival) -> None:
-        """Handle an arrival on a subject (multicast)."""
         self.dispatch_arrival(arrival, subject_id=subject_id, unicast=False)
 
     def on_unicast_arrival(self, arrival: TransportArrival) -> None:
-        """Handle an arrival via unicast."""
         self.dispatch_arrival(arrival, subject_id=None, unicast=True)
 
     def dispatch_arrival(self, arrival: TransportArrival, *, subject_id: int | None, unicast: bool) -> None:
@@ -1293,7 +1220,6 @@ class NodeImpl(Node):
             tracker.on_ack(remote_id, positive)
 
     def on_rsp(self, arrival: TransportArrival, hdr: RspBeHeader | RspRelHeader, payload: bytes) -> None:
-        """Handle a response message (for RPC)."""
         ack = False
         topic = self.topics_by_hash.get(hdr.topic_hash)
         if topic is not None:
@@ -1317,7 +1243,6 @@ class NodeImpl(Node):
             )
 
     def on_rsp_ack(self, arrival: TransportArrival, hdr: RspAckHeader | RspNackHeader) -> None:
-        """Handle a response ACK/NACK."""
         key = (arrival.remote_id, hdr.message_tag, hdr.topic_hash, hdr.seqno, hdr.tag)
         future = self.respond_futures.get(key)
         if future is not None:
@@ -1366,7 +1291,6 @@ class NodeImpl(Node):
 
         topic = self.topics_by_hash.get(hdr.topic_hash)
 
-        # If unknown topic with a name, check for pattern subscriber matches.
         if topic is None and name:
             if scope in {GossipScope.UNICAST, GossipScope.BROADCAST}:
                 topic = self.topic_subscribe_if_matching(
@@ -1472,8 +1396,6 @@ class NodeImpl(Node):
                     self.send_gossip_unicast(topic, arrival.remote_id, arrival.priority), "gossip unicast"
                 )
 
-    # -- Implicit Topic GC --
-
     def notify_implicit_gc(self) -> None:
         if not self._closed:
             self._implicit_gc_wakeup.set()
@@ -1534,8 +1456,6 @@ class NodeImpl(Node):
         self.notify_implicit_gc()
         _logger.info("Topic destroyed '%s'", name)
 
-    # -- Cleanup --
-
     def close(self) -> None:
         if self._closed:
             return

{pycyphal2-2.0.0.dev5 → pycyphal2-2.0.0.dev6}/src/pycyphal2/_publisher.py

@@ -297,11 +297,6 @@ class PublisherImpl(Publisher):
         _logger.info("Publisher closed for '%s'", self._topic.name)
 
 
-# =====================================================================================================================
-# Response Stream
-# =====================================================================================================================
-
-
 class ResponseStreamImpl(ResponseStream):
     def __init__(
         self,
@@ -367,7 +362,6 @@ class ResponseStreamImpl(ResponseStream):
         hdr: RspBeHeader | RspRelHeader,
         payload: bytes,
     ) -> bool:
-        """Called by the node when a response arrives matching our message_tag."""
         reliable = isinstance(hdr, RspRelHeader)
         if self.closed:
             if not reliable:

{pycyphal2-2.0.0.dev5 → pycyphal2-2.0.0.dev6}/src/pycyphal2/_subscriber.py

@@ -23,11 +23,6 @@ _logger = logging.getLogger(__name__)
 REORDERING_WINDOW_MAX = SESSION_LIFETIME / 2
 
 
-# =====================================================================================================================
-# Reordering
-# =====================================================================================================================
-
-
 @dataclass
 class InternedMsg:
     arrival: Arrival
@@ -114,13 +109,11 @@ class SubscriberImpl(Subscriber):
         return item
 
     def deliver(self, arrival: Arrival, tag: int, remote_id: int) -> bool:
-        """Called by the node to deliver a message to this subscriber."""
         if self.closed:
             return False
         if self._reordering_window is None:
             self.queue.put_nowait(arrival)
             return True
-        # Reordering enabled.
         self._drop_stale_reordering(arrival.timestamp.s)
         topic_hash = arrival.breadcrumb.topic.hash
         key = (remote_id, topic_hash)
@@ -148,7 +141,6 @@ class SubscriberImpl(Subscriber):
 
         expected = state.last_ejected_lin_tag + 1
         if lin_tag == expected:
-            # In-order: eject immediately and scan for consecutive.
             self.queue.put_nowait(arrival)
             state.last_ejected_lin_tag = lin_tag
             self._scan_reordering(state, force_first=False)
@@ -160,7 +152,6 @@ class SubscriberImpl(Subscriber):
             lin_tag = (tag - state.tag_baseline) & ((1 << 64) - 1)
             _logger.debug("Reorder resequence tag=%d lin=%d", tag, lin_tag)
 
-        # Out-of-order but within capacity: intern.
         if lin_tag in state.interned:
             return True
         state.interned[lin_tag] = InternedMsg(arrival=arrival, tag=tag, remote_id=remote_id, lin_tag=lin_tag)
@@ -187,7 +178,6 @@ class SubscriberImpl(Subscriber):
             break
 
     def _force_eject_all(self, state: ReorderingState, *, silenced: bool = False) -> None:
-        """Force-eject all interned messages in tag order."""
         while state.interned:
             lin_tag = min(state.interned)
             interned = state.interned.pop(lin_tag)
@@ -199,7 +189,6 @@ class SubscriberImpl(Subscriber):
             state.timeout_handle = None
 
     def _rearm_reorder_timeout(self, state: ReorderingState) -> None:
-        """Arm or rearm the reordering timeout against the current head-of-line slot."""
         if self._reordering_window is None:
             return
         if not state.interned:
@@ -256,11 +245,6 @@ class SubscriberImpl(Subscriber):
         _logger.info("Subscriber closed for '%s'", self._pattern)
 
 
-# =====================================================================================================================
-# Breadcrumb
-# =====================================================================================================================
-
-
 class BreadcrumbImpl(Breadcrumb):
     def __init__(
         self,
@@ -322,7 +306,6 @@ class BreadcrumbImpl(Breadcrumb):
             _logger.debug("Response BE sent seqno=%d to %016x", seqno, self._remote_id)
             return
 
-        # Reliable response with retransmission.
         tracker = RespondTracker(
             remote_id=self._remote_id,
             message_tag=self._message_tag,

{pycyphal2-2.0.0.dev5 → pycyphal2-2.0.0.dev6}/src/pycyphal2/_transport.py

@@ -20,6 +20,11 @@ SUBJECT_ID_MODULUS_32bit = 4294954663  # Incompatible with Cyphal/CAN and Cyphal
 class SubjectWriter(Closable):
     @abstractmethod
     async def __call__(self, deadline: Instant, priority: Priority, message: bytes | memoryview) -> None:
+        """
+        Send one message on the subject. Returning means every frame of the transfer has been handed over to the
+        OS or the driver on at least one interface; implementations that queue internally must await that handover.
+        Raises :class:`SendError` if the message could not be handed over before the deadline.
+        """
         raise NotImplementedError