zerodds-wire 1.0.0rc7__py3-none-any.whl

zerodds_wire/__init__.py

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 ZeroDDS Contributors
+"""`zerodds_wire` — the Python wire runtime.
+
+The runtime a generated Python encoder calls: `Writer` and `Reader`, the
+alignment rules, and the framing forms. It is the counterpart of
+`crates/wire`, not a binding to it — a Python probe that reached the Rust
+core through ctypes would be byte-identical by construction and would
+prove nothing about whether the two read the specification the same way.
+
+This package makes no decision about a type. Which members are written,
+in what order, with which header and which length code is the layout
+plan's answer and arrives here as arguments. A runtime that decided any
+of it would be a second place where the wire format lives.
+
+Spec: DDS-XTypes 1.3 §7.4, DDSI-RTPS 2.5 §9.6.3.8 and §10.5.
+"""
+
+from __future__ import annotations
+
+from .encapsulation import Encoding, encapsulation_header, encapsulation_padding
+from .endianness import Endianness
+from .error import ImpossibleLength, NotUtf8, OutOfRange, Truncated, WireError
+from .float128 import Float128, Inexact
+from .reader import EmHeaderRead, PidRead, Reader, ReaderMark
+# `utf8_octets` and `utf16_units` are exported because a generated codec
+# names them: the shared walk emits both through
+# `CodecTarget::runtime_static` where a bounded `string` or `wstring` is
+# measured against its bound (§7.3.1.2.1.12.3). Without them here a
+# generated module needed a second import line reaching into a submodule,
+# which is a path the package's shape does not otherwise ask anyone to
+# know.
+from .typesupport import Discarded, Status, TryConstruct, utf8_octets, utf16_units
+from .values import Mismatch, Missing, SampleError, Unknown
+from .writer import (
+    KEY_HASH_LEN,
+    PID_EXTENDED,
+    PID_IGNORE,
+    PID_IMPL_EXTENSION,
+    PID_LIST_END,
+    PID_MUST_UNDERSTAND,
+    PID_SHORT_MAX_ID,
+    PID_SHORT_MAX_LEN,
+    DHeader,
+    EmHeader,
+    ParameterRole,
+    Pid,
+    PlCdr1Framing,
+    pid_flags_at,
+    bit_pattern_bool,
+    bit_pattern_f32,
+    bit_pattern_f64,
+    bit_pattern_int,
+    no_dheader,
+    Writer,
+    wstring_unit_width,
+)
+
+__all__ = [
+    "DHeader",
+    "Float128",
+    "Inexact",
+    "EmHeader",
+    "EmHeaderRead",
+    "Encoding",
+    "Endianness",
+    "ImpossibleLength",
+    "KEY_HASH_LEN",
+    "Discarded",
+    "Mismatch",
+    "Missing",
+    "NotUtf8",
+    "OutOfRange",
+    "PID_EXTENDED",
+    "PID_IGNORE",
+    "PID_IMPL_EXTENSION",
+    "PID_LIST_END",
+    "PID_MUST_UNDERSTAND",
+    "PID_SHORT_MAX_ID",
+    "PID_SHORT_MAX_LEN",
+    "ParameterRole",
+    "Pid",
+    "PlCdr1Framing",
+    "pid_flags_at",
+    "PidRead",
+    "Reader",
+    "ReaderMark",
+    "SampleError",
+    "Status",
+    "Truncated",
+    "Unknown",
+    "TryConstruct",
+    "WireError",
+    "Writer",
+    "encapsulation_header",
+    "encapsulation_padding",
+    "bit_pattern_bool",
+    "bit_pattern_f32",
+    "bit_pattern_f64",
+    "bit_pattern_int",
+    "no_dheader",
+    "utf8_octets",
+    "utf16_units",
+    "wstring_unit_width",
+]
+
+__version__ = "1.0.0-rc.7"

zerodds_wire/encapsulation.py

