pyccobs 0.1.1__py3-none-win_arm64.whl

ccobs/__init__.py

@@ -0,0 +1,312 @@
+"""Pythonic ctypes bindings for the ccobs C library."""
+
+import ctypes
+import os
+from collections.abc import Iterable
+from enum import IntEnum
+from typing import Optional
+
+from ._lib import BytePointer, StatePointer, bind
+
+__all__ = [
+    "Decoder",
+    "Encoder",
+    "Error",
+    "MalformedInputError",
+    "CcobsError",
+    "decode",
+    "encode",
+    "encodev",
+    "load_library",
+]
+
+
+class Error(IntEnum):
+    OK = 0
+    PARTIAL = 1
+    NEED_OUTPUT = 2
+    NULL_ARGUMENT = 3
+    MALFORMED_INPUT = 4
+    OOM = 5
+
+
+class CcobsError(Exception):
+    """An error reported by the native ccobs library."""
+
+    def __init__(self, code: int, message: str):
+        self.code = Error(code) if code in Error._value2member_map_ else code
+        super().__init__(message)
+
+
+class MalformedInputError(CcobsError):
+    """The encoded stream contains a malformed COBS frame."""
+
+
+_library: Optional[ctypes.CDLL] = None
+
+
+def load_library(path: Optional[os.PathLike[str] | str] = None) -> ctypes.CDLL:
+    """Load and return ccobs, optionally from an explicit path.
+
+    Calling this with a path replaces the process-wide library used by new
+    encoders and decoders. Existing objects retain their original library.
+    """
+    global _library
+    if path is not None or _library is None:
+        _library = bind(path)
+    return _library
+
+
+def _message(lib: ctypes.CDLL, code: int) -> str:
+    value = lib.ccobs_error_string(code)
+    return value.decode("utf-8", "replace") if value else f"ccobs error {code}"
+
+
+def _raise_error(lib: ctypes.CDLL, code: int) -> None:
+    """Wrapper to turn ccobs error into idiomatic Python errors."""
+    cls = MalformedInputError if code == Error.MALFORMED_INPUT else CcobsError
+    raise cls(code, _message(lib, code))
+
+
+def _input_buffer(data: bytes) -> tuple[object | None, BytePointer]:
+    if not data:
+        return None, BytePointer()
+    owner = (ctypes.c_uint8 * len(data)).from_buffer_copy(data)
+    return owner, ctypes.cast(owner, BytePointer)
+
+
+class _State:
+    """Wrapper to internal ccobs state."""
+
+    def __init__(self, library: Optional[ctypes.CDLL] = None):
+        self._lib = library or load_library()
+        error = ctypes.c_int(Error.OK)
+        self._state: StatePointer = self._lib.ccobs_create(ctypes.byref(error))
+        if not self._state:
+            _raise_error(self._lib, error.value)
+
+    def close(self) -> None:
+        state = getattr(self, "_state", None)
+        if state:
+            self._lib.ccobs_destroy(state)
+            self._state = StatePointer()
+
+    def reset(self) -> None:
+        code = self._lib.ccobs_reset(self._state)
+        if code != Error.OK:
+            _raise_error(self._lib, code)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    def __del__(self):
+        self.close()
+
+
+class Encoder(_State):
+    """Incrementally encode message chunks or batches of complete messages."""
+
+    _OUTPUT_CHUNK_SIZE = 64 * 1024
+
+    def feed(self, data: object = b"", *, end_message: bool = False) -> bytes:
+        raw = memoryview(data).cast("B").tobytes()
+        if end_message:
+            return self.feedv((raw,))
+
+        owner, _ = _input_buffer(raw)
+        offset = 0
+        result = bytearray()
+        # 257 also drains a full native block retained from an earlier call.
+        capacity = max(257, int(self._lib.ccobs_encode_max_size(len(raw))))
+        while True:
+            output = (ctypes.c_uint8 * capacity)()
+            available = ctypes.c_size_t(len(raw) - offset)
+            size = ctypes.c_size_t(capacity)
+            current = (
+                ctypes.cast(ctypes.byref(owner, offset), BytePointer)
+                if owner
+                else BytePointer()
+            )
+            code = self._lib.ccobs_encode(
+                self._state,
+                current,
+                ctypes.byref(available),
+                output,
+                ctypes.byref(size),
+                end_message,
+            )
+            offset += available.value
+            result.extend(output[: size.value])
+
+            if code == Error.NEED_OUTPUT:
+                continue
+            if code not in (Error.OK, Error.PARTIAL):
+                _raise_error(self._lib, code)
+
+            return bytes(result)
+
+    def feedv(self, messages: Iterable[object]) -> bytes:
+        """Encode complete, independent messages into one flat framed stream.
+
+        The encoder state is retained between calls. If :meth:`feed` previously
+        supplied an unfinished message, the first message completes it.
+        """
+        pending = [memoryview(message).cast("B").tobytes() for message in messages]
+        if not pending:
+            return b""
+
+        offsets = [0] * len(pending)
+        result = bytearray()
+        while pending:
+            count = len(pending)
+            owners: list[object | None] = []
+            pointers = (BytePointer * count)()
+            sizes = (ctypes.c_size_t * count)()
+            maximum = 0
+            for index, raw in enumerate(pending):
+                owner, pointer = _input_buffer(raw)
+                owners.append(owner)
+                offset = offsets[index]
+                pointers[index] = (
+                    ctypes.cast(ctypes.byref(owner, offset), BytePointer)
+                    if owner
+                    else pointer
+                )
+                sizes[index] = len(raw) - offset
+                maximum += int(self._lib.ccobs_encode_max_size(sizes[index]))
+
+            capacity = max(257, min(maximum, self._OUTPUT_CHUNK_SIZE))
+            output = (ctypes.c_uint8 * capacity)()
+            completed = ctypes.c_size_t(count)
+            written = ctypes.c_size_t(capacity)
+            code = self._lib.ccobs_encodev(
+                self._state,
+                pointers,
+                sizes,
+                ctypes.byref(completed),
+                output,
+                ctypes.byref(written),
+            )
+            result.extend(output[: written.value])
+
+            for index in range(min(completed.value + 1, count)):
+                offsets[index] += sizes[index]
+            if completed.value:
+                del pending[: completed.value]
+                del offsets[: completed.value]
+
+            if code == Error.NEED_OUTPUT:
+                continue
+            if code != Error.OK:
+                _raise_error(self._lib, code)
+            if completed.value != count:
+                raise CcobsError(
+                    Error.PARTIAL, "ccobs_encodev did not complete the batch"
+                )
+
+        return bytes(result)
+
+
+class Decoder(_State):
+    """Incrementally decode framed stream chunks."""
+
+    def feed(self, data: object = b"") -> tuple[bytes, int, bool]:
+        """Decode at most one frame and report whether it was completed."""
+        raw = memoryview(data).cast("B").tobytes()
+        owner, _ = _input_buffer(raw)
+        offset = 0
+        result = bytearray()
+        complete = ctypes.c_bool(False)
+        capacity = max(1, len(raw))
+        while True:
+            output = (ctypes.c_uint8 * capacity)()
+            available = ctypes.c_size_t(len(raw) - offset)
+            size = ctypes.c_size_t(capacity)
+            current = (
+                ctypes.cast(ctypes.byref(owner, offset), BytePointer)
+                if owner
+                else BytePointer()
+            )
+            code = self._lib.ccobs_decode(
+                self._state,
+                current,
+                ctypes.byref(available),
+                output,
+                ctypes.byref(size),
+                ctypes.byref(complete),
+            )
+            offset += available.value
+            result.extend(output[: size.value])
+            if code == Error.NEED_OUTPUT:
+                continue
+            if code not in (Error.OK, Error.PARTIAL):
+                _raise_error(self._lib, code)
+
+            return bytes(result), offset, complete.value
+
+    def feedv(self, data: object = b"") -> tuple[bytes, int, tuple[int, ...]]:
+        """Decode framed stream data into one flat byte string.
+
+        The decoder state is retained between calls. The returned tuple contains
+        the decoded bytes, consumed input byte count, and completed frame sizes.
+        If a frame began in a previous call, its size includes bytes returned by
+        that call.
+        """
+        raw = memoryview(data).cast("B").tobytes()
+        owner, _ = _input_buffer(raw)
+        output_capacity = max(1, len(raw))
+        output = (ctypes.c_uint8 * output_capacity)()
+        available = ctypes.c_size_t(len(raw))
+        written = ctypes.c_size_t(output_capacity)
+
+        # Every complete encoded frame ends in zero.  The extra slot lets
+        # decodev consume a partial frame following the final delimiter.
+        frame_capacity = raw.count(0) + 1
+        frame_sizes = (ctypes.c_size_t * frame_capacity)()
+        frame_count = ctypes.c_size_t(frame_capacity)
+        code = self._lib.ccobs_decodev(
+            self._state,
+            ctypes.cast(owner, BytePointer) if owner else BytePointer(),
+            ctypes.byref(available),
+            output,
+            ctypes.byref(written),
+            frame_sizes,
+            ctypes.byref(frame_count),
+        )
+        if code not in (Error.OK, Error.PARTIAL):
+            _raise_error(self._lib, code)
+
+        sizes = tuple(frame_sizes[: frame_count.value])
+        return bytes(output[: written.value]), available.value, sizes
+
+
+def encode(data: object, *, library: Optional[ctypes.CDLL] = None) -> bytes:
+    """Encode one bytes-like message, including its trailing zero delimiter."""
+    with Encoder(library) as encoder:
+        return encoder.feed(data, end_message=True)
+
+
+def encodev(
+    messages: Iterable[object], *, library: Optional[ctypes.CDLL] = None
+) -> bytes:
+    """Encode a batch of bytes-like messages into one flat framed stream."""
+    with Encoder(library) as encoder:
+        return encoder.feedv(messages)
+
+
+def decode(data: object, *, library: Optional[ctypes.CDLL] = None) -> bytes:
+    """Decode exactly one complete, zero-delimited frame."""
+    raw = memoryview(data).cast("B").tobytes()
+    with Decoder(library) as decoder:
+        output, consumed, complete = decoder.feed(raw)
+
+    if not complete:
+        raise ValueError("incomplete COBS frame")
+
+    if consumed != len(raw):
+        raise ValueError("input contains data after the first COBS frame")
+
+    return output

