pamoja-serial 0.1.18__tar.gz

pamoja_serial-0.1.18/.gitignore

@@ -0,0 +1,13 @@
+# Native extensions are built per platform, not committed.
+*.so
+*.pyd
+*.dylib
+
+# Build and packaging output.
+dist/
+wheels/
+target/
+
+# Local virtual environments.
+.venv/
+venv/

pamoja_serial-0.1.18/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anthony Wiedman
+
+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.

pamoja_serial-0.1.18/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.5
+Name: pamoja-serial
+Version: 0.1.18
+Summary: SLIP and COBS byte stuffing with streaming decoders, so a UART byte stream carries discrete packets.
+Project-URL: Repository, https://github.com/molexxxx/pamoja
+Project-URL: Documentation, https://pamoja.molex.cloud/docs/guides/serial.html
+Author: molexxxx
+License: MIT
+License-File: LICENSE-MIT
+Keywords: iot,pamoja,robotics,serial
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pamoja-native==0.1.18
+Description-Content-Type: text/markdown
+
+# pamoja-serial
+
+SLIP and COBS byte stuffing with streaming decoders, so a UART byte stream carries discrete packets. One capability of [pamoja](https://github.com/molexxxx/pamoja), one memory-safe Rust core with bindings for TypeScript, Python, and C#.
+
+[![read the guide](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-guide.svg)](https://pamoja.molex.cloud/docs/guides/serial.html)
+[![documentation](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-docs.svg)](https://pamoja.molex.cloud/docs/)
+[![API reference](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-api.svg)](https://pamoja.molex.cloud/docs/reference/python/pamoja/serial.html)
+
+## Install
+
+```sh
+pip install pamoja-serial
+```
+
+```python
+from pamoja import serial
+```
+
+This pulls in `pamoja-native`, the compiled engine. `pip install pamoja` is the whole framework in one package.
+
+## Example
+
+The script the test suite runs, spliced here as it ran.
+
+From [`bindings/python/guides/serial.py`](https://github.com/molexxxx/pamoja/blob/main/bindings/python/guides/serial.py):
+
+```python
+from pamoja.serial import COBS_DELIMITER, SLIP_END, SLIP_ESC, SlipDecoder, cobs, slip
+
+# A UART carries bytes, not packets, so a framing has to mark where one packet ends. SLIP
+# reserves two byte values for that, and the package names both: the end byte closes a
+# frame, the escape byte carries a value that would otherwise look like one.
+payload = b"lvl=" + bytes([SLIP_END, SLIP_ESC])
+framed = slip.encode(payload)
+print(f"slip      {len(payload)} payload bytes framed as {len(framed)}")
+
+# Decoding gives the payload back unchanged, reserved bytes and all.
+restored = slip.decode(framed)
+print(f"slip      decoded back to {len(restored)} bytes")
+
+# COBS trades that escaping for one code byte per run of up to 254 non-zero bytes, each
+# run led by its own length, so a frame never grows by more than a byte per 254. Zero is
+# the delimiter, and never appears inside a frame.
+packet = b"lvl=" + bytes([COBS_DELIMITER]) + b"7"
+cobs_framed = cobs.encode(packet)
+print(f"cobs      {len(packet)} payload bytes framed as {len(cobs_framed)}")
+
+# A read from a port returns whatever arrived, which is rarely one whole frame. This chunk
+# holds two good frames with a truncated one between them; the decoder hands over the good
+# ones and discards only the bad frame.
+decoder = SlipDecoder()
+chunk = (
+    b"ok"
+    + bytes([SLIP_END])
+    + bytes([SLIP_ESC])  # a frame that ends before its escape pair completes
+    + bytes([SLIP_END])
+    + b"go"
+    + bytes([SLIP_END])
+)
+frames = decoder.feed(chunk)
+for frame in frames:
+    print(f"received  {frame.decode()}")
+print(f"discarded {decoder.discarded} frame the stream mangled")
+```
+
+## The same capability in every language
+
+| Language | Package | Reference |
+| --- | --- | --- |
+| Rust | [`pamoja-serial`](https://crates.io/crates/pamoja-serial) | [reference](https://pamoja.molex.cloud/docs/reference/rust/pamoja_serial/index.html), [docs.rs](https://docs.rs/pamoja-serial), [install](https://pamoja.molex.cloud/docs/reference/rust.html#rust-serial) |
+| TypeScript | [`@pamoja/serial`](https://www.npmjs.com/package/@pamoja/serial) | [reference](https://pamoja.molex.cloud/docs/reference/node/modules/_pamoja_serial.html), [install](https://pamoja.molex.cloud/docs/reference/node.html#node-serial) |
+| Python | [`pamoja-serial`](https://pypi.org/project/pamoja-serial/) | [reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/serial.html), [install](https://pamoja.molex.cloud/docs/reference/python.html#python-serial) |
+| C# | [`Pamoja.Serial`](https://www.nuget.org/packages/Pamoja.Serial) | [reference](https://pamoja.molex.cloud/docs/reference/dotnet/api/Pamoja.Serial.html), [install](https://pamoja.molex.cloud/docs/reference/dotnet.html#dotnet-serial) |
+
+## Documentation
+
+- [`pamoja.serial` reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/serial.html), every class and function in this module.
+- [The Serial framing guide](https://pamoja.molex.cloud/docs/guides/serial.html), with the same example in Rust, TypeScript, and C#.
+- [Every capability](https://pamoja.molex.cloud/docs/), and the [install page](https://pamoja.molex.cloud/docs/install.html).
+
+## License
+
+MIT

pamoja_serial-0.1.18/README.md

@@ -0,0 +1,83 @@
+# pamoja-serial
+
+SLIP and COBS byte stuffing with streaming decoders, so a UART byte stream carries discrete packets. One capability of [pamoja](https://github.com/molexxxx/pamoja), one memory-safe Rust core with bindings for TypeScript, Python, and C#.
+
+[![read the guide](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-guide.svg)](https://pamoja.molex.cloud/docs/guides/serial.html)
+[![documentation](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-docs.svg)](https://pamoja.molex.cloud/docs/)
+[![API reference](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-api.svg)](https://pamoja.molex.cloud/docs/reference/python/pamoja/serial.html)
+
+## Install
+
+```sh
+pip install pamoja-serial
+```
+
+```python
+from pamoja import serial
+```
+
+This pulls in `pamoja-native`, the compiled engine. `pip install pamoja` is the whole framework in one package.
+
+## Example
+
+The script the test suite runs, spliced here as it ran.
+
+From [`bindings/python/guides/serial.py`](https://github.com/molexxxx/pamoja/blob/main/bindings/python/guides/serial.py):
+
+```python
+from pamoja.serial import COBS_DELIMITER, SLIP_END, SLIP_ESC, SlipDecoder, cobs, slip
+
+# A UART carries bytes, not packets, so a framing has to mark where one packet ends. SLIP
+# reserves two byte values for that, and the package names both: the end byte closes a
+# frame, the escape byte carries a value that would otherwise look like one.
+payload = b"lvl=" + bytes([SLIP_END, SLIP_ESC])
+framed = slip.encode(payload)
+print(f"slip      {len(payload)} payload bytes framed as {len(framed)}")
+
+# Decoding gives the payload back unchanged, reserved bytes and all.
+restored = slip.decode(framed)
+print(f"slip      decoded back to {len(restored)} bytes")
+
+# COBS trades that escaping for one code byte per run of up to 254 non-zero bytes, each
+# run led by its own length, so a frame never grows by more than a byte per 254. Zero is
+# the delimiter, and never appears inside a frame.
+packet = b"lvl=" + bytes([COBS_DELIMITER]) + b"7"
+cobs_framed = cobs.encode(packet)
+print(f"cobs      {len(packet)} payload bytes framed as {len(cobs_framed)}")
+
+# A read from a port returns whatever arrived, which is rarely one whole frame. This chunk
+# holds two good frames with a truncated one between them; the decoder hands over the good
+# ones and discards only the bad frame.
+decoder = SlipDecoder()
+chunk = (
+    b"ok"
+    + bytes([SLIP_END])
+    + bytes([SLIP_ESC])  # a frame that ends before its escape pair completes
+    + bytes([SLIP_END])
+    + b"go"
+    + bytes([SLIP_END])
+)
+frames = decoder.feed(chunk)
+for frame in frames:
+    print(f"received  {frame.decode()}")
+print(f"discarded {decoder.discarded} frame the stream mangled")
+```
+
+## The same capability in every language
+
+| Language | Package | Reference |
+| --- | --- | --- |
+| Rust | [`pamoja-serial`](https://crates.io/crates/pamoja-serial) | [reference](https://pamoja.molex.cloud/docs/reference/rust/pamoja_serial/index.html), [docs.rs](https://docs.rs/pamoja-serial), [install](https://pamoja.molex.cloud/docs/reference/rust.html#rust-serial) |
+| TypeScript | [`@pamoja/serial`](https://www.npmjs.com/package/@pamoja/serial) | [reference](https://pamoja.molex.cloud/docs/reference/node/modules/_pamoja_serial.html), [install](https://pamoja.molex.cloud/docs/reference/node.html#node-serial) |
+| Python | [`pamoja-serial`](https://pypi.org/project/pamoja-serial/) | [reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/serial.html), [install](https://pamoja.molex.cloud/docs/reference/python.html#python-serial) |
+| C# | [`Pamoja.Serial`](https://www.nuget.org/packages/Pamoja.Serial) | [reference](https://pamoja.molex.cloud/docs/reference/dotnet/api/Pamoja.Serial.html), [install](https://pamoja.molex.cloud/docs/reference/dotnet.html#dotnet-serial) |
+
+## Documentation
+
+- [`pamoja.serial` reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/serial.html), every class and function in this module.
+- [The Serial framing guide](https://pamoja.molex.cloud/docs/guides/serial.html), with the same example in Rust, TypeScript, and C#.
+- [Every capability](https://pamoja.molex.cloud/docs/), and the [install page](https://pamoja.molex.cloud/docs/install.html).
+
+## License
+
+MIT

pamoja_serial-0.1.18/pamoja/serial/__init__.py

@@ -0,0 +1,187 @@
+"""Idiomatic serial-framing facade.
+
+A serial line is a stream of bytes with no packet boundaries, so something has to
+mark where one message ends and the next begins. SLIP and COBS are the two ways to
+do that, and each is offered both as a one-shot call over a complete frame and as
+a streaming decoder for the arbitrary chunks a port delivers.
+
+The streaming decoders are what a real read loop uses. A corrupt frame does not
+raise, because the frames around it are still good; it is dropped and counted on
+:attr:`SlipDecoder.discarded`.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from pamoja._native import CobsDecoder as _NativeCobsDecoder
+from pamoja._native import SlipDecoder as _NativeSlipDecoder
+from pamoja._native import cobs_decode as _cobs_decode
+from pamoja._native import cobs_encode as _cobs_encode
+from pamoja._native import cobs_max_encoded_len as _cobs_max_encoded_len
+from pamoja._native import serial_framing_bytes as _serial_framing_bytes
+from pamoja._native import slip_decode as _slip_decode
+from pamoja._native import slip_encode as _slip_encode
+from pamoja._native import slip_max_encoded_len as _slip_max_encoded_len
+
+__all__ = [
+    "COBS_DELIMITER",
+    "CobsDecoder",
+    "Framing",
+    "SLIP_END",
+    "SLIP_ESC",
+    "SLIP_ESC_END",
+    "SLIP_ESC_ESC",
+    "SlipDecoder",
+    "cobs",
+    "slip",
+]
+
+
+class Framing(Protocol):
+    """One of the two byte-stuffing framings this module offers."""
+
+    def encode(self, payload: bytes) -> bytes:
+        """Frame a payload for the wire.
+
+        :param payload: The bytes to send.
+        :returns: The frame, delimiter included.
+        """
+
+    def decode(self, frame: bytes) -> bytes:
+        """Read the payload back out of a complete frame.
+
+        :param frame: The frame as it arrived.
+        :returns: The payload.
+        :raises PamojaError: If the frame is corrupt.
+        """
+
+    def max_encoded_len(self, payload_len: int) -> int:
+        """Return the largest frame a payload of this length can produce.
+
+        :param payload_len: The payload length in bytes.
+        :returns: The worst-case frame length.
+        """
+
+
+_END, _ESC, _ESC_END, _ESC_ESC, _DELIMITER = _serial_framing_bytes()
+
+#: The SLIP byte that ends a frame (RFC 1055).
+SLIP_END = _END
+#: The SLIP byte that escapes a reserved value inside a frame (RFC 1055).
+SLIP_ESC = _ESC
+#: The byte that follows an escape to stand for a literal end byte.
+SLIP_ESC_END = _ESC_END
+#: The byte that follows an escape to stand for a literal escape byte.
+SLIP_ESC_ESC = _ESC_ESC
+#: The byte that delimits a COBS frame, which never appears inside one.
+COBS_DELIMITER = _DELIMITER
+
+
+class _Slip:
+    """SLIP (RFC 1055): an ``END`` byte ends a packet, and an escape pair carries it."""
+
+    __slots__ = ()
+
+    def encode(self, payload: bytes) -> bytes:
+        """Frame a payload as a SLIP packet."""
+        return _slip_encode(bytes(payload))
+
+    def decode(self, frame: bytes) -> bytes:
+        """Read the payload back out of a SLIP frame."""
+        return _slip_decode(bytes(frame))
+
+    def max_encoded_len(self, payload_len: int) -> int:
+        """Return the worst-case SLIP frame length for a payload."""
+        return _slip_max_encoded_len(payload_len)
+
+
+class _Cobs:
+    """COBS: removes the zero byte so one zero delimits packets unambiguously."""
+
+    __slots__ = ()
+
+    def encode(self, payload: bytes) -> bytes:
+        """Frame a payload as a COBS packet."""
+        return _cobs_encode(bytes(payload))
+
+    def decode(self, frame: bytes) -> bytes:
+        """Read the payload back out of a COBS frame."""
+        return _cobs_decode(bytes(frame))
+
+    def max_encoded_len(self, payload_len: int) -> int:
+        """Return the worst-case COBS frame length for a payload."""
+        return _cobs_max_encoded_len(payload_len)
+
+
+#: SLIP framing, the simplest there is.
+slip: Framing = _Slip()
+
+#: COBS framing, for links where the overhead has to stay small and predictable.
+cobs: Framing = _Cobs()
+
+
+class SlipDecoder:
+    """Reassembles whole SLIP frames from the chunks a serial port delivers.
+
+    Example::
+
+        decoder = SlipDecoder()
+        while True:
+            for frame in decoder.feed(port.read(256)):
+                handle(frame)
+    """
+
+    __slots__ = ("_native",)
+
+    def __init__(self) -> None:
+        """Create an empty decoder, ready for the first chunk."""
+        self._native = _NativeSlipDecoder()
+
+    def feed(self, chunk: bytes) -> list[bytes]:
+        """Feed a chunk of the stream.
+
+        :param chunk: The bytes just read from the port.
+        :returns: Every frame this chunk completed, in order, which is often none.
+        """
+        return self._native.feed(bytes(chunk))
+
+    @property
+    def discarded(self) -> int:
+        """How many corrupt frames this decoder has discarded."""
+        return self._native.discarded
+
+    def reset(self) -> None:
+        """Discard any partly assembled frame."""
+        self._native.reset()
+
+
+class CobsDecoder:
+    """Reassembles whole COBS frames from the chunks a serial port delivers.
+
+    The counterpart to :class:`SlipDecoder`, for links where the framing overhead
+    has to stay small and predictable.
+    """
+
+    __slots__ = ("_native",)
+
+    def __init__(self) -> None:
+        """Create an empty decoder, ready for the first chunk."""
+        self._native = _NativeCobsDecoder()
+
+    def feed(self, chunk: bytes) -> list[bytes]:
+        """Feed a chunk of the stream.
+
+        :param chunk: The bytes just read from the port.
+        :returns: Every frame this chunk completed, in order.
+        """
+        return self._native.feed(bytes(chunk))
+
+    @property
+    def discarded(self) -> int:
+        """How many corrupt frames this decoder has discarded."""
+        return self._native.discarded
+
+    def reset(self) -> None:
+        """Discard any partly assembled frame."""
+        self._native.reset()

pamoja_serial-0.1.18/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pamoja-serial"
+version = "0.1.18"
+description = "SLIP and COBS byte stuffing with streaming decoders, so a UART byte stream carries discrete packets."
+readme = "README.md"
+license = { text = "MIT" }
+license-files = ["LICENSE-MIT"]
+requires-python = ">=3.10"
+authors = [{ name = "molexxxx" }]
+keywords = ["pamoja", "iot", "robotics", "serial"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pamoja-native==0.1.18",
+]
+
+[project.urls]
+Repository = "https://github.com/molexxxx/pamoja"
+Documentation = "https://pamoja.molex.cloud/docs/guides/serial.html"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pamoja"]