@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 ZeroDDS Contributors
+"""Encodings, and the four bytes that announce one.
+
+DDSI-RTPS 2.5 §10.5 and XTypes 1.3 §7.4.1.1. Kept out of `writer.py`
+because it frames a sample rather than being part of one: a KeyHash
+holder is written by the same writer and carries no header at all.
+"""
+
+from __future__ import annotations
+
+import enum
+
+from .endianness import Endianness
+
+__all__ = ["Encoding", "encapsulation_header", "encapsulation_padding"]
+
+
+class Encoding(enum.Enum):
+    """Which encoding a plan and a stream are in.
+
+    The five of `zerodds_ast_layout::Encoding`. XCDR1 and XCDR2 differ in
+    their framing: XCDR1 has no delimiter header, and `@mutable` uses PID
+    headers there and EMHEADERs here.
+    """
+
+    PLAIN_CDR1 = "plain-cdr1"
+    PL_CDR1 = "pl-cdr1"
+    PLAIN_CDR2 = "plain-cdr2"
+    DELIMITED_CDR = "delimited-cdr"
+    PL_CDR2 = "pl-cdr2"
+
+    def is_v1(self) -> bool:
+        """Whether this is an XCDR version 1 encoding."""
+        return self in (Encoding.PLAIN_CDR1, Encoding.PL_CDR1)
+
+    def is_v2(self) -> bool:
+        """Whether this is an XCDR version 2 encoding."""
+        return not self.is_v1()
+
+    @property
+    def max_alignment(self) -> int:
+        """The largest alignment any primitive takes.
+
+        XTypes 1.3 §7.4.1: `MAXALIGN(VERSION2) = 4`,
+        `MAXALIGN(VERSION1) = 8`, and `ALIGN(N)` aligns to
+        `MIN(N, XCDR.maxalign)`. §7.6.8 repeats it for the key holder:
+        "the maximum alignment in PLAIN_CDR2 (i.e., 4)".
+        """
+        return 8 if self.is_v1() else 4
+
+    @staticmethod
+    def parse(name: str) -> Encoding | None:
+        """The command line's spelling, including the two shorthands.
+
+        `xcdr1` and `xcdr2` name the plain form, because that is what a
+        caller who has not thought about extensibility means. An unknown
+        name is `None` and never a default.
+        """
+        if name in ("xcdr1", "plain-cdr1"):
+            return Encoding.PLAIN_CDR1
+        if name in ("xcdr2", "plain-cdr2"):
+            return Encoding.PLAIN_CDR2
+        for encoding in Encoding:
+            if encoding.value == name:
+                return encoding
+        return None
+
+
+_IDENTIFIERS: dict[tuple[Encoding, Endianness], int] = {
+    (Encoding.PLAIN_CDR1, Endianness.BIG): 0x0000,
+    (Encoding.PLAIN_CDR1, Endianness.LITTLE): 0x0001,
+    (Encoding.PL_CDR1, Endianness.BIG): 0x0002,
+    (Encoding.PL_CDR1, Endianness.LITTLE): 0x0003,
+    (Encoding.PLAIN_CDR2, Endianness.BIG): 0x0006,
+    (Encoding.PLAIN_CDR2, Endianness.LITTLE): 0x0007,
+    (Encoding.DELIMITED_CDR, Endianness.BIG): 0x0008,
+    (Encoding.DELIMITED_CDR, Endianness.LITTLE): 0x0009,
+    (Encoding.PL_CDR2, Endianness.BIG): 0x000A,
+    (Encoding.PL_CDR2, Endianness.LITTLE): 0x000B,
+}
+
+
+def encapsulation_padding(length: int) -> int:
+    """How many zero bytes bring `length` up to the next multiple of four.
+
+    XTypes 1.3 §7.4.1.1 pads the serialized data to a four-byte
+    boundary; §7.6.3.1.2 states the count in the encapsulation options.
+    """
+    return (4 - (length & 3)) & 3
+
+
+def encapsulation_header(
+    encoding: Encoding, endianness: Endianness, padding: int = 0
+) -> bytes:
+    """The four-byte encapsulation header.
+
+    The identifier itself is always big-endian on the wire, whatever the
+    payload behind it is — it is what tells a reader which order to
+    switch to.
+
+    The two option bytes carry the payload's trailing padding count in
+    the low two bits of the second one. XTypes 1.3 §7.6.3.1.2: those
+    bits "shall be interpreted by the receiver to determine where the
+    serialized data exactly ended". Measured on the loopback wire on
+    2026-08-09: Cyclone, RTI and Fast DDS all pad the payload to four
+    and all three state the count — `@final struct One { octet a; }`
+    goes out as `0001 0003 ab000000` from every one of them.
+    """
+    identifier = _IDENTIFIERS[(encoding, endianness)]
+    return bytes([identifier >> 8, identifier & 0xFF, 0, padding & 0x3])