ccobs/_lib.py

@@ -0,0 +1,131 @@
+"""ctypes declarations and shared-library discovery for ccobs."""
+
+import ctypes
+import ctypes.util
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+class State(ctypes.Structure):
+    """Opaque ``ccobs_state``; allocate it through ``ccobs_create``."""
+
+
+# Opaque state pointer to ccobs
+StatePointer = ctypes.POINTER(State)
+
+# Miscellaneous pointer types
+BytePointer = ctypes.POINTER(ctypes.c_uint8)
+SizePointer = ctypes.POINTER(ctypes.c_size_t)
+
+
+def _library_names() -> tuple[str, ...]:
+    if sys.platform == "win32":
+        return ("ccobs.dll", "libccobs.dll")
+    if sys.platform == "darwin":
+        return ("libccobs.dylib", "ccobs.dylib")
+    return ("libccobs.so",)
+
+
+def _bundled_library_paths(package_dir: Path) -> list[str]:
+    """Return platform library names produced by the CMake build."""
+    if sys.platform == "win32":
+        patterns = ("ccobs.dll",)
+    elif sys.platform == "darwin":
+        patterns = ("libccobs.dylib",)
+    else:
+        patterns = ("libccobs.so",)
+
+    return [str(path) for pattern in patterns for path in package_dir.glob(pattern)]
+
+
+def _load_library(path: Optional[os.PathLike[str] | str] = None) -> ctypes.CDLL:
+    candidates: list[str] = []
+    explicit = path if path is not None else os.environ.get("CCOBS_LIBRARY_PATH")
+    if explicit:
+        explicit_path = Path(explicit).expanduser()
+        if explicit_path.is_dir():
+            candidates.extend(str(explicit_path / name) for name in _library_names())
+        else:
+            candidates.append(str(explicit_path))
+
+    package_dir = Path(__file__).resolve().parent
+    candidates.extend(_bundled_library_paths(package_dir))
+    candidates.extend(str(package_dir / name) for name in _library_names())
+    discovered = ctypes.util.find_library("ccobs")
+    if discovered:
+        candidates.append(discovered)
+
+    errors: list[str] = []
+    for candidate in candidates:
+        try:
+            return ctypes.CDLL(candidate)
+        except OSError as exc:
+            errors.append(f"{candidate}: {exc}")
+
+    detail = "\n".join(errors) if errors else "no library candidates were found"
+    raise OSError(
+        "Unable to load the ccobs shared library. Install it where the platform "
+        "loader can find it, or set CCOBS_LIBRARY_PATH to the library file or "
+        f"its directory. Attempts:\n{detail}"
+    )
+
+
+def bind(path: Optional[os.PathLike[str] | str] = None) -> ctypes.CDLL:
+    """Load ccobs and apply exact argument/result declarations to its C API."""
+
+    lib = _load_library(path)
+
+    # ccobs_create
+    lib.ccobs_create.argtypes = [ctypes.POINTER(ctypes.c_int)]
+    lib.ccobs_create.restype = StatePointer
+
+    # ccobs_init
+    lib.ccobs_init.argtypes = [StatePointer]
+    lib.ccobs_init.restype = ctypes.c_int
+
+    # ccobs_reset
+    lib.ccobs_reset.argtypes = [StatePointer]
+    lib.ccobs_reset.restype = ctypes.c_int
+
+    # ccobs_destroy
+    lib.ccobs_destroy.argtypes = [StatePointer]
+    lib.ccobs_destroy.restype = None
+
+    # ccobs_encode
+    lib.ccobs_encode.argtypes = [
+        StatePointer, BytePointer, SizePointer, BytePointer, SizePointer, ctypes.c_bool
+    ]
+    lib.ccobs_encode.restype = ctypes.c_int
+
+    # ccobs_decode
+    lib.ccobs_decode.argtypes = [
+        StatePointer, BytePointer, SizePointer, BytePointer, SizePointer,
+        ctypes.POINTER(ctypes.c_bool),
+    ]
+    lib.ccobs_decode.restype = ctypes.c_int
+
+    # ccobs_encode_max_size
+    lib.ccobs_encode_max_size.argtypes = [ctypes.c_size_t]
+    lib.ccobs_encode_max_size.restype = ctypes.c_size_t
+
+    # ccobs_encodev
+    lib.ccobs_encodev.argtypes = [
+        StatePointer, ctypes.POINTER(BytePointer), SizePointer, SizePointer,
+        BytePointer, SizePointer,
+    ]
+    lib.ccobs_encodev.restype = ctypes.c_int
+
+    # ccobs_decodev
+    lib.ccobs_decodev.argtypes = [
+        StatePointer, BytePointer, SizePointer, BytePointer, SizePointer,
+        SizePointer, SizePointer,
+    ]
+    lib.ccobs_decodev.restype = ctypes.c_int
+
+    # ccobs_error_string
+    lib.ccobs_error_string.argtypes = [ctypes.c_int]
+    lib.ccobs_error_string.restype = ctypes.c_char_p
+
+    return lib

