pamoja-codec 0.1.17__tar.gz

pamoja_codec-0.1.17/.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_codec-0.1.17/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_codec-0.1.17/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: pamoja-codec
+Version: 0.1.17
+Summary: CBOR, JSON, and raw codecs behind one trait, delta and varint batch packing, and an f32 quantizer for metered links.
+Project-URL: Repository, https://github.com/molexxxx/pamoja
+Project-URL: Documentation, https://pamoja.molex.cloud/docs/guides/codec.html
+Author: molexxxx
+License: MIT
+License-File: LICENSE-MIT
+Keywords: codec,iot,pamoja,robotics
+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.17
+Description-Content-Type: text/markdown
+
+# pamoja-codec
+
+CBOR, JSON, and raw codecs behind one trait, delta and varint batch packing, and an f32 quantizer for metered links. One capability of [pamoja](https://github.com/molexxxx/pamoja), one memory-safe Rust core with bindings for TypeScript, Python, and C#.
+
+[![API reference](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-api.svg)](https://pamoja.molex.cloud/docs/reference/python/pamoja/codec.html)
+[![read the guide](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-guide.svg)](https://pamoja.molex.cloud/docs/guides/codec.html)
+[![documentation](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-docs.svg)](https://pamoja.molex.cloud/docs/)
+
+## Install
+
+```sh
+pip install pamoja-codec
+```
+
+```python
+from pamoja import codec
+```
+
+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/codec.py`](https://github.com/molexxxx/pamoja/blob/main/bindings/python/guides/codec.py):
+
+```python
+import json
+
+from pamoja.codec import Quantizer, from_cbor, pack_samples, to_cbor, unpack_samples
+
+# The same reading as JSON and as CBOR. Nothing is lost, and 21.5 rides as a
+# half-precision float, the shortest form RFC 8949 allows for it.
+reading = {"c": 21.5, "ok": True}
+as_json = json.dumps(reading, separators=(",", ":")).encode()
+cbor = to_cbor(reading)
+print(f"json      {len(as_json)} bytes")
+print(f"cbor      {len(cbor)} bytes")
+
+# A gateway that speaks JSON gets it back unchanged, so the compact form is a transport
+# choice rather than a different data model.
+restored = from_cbor(cbor)
+print(f"back to json, unchanged: {restored == reading}")
+
+# A batch of readings packs to a count, then the difference between each sample and the
+# one before it. Successive readings differ by very little, so the differences cost about
+# a byte each where the samples would cost eight.
+samples = [10, 11, 13, 12, 900]
+packed = pack_samples(samples)
+print(f"batch     {len(samples)} samples in {len(packed)} bytes")
+print(f"unpacked  {unpack_samples(packed)}")
+
+# Readings that arrive as floats pack the same way once a scale is chosen. Nothing in the
+# bytes records that scale, so the sender and the receiver have to agree on it.
+quantizer = Quantizer(100)
+celsius = [20.0, 20.1, 20.2, 20.3]
+packed_celsius = quantizer.encode(celsius)
+recovered = quantizer.decode(packed_celsius)
+print(f"degrees   {len(celsius)} readings in {len(packed_celsius)} bytes")
+print(f"recovered {[round(value, 1) for value in recovered]}")
+```
+
+## The same capability in every language
+
+| Language | Package | Reference |
+| --- | --- | --- |
+| Rust | [`pamoja-codec`](https://crates.io/crates/pamoja-codec) | [reference](https://pamoja.molex.cloud/docs/reference/rust/pamoja_codec/index.html), [docs.rs](https://docs.rs/pamoja-codec), [install](https://pamoja.molex.cloud/docs/reference/rust.html#rust-codec) |
+| TypeScript | [`@pamoja/codec`](https://www.npmjs.com/package/@pamoja/codec) | [reference](https://pamoja.molex.cloud/docs/reference/node/modules/_pamoja_codec.html), [install](https://pamoja.molex.cloud/docs/reference/node.html#node-codec) |
+| Python | [`pamoja-codec`](https://pypi.org/project/pamoja-codec/) | [reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/codec.html), [install](https://pamoja.molex.cloud/docs/reference/python.html#python-codec) |
+| C# | [`Pamoja.Codec`](https://www.nuget.org/packages/Pamoja.Codec) | [reference](https://pamoja.molex.cloud/docs/reference/dotnet/api/Pamoja.Codec.html), [install](https://pamoja.molex.cloud/docs/reference/dotnet.html#dotnet-codec) |
+
+## Documentation
+
+- [`pamoja.codec` reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/codec.html), every class and function in this module.
+- [The Codecs guide](https://pamoja.molex.cloud/docs/guides/codec.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_codec-0.1.17/README.md

@@ -0,0 +1,80 @@
+# pamoja-codec
+
+CBOR, JSON, and raw codecs behind one trait, delta and varint batch packing, and an f32 quantizer for metered links. One capability of [pamoja](https://github.com/molexxxx/pamoja), one memory-safe Rust core with bindings for TypeScript, Python, and C#.
+
+[![API reference](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-api.svg)](https://pamoja.molex.cloud/docs/reference/python/pamoja/codec.html)
+[![read the guide](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-guide.svg)](https://pamoja.molex.cloud/docs/guides/codec.html)
+[![documentation](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-docs.svg)](https://pamoja.molex.cloud/docs/)
+
+## Install
+
+```sh
+pip install pamoja-codec
+```
+
+```python
+from pamoja import codec
+```
+
+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/codec.py`](https://github.com/molexxxx/pamoja/blob/main/bindings/python/guides/codec.py):
+
+```python
+import json
+
+from pamoja.codec import Quantizer, from_cbor, pack_samples, to_cbor, unpack_samples
+
+# The same reading as JSON and as CBOR. Nothing is lost, and 21.5 rides as a
+# half-precision float, the shortest form RFC 8949 allows for it.
+reading = {"c": 21.5, "ok": True}
+as_json = json.dumps(reading, separators=(",", ":")).encode()
+cbor = to_cbor(reading)
+print(f"json      {len(as_json)} bytes")
+print(f"cbor      {len(cbor)} bytes")
+
+# A gateway that speaks JSON gets it back unchanged, so the compact form is a transport
+# choice rather than a different data model.
+restored = from_cbor(cbor)
+print(f"back to json, unchanged: {restored == reading}")
+
+# A batch of readings packs to a count, then the difference between each sample and the
+# one before it. Successive readings differ by very little, so the differences cost about
+# a byte each where the samples would cost eight.
+samples = [10, 11, 13, 12, 900]
+packed = pack_samples(samples)
+print(f"batch     {len(samples)} samples in {len(packed)} bytes")
+print(f"unpacked  {unpack_samples(packed)}")
+
+# Readings that arrive as floats pack the same way once a scale is chosen. Nothing in the
+# bytes records that scale, so the sender and the receiver have to agree on it.
+quantizer = Quantizer(100)
+celsius = [20.0, 20.1, 20.2, 20.3]
+packed_celsius = quantizer.encode(celsius)
+recovered = quantizer.decode(packed_celsius)
+print(f"degrees   {len(celsius)} readings in {len(packed_celsius)} bytes")
+print(f"recovered {[round(value, 1) for value in recovered]}")
+```
+
+## The same capability in every language
+
+| Language | Package | Reference |
+| --- | --- | --- |
+| Rust | [`pamoja-codec`](https://crates.io/crates/pamoja-codec) | [reference](https://pamoja.molex.cloud/docs/reference/rust/pamoja_codec/index.html), [docs.rs](https://docs.rs/pamoja-codec), [install](https://pamoja.molex.cloud/docs/reference/rust.html#rust-codec) |
+| TypeScript | [`@pamoja/codec`](https://www.npmjs.com/package/@pamoja/codec) | [reference](https://pamoja.molex.cloud/docs/reference/node/modules/_pamoja_codec.html), [install](https://pamoja.molex.cloud/docs/reference/node.html#node-codec) |
+| Python | [`pamoja-codec`](https://pypi.org/project/pamoja-codec/) | [reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/codec.html), [install](https://pamoja.molex.cloud/docs/reference/python.html#python-codec) |
+| C# | [`Pamoja.Codec`](https://www.nuget.org/packages/Pamoja.Codec) | [reference](https://pamoja.molex.cloud/docs/reference/dotnet/api/Pamoja.Codec.html), [install](https://pamoja.molex.cloud/docs/reference/dotnet.html#dotnet-codec) |
+
+## Documentation
+
+- [`pamoja.codec` reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/codec.html), every class and function in this module.
+- [The Codecs guide](https://pamoja.molex.cloud/docs/guides/codec.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_codec-0.1.17/pamoja/codec/__init__.py

@@ -0,0 +1,104 @@
+"""Idiomatic codec facade.
+
+Python already has :mod:`json`, so this facade takes and returns ordinary values
+and does the encoding itself, leaving callers to think in documents rather than
+buffers. The conversion and the packing happen in the Rust core.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Sequence
+
+from pamoja._native import Quantizer as _NativeQuantizer
+from pamoja._native import cbor_to_json_bytes as _cbor_to_json_bytes
+from pamoja._native import decode_delta_samples as _decode_delta_samples
+from pamoja._native import encode_delta_samples as _encode_delta_samples
+from pamoja._native import json_to_cbor_bytes as _json_to_cbor_bytes
+
+__all__ = ["Quantizer", "from_cbor", "pack_samples", "to_cbor", "unpack_samples"]
+
+
+def to_cbor(value: Any) -> bytes:
+    """Encode a value as CBOR, typically much smaller than its JSON form.
+
+    :param value: Any JSON-serializable value, or the raw bytes of a JSON
+        document.
+    :returns: The CBOR encoding.
+    :raises PamojaError: If the value cannot be encoded.
+    """
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        document = bytes(value)
+    else:
+        document = json.dumps(value).encode("utf-8")
+    return _json_to_cbor_bytes(document)
+
+
+def from_cbor(cbor: bytes) -> Any:
+    """Decode a CBOR document back into an ordinary Python value.
+
+    :param cbor: The CBOR document to decode.
+    :returns: The decoded value.
+    :raises PamojaError: If the document is malformed, or holds a construct with
+        no JSON equivalent such as a non-string map key.
+    """
+    return json.loads(_cbor_to_json_bytes(bytes(cbor)).decode("utf-8"))
+
+
+def pack_samples(samples: Sequence[int]) -> bytes:
+    """Delta-encode a series of integer samples into a compact buffer.
+
+    :param samples: The samples, in order.
+    :returns: The packed encoding, far smaller than the samples for a
+        slow-moving series.
+    """
+    return _encode_delta_samples(list(samples))
+
+
+def unpack_samples(data: bytes) -> list[int]:
+    """Unpack a buffer produced by :func:`pack_samples`.
+
+    :param data: The packed encoding.
+    :returns: The samples, in order.
+    :raises PamojaError: If the buffer is malformed.
+    """
+    return _decode_delta_samples(bytes(data))
+
+
+class Quantizer:
+    """Packs float readings to a fixed precision, for a link charging per byte.
+
+    Example::
+
+        quantizer = Quantizer(100)  # keep two decimal places
+        packed = quantizer.encode([20.0, 20.1, 20.2])
+        quantizer.decode(packed)  # [20.0, 20.1, 20.2], to within 0.01
+    """
+
+    __slots__ = ("_native",)
+
+    def __init__(self, scale: float) -> None:
+        """Create a quantizer at the given precision.
+
+        :param scale: The multiplier applied before rounding; ``100`` keeps two
+            decimal places. Must be positive and finite.
+        :raises ValueError: If the scale is not positive and finite.
+        """
+        self._native = _NativeQuantizer(scale)
+
+    def encode(self, readings: Sequence[float]) -> bytes:
+        """Quantize and pack a batch of readings.
+
+        :param readings: The readings, in order.
+        :returns: The packed encoding.
+        """
+        return self._native.encode(list(readings))
+
+    def decode(self, data: bytes) -> list[float]:
+        """Unpack a batch, to within this quantizer's precision.
+
+        :param data: The encoding produced by :meth:`encode` at the same scale.
+        :returns: The readings, in order.
+        :raises PamojaError: If the buffer is malformed.
+        """
+        return self._native.decode(bytes(data))

pamoja_codec-0.1.17/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pamoja-codec"
+version = "0.1.17"
+description = "CBOR, JSON, and raw codecs behind one trait, delta and varint batch packing, and an f32 quantizer for metered links."
+readme = "README.md"
+license = { text = "MIT" }
+license-files = ["LICENSE-MIT"]
+requires-python = ">=3.10"
+authors = [{ name = "molexxxx" }]
+keywords = ["pamoja", "iot", "robotics", "codec"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pamoja-native==0.1.17",
+]
+
+[project.urls]
+Repository = "https://github.com/molexxxx/pamoja"
+Documentation = "https://pamoja.molex.cloud/docs/guides/codec.html"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pamoja"]