zerodds_wire/endianness.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 ZeroDDS Contributors
+"""Byte order.
+
+The counterpart of `crates/wire/src/endianness.rs`. A separate module
+because the writer and the reader both need it and neither should own it.
+"""
+
+from __future__ import annotations
+
+import enum
+
+__all__ = ["Endianness"]
+
+
+class Endianness(enum.Enum):
+    """Which end of a multi-byte value goes out first."""
+
+    LITTLE = "le"
+    BIG = "be"
+
+    def is_little(self) -> bool:
+        """Whether the low byte goes out first."""
+        return self is Endianness.LITTLE
+
+    @property
+    def struct_prefix(self) -> str:
+        """The `struct` module's byte-order character.
+
+        Explicit rather than `=` or `@`: the native order of the host is
+        not the order the encapsulation identifier announced, and a probe
+        that agreed with itself on one machine and not another would be
+        useless as a second opinion.
+        """
+        return "<" if self is Endianness.LITTLE else ">"
+
+    @staticmethod
+    def parse(name: str) -> Endianness | None:
+        """The command line's spelling, or `None` for anything else.
+
+        `None` and not a default: a typo in a wire-affecting flag has to
+        be loud, because the bytes it produces look plausible.
+        """
+        if name in ("le", "little"):
+            return Endianness.LITTLE
+        if name in ("be", "big"):
+            return Endianness.BIG
+        return None

zerodds_wire/error.py

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 ZeroDDS Contributors
+"""What can go wrong on the wire.
+
+The variants of `crates/wire/src/error.rs`, as exceptions. Every one
+names what was expected and where: a reader that returned a zero for a
+truncated stream would hand the caller a value that was never sent, and
+a writer that clamped an over-wide integer would put a different number
+on the wire than the caller asked for.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "WireError",
+    "Truncated",
+    "ImpossibleLength",
+    "NotUtf8",
+    "OutOfRange",
+]
+
+
+class WireError(Exception):
+    """Base of every wire failure."""
+
+
+class Truncated(WireError):
+    """The stream ended before the value did."""
+
+    def __init__(self, at: int, needed: int, available: int) -> None:
+        super().__init__(f"at {at}: {needed} bytes needed, {available} available")
+        self.at = at
+        self.needed = needed
+        self.available = available
+
+
+class ImpossibleLength(WireError):
+    """A length field claims more than the stream holds.
+
+    Separate from `Truncated`: a length that cannot be true is a
+    malformed stream, not a short one, and allocating for it is how a
+    reader turns a bad message into an out-of-memory.
+    """
+
+    def __init__(self, at: int, claimed: int, available: int) -> None:
+        super().__init__(f"at {at}: a length of {claimed} with {available} bytes left")
+        self.at = at
+        self.claimed = claimed
+        self.available = available
+
+
+class NotUtf8(WireError):
+    """A string held bytes that are not UTF-8."""
+
+    def __init__(self, at: int) -> None:
+        super().__init__(f"at {at}: the string is not UTF-8")
+        self.at = at
+
+
+class OutOfRange(WireError):
+    """A value outside what its type admits.
+
+    Raised by the writer as well as the reader, which is where Python
+    differs from the Rust runtime: an `int` there is `i32` or `u64` and
+    the compiler has already refused the value, while here it is
+    unbounded and the check has to happen at the point of the write.
+    """
+
+    def __init__(self, at: int, expected: str) -> None:
+        super().__init__(f"at {at}: expected {expected}")
+        self.at = at
+        self.expected = expected