pyccobs-0.1.1.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: pyccobs
+Version: 0.1.1
+Summary: Portable ctypes bindings for ccobs
+Author: Elizabeth Kiara Regina Ashford
+License-Expression: 0BSD
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: vendor/ccobs/LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# pyccobs
+
+`pyccobs` provides Python bindings to [ccobs](https://github.com/Elizafox/ccobs)
+using only the standard library's `ctypes` module. The ccobs C library is
+vendored and built into the package, so a separate ccobs installation is not
+required. It includes one-shot and streaming APIs as well as exposing the
+native library handle.
+
+## Build and use
+
+Python 3.11+ and CMake 3.15+ are required.
+
+```sh
+python -m pip install -e .
+```
+
+The package build invokes the vendored ccobs CMake project directly. Because
+the package uses `ctypes` rather than the CPython extension API, the resulting
+wheel is tagged for Python 3 generally (for example, `py3-none-win_amd64`).
+
+Set `CCOBS_LIBRARY_PATH` to a compatible shared library (or its directory) to
+override the bundled copy when testing a different ccobs build.
+
+```python
+import ccobs
+
+wire = ccobs.encode(b"hello\0world")
+assert ccobs.decode(wire) == b"hello\0world"
+
+batch = ccobs.encodev([b"first", b"", b"third"])
+assert batch == b"".join(ccobs.encode(item) for item in [b"first", b"", b"third"])
+
+encoder = ccobs.Encoder()
+wire = encoder.feed(b"hello ") + encoder.feed(b"world", end_message=True)
+wire += encoder.feedv([b"second", b"third"])
+encoder.close()
+
+decoder = ccobs.Decoder()
+decoded, used, frame_sizes = decoder.feedv(wire)
+decoder.close()
+```
+
+`Decoder.feed()` returns `(decoded_bytes, consumed_bytes, message_complete)`
+and stops after the first complete frame. `Decoder.feedv()` returns
+`(decoded_bytes, consumed_bytes, frame_sizes)` and
+decodes every complete frame in the supplied chunk in one `ccobs_decodev()`
+call. `frame_sizes` gives the decoded size of each completed frame in the flat
+output; a size may include bytes returned by an earlier partial call.
+`Encoder.feedv()` encodes a batch of complete messages through the native
+streaming vector API. Both stateful classes are context managers and have
+`reset()` and `close()`.
+
+For direct access to `ccobs_create`, `ccobs_encodev`, and the rest of the C API,
+use `ccobs.load_library()`. Its functions have their ctypes `argtypes` and
+`restype` declarations installed.

pyccobs-0.1.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+ccobs/__init__.py,sha256=0fUMmrmPt3TQeR0LS537qWcxR-XjzrNaX1NPn6U5LFg,10749
+ccobs/_lib.py,sha256=pzcQj39QUba2YvYmdxx0rMejA08SfAZfp8YzbSxroR0,4256
+ccobs/ccobs.dll,sha256=PMQnPayCVIxWPqbc0Ue72mqyIYfElxxT1wp4_Ai08ws,13312
+pyccobs-0.1.1.dist-info/licenses/LICENSE,sha256=XHm6een4gLbCb5HjVD1_gJfGuWhxrwTZYPm87gULJYM,691
+pyccobs-0.1.1.dist-info/licenses/vendor/ccobs/LICENSE,sha256=ERvxRExI2KNtyhDgYvhgfG3fp5bUhMqD0Z0W8tKwZVs,670
+pyccobs-0.1.1.dist-info/METADATA,sha256=EDWKBsNQoLa4M26qh_yrSIZD2ukdj-fpg-1_S5l07R4,2623
+pyccobs-0.1.1.dist-info/WHEEL,sha256=MeHYnn3dJDyOdmwbmKeeTp6EsuI4RKEVPLYFUebszcw,98
+pyccobs-0.1.1.dist-info/top_level.txt,sha256=MfgbKG2TnFepR57Kt4EmrpApp6FyCIxB7k_scVqIaIU,6
+pyccobs-0.1.1.dist-info/RECORD,,

pyccobs-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: false
+Tag: py3-none-win_arm64
+

pyccobs-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,15 @@
+Zero-Clause BSD
+
+Copyright (C) 2026 Elizabeth Kiara Regina Ashford
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+

pyccobs-0.1.1.dist-info/licenses/vendor/ccobs/LICENSE

@@ -0,0 +1,12 @@
+Copyright (C) 2026 Elizabeth Kiara Regina Ashford
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

pyccobs-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+ccobs