pyccobs 0.1.0__tar.gz

pyccobs-0.1.0/CMakeLists.txt

@@ -0,0 +1,13 @@
+cmake_minimum_required(VERSION 3.15)
+project(pyccobs LANGUAGES C)
+
+set(BUILD_SHARED_LIBS ON CACHE BOOL "Build ccobs as a shared library" FORCE)
+set(BUILD_TESTING OFF CACHE BOOL "Do not build ccobs's C tests for the wheel" FORCE)
+
+add_subdirectory(vendor/ccobs)
+
+install(
+    TARGETS ccobs
+    LIBRARY DESTINATION ccobs
+    RUNTIME DESTINATION ccobs
+)

pyccobs-0.1.0/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.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include CMakeLists.txt
+include vendor/ccobs/LICENSE
+include vendor/ccobs/README.md
+include vendor/ccobs/CMakeLists.txt
+recursive-include vendor/ccobs/include *.h
+recursive-include vendor/ccobs/src *.c

pyccobs-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: pyccobs
+Version: 0.1.0
+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.0/README.md

@@ -0,0 +1,55 @@
+# 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.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyccobs"
+version = "0.1.0"
+description = "Portable ctypes bindings for ccobs"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "0BSD"
+license-files = ["LICENSE", "vendor/ccobs/LICENSE"]
+authors = [{ name = "Elizabeth Kiara Regina Ashford" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: C",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+
+[tool.cibuildwheel]
+# ctypes wheels are independent of the Python ABI; build once per platform.
+build = ["cp311-manylinux_*", "cp311-macosx_*", "cp311-win_amd64"]
+archs = ["native"]
+before-build = 'python -m pip install "cmake>=3.15"'
+test-requires = ["pytest>=7"]
+test-sources = ["tests"]
+test-command = "python -m pytest tests"
+
+[tool.cibuildwheel.linux]
+manylinux-x86_64-image = "manylinux2014"
+manylinux-aarch64-image = "manylinux2014"

pyccobs-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyccobs-0.1.0/setup.py

@@ -0,0 +1,85 @@
+"""Build the bundled ctypes library with its native CMake project."""
+
+import os
+import subprocess
+from pathlib import Path
+
+from setuptools import Extension, setup
+from setuptools.command.bdist_wheel import bdist_wheel
+from setuptools.command.build_ext import build_ext
+
+
+class CMakeExtension(Extension):
+    """A native library built by CMake rather than setuptools's compiler."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(name, sources=[])
+
+
+class CMakeBuild(build_ext):
+    """Configure, build, and install ccobs into the staged Python package."""
+
+    def build_extension(self, ext: Extension) -> None:
+        source_dir = Path(__file__).resolve().parent
+        build_dir = Path(self.build_temp).resolve() / ext.name
+        extension_path = Path(self.get_ext_fullpath(ext.name)).resolve()
+        install_root = extension_path.parents[1]
+        config = "Debug" if self.debug else "Release"
+
+        # Don't let stale artifacts from previous builds leak into the wheel.
+        extension_path.unlink(missing_ok=True)
+        build_dir.mkdir(parents=True, exist_ok=True)
+        configure_command = [
+            "cmake",
+            "-S",
+            str(source_dir),
+            "-B",
+            str(build_dir),
+            f"-DCMAKE_BUILD_TYPE={config}",
+        ]
+        generator = os.environ.get("CMAKE_GENERATOR")
+        if generator:
+            configure_command.extend(["-G", generator])
+        if (
+            os.name == "nt"
+            and (not generator or generator.startswith("Visual Studio"))
+            and "CMAKE_GENERATOR_PLATFORM" not in os.environ
+        ):
+            architecture = {
+                "win32": "Win32",
+                "win-amd64": "x64",
+                "win-arm64": "ARM64",
+            }.get(self.plat_name)
+            if architecture:
+                configure_command.extend(["-A", architecture])
+
+        subprocess.run(configure_command, check=True)
+        subprocess.run(
+            ["cmake", "--build", str(build_dir), "--config", config], check=True
+        )
+        subprocess.run(
+            [
+                "cmake",
+                "--install",
+                str(build_dir),
+                "--config",
+                config,
+                "--prefix",
+                str(install_root),
+            ],
+            check=True,
+        )
+
+
+class PlatformWheel(bdist_wheel):
+    """Tag the ctypes wheel as Python-independent but platform-specific."""
+
+    def get_tag(self) -> tuple[str, str, str]:
+        _, _, platform = super().get_tag()
+        return "py3", "none", platform
+
+
+setup(
+    ext_modules=[CMakeExtension("ccobs._ccobs")],
+    cmdclass={"build_ext": CMakeBuild, "bdist_wheel": PlatformWheel},
+)

pyccobs-0.1.0/src/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