cbor-model 0.1.0__tar.gz

cbor_model-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: cbor-model
+Version: 0.1.0
+Summary: CBOR Model: Add CBOR and CDDL support to Pydantic models
+Keywords: serialization,cbor,cddl
+Author: William Häggqvist
+License-Expression: MIT
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: cbor2>=5.8.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Python: >=3.12
+Project-URL: repository, https://github.com/haggqvist/cbor-model
+Project-URL: issues, https://github.com/haggqvist/cbor-model/issues
+Description-Content-Type: text/markdown
+
+# CBOR Model
+
+`cbor-model` adds [CBOR] serialization and [CDDL] schema generation to [Pydantic]
+models.
+
+## Installation
+
+```bash
+pip install cbor-model
+```
+
+or with [uv]:
+
+```bash
+uv add cbor-model
+```
+
+## Quick start
+
+### Map encoding
+
+Fields are encoded as a CBOR map keyed by the integer or string supplied to
+`CBORField(key=...)`.
+
+```python
+from typing import Annotated
+from cbor_model import CBORModel, CBORField
+
+class Sensor(CBORModel):
+    name: Annotated[str, CBORField(key=0)]
+    value: Annotated[float, CBORField(key=1)]
+
+sensor = Sensor(name="temp", value=21.5)
+data = sensor.model_dump_cbor()  # a2006474656d7001fb4035800000000000
+assert Sensor.model_validate_cbor(data) == sensor
+```
+
+### Array encoding
+
+Switch to array encoding by setting `CBORConfig(encoding="array")` and using
+`CBORField(index=...)` — fields are serialized in index order.
+
+```python
+from typing import Annotated
+from cbor_model import CBORModel, CBORField, CBORConfig
+
+class Point(CBORModel):
+    cbor_config = CBORConfig(encoding="array")
+
+    x: Annotated[int, CBORField(index=0)]
+    y: Annotated[int, CBORField(index=1)]
+
+pt = Point(x=4, y=2)
+data = pt.model_dump_cbor()  # 820402
+assert Point.model_validate_cbor(data) == pt
+```
+
+### CBOR tags
+
+Wrap a field's value in a CBOR tag using `CBORField(tag=...)`, or tag the entire
+model with `CBORConfig(tag=...)`.
+
+```python
+from typing import Annotated
+from cbor_model import CBORModel, CBORField, CBORConfig
+
+class Reading(CBORModel):
+    cbor_config = CBORConfig(tag=40001)
+
+    sensor_id: Annotated[int, CBORField(key=0)]
+    raw: Annotated[bytes, CBORField(key=1, tag=40002)]
+```
+
+### Serialization context
+
+Pass a `CBORSerializationContext` to control `None` and empty-collection exclusion:
+
+```python
+from cbor_model import CBORSerializationContext
+
+ctx = CBORSerializationContext(exclude_none=False, exclude_empty=False)
+data = sensor.model_dump_cbor(context=ctx)
+```
+
+### Custom encoders
+
+Register encoders for types not natively supported by [cbor2]:
+
+```python
+import decimal
+from cbor_model import CBORConfig
+
+class MyModel(CBORModel):
+    cbor_config = CBORConfig(
+        encoders={decimal.Decimal: lambda d: str(d)}
+    )
+    amount: Annotated[decimal.Decimal, CBORField(key=0)]
+```
+
+### CDDL generation
+
+Generate a [CDDL] schema from one or more models:
+
+```python
+from cbor_model.cddl import CDDLGenerator
+
+print(CDDLGenerator().generate(Sensor))
+# Sensor = {
+#     ? 0: text,  ; name
+#     ? 1: float,  ; value
+# }
+```
+
+[CBOR]: https://cbor.io/
+[CDDL]: https://www.rfc-editor.org/rfc/rfc8610
+[Pydantic]: https://github.com/pydantic/pydantic
+[cbor2]: https://github.com/agronholm/cbor2
+[uv]: https://docs.astral.sh/uv/
+
+
+[pydantic]: https://github.com/pydantic/pydantic

cbor_model-0.1.0/README.md

@@ -0,0 +1,121 @@
+# CBOR Model
+
+`cbor-model` adds [CBOR] serialization and [CDDL] schema generation to [Pydantic]
+models.
+
+## Installation
+
+```bash
+pip install cbor-model
+```
+
+or with [uv]:
+
+```bash
+uv add cbor-model
+```
+
+## Quick start
+
+### Map encoding
+
+Fields are encoded as a CBOR map keyed by the integer or string supplied to
+`CBORField(key=...)`.
+
+```python
+from typing import Annotated
+from cbor_model import CBORModel, CBORField
+
+class Sensor(CBORModel):
+    name: Annotated[str, CBORField(key=0)]
+    value: Annotated[float, CBORField(key=1)]
+
+sensor = Sensor(name="temp", value=21.5)
+data = sensor.model_dump_cbor()  # a2006474656d7001fb4035800000000000
+assert Sensor.model_validate_cbor(data) == sensor
+```
+
+### Array encoding
+
+Switch to array encoding by setting `CBORConfig(encoding="array")` and using
+`CBORField(index=...)` — fields are serialized in index order.
+
+```python
+from typing import Annotated
+from cbor_model import CBORModel, CBORField, CBORConfig
+
+class Point(CBORModel):
+    cbor_config = CBORConfig(encoding="array")
+
+    x: Annotated[int, CBORField(index=0)]
+    y: Annotated[int, CBORField(index=1)]
+
+pt = Point(x=4, y=2)
+data = pt.model_dump_cbor()  # 820402
+assert Point.model_validate_cbor(data) == pt
+```
+
+### CBOR tags
+
+Wrap a field's value in a CBOR tag using `CBORField(tag=...)`, or tag the entire
+model with `CBORConfig(tag=...)`.
+
+```python
+from typing import Annotated
+from cbor_model import CBORModel, CBORField, CBORConfig
+
+class Reading(CBORModel):
+    cbor_config = CBORConfig(tag=40001)
+
+    sensor_id: Annotated[int, CBORField(key=0)]
+    raw: Annotated[bytes, CBORField(key=1, tag=40002)]
+```
+
+### Serialization context
+
+Pass a `CBORSerializationContext` to control `None` and empty-collection exclusion:
+
+```python
+from cbor_model import CBORSerializationContext
+
+ctx = CBORSerializationContext(exclude_none=False, exclude_empty=False)
+data = sensor.model_dump_cbor(context=ctx)
+```
+
+### Custom encoders
+
+Register encoders for types not natively supported by [cbor2]:
+
+```python
+import decimal
+from cbor_model import CBORConfig
+
+class MyModel(CBORModel):
+    cbor_config = CBORConfig(
+        encoders={decimal.Decimal: lambda d: str(d)}
+    )
+    amount: Annotated[decimal.Decimal, CBORField(key=0)]
+```
+
+### CDDL generation
+
+Generate a [CDDL] schema from one or more models:
+
+```python
+from cbor_model.cddl import CDDLGenerator
+
+print(CDDLGenerator().generate(Sensor))
+# Sensor = {
+#     ? 0: text,  ; name
+#     ? 1: float,  ; value
+# }
+```
+
+[CBOR]: https://cbor.io/
+[CDDL]: https://www.rfc-editor.org/rfc/rfc8610
+[Pydantic]: https://github.com/pydantic/pydantic
+[cbor2]: https://github.com/agronholm/cbor2
+[uv]: https://docs.astral.sh/uv/
+
+
+[pydantic]: https://github.com/pydantic/pydantic

cbor_model-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "cbor-model"
+version = "0.1.0"
+description = "CBOR Model: Add CBOR and CDDL support to Pydantic models"
+readme = "README.md"
+authors = [
+    { name = "William Häggqvist" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "cbor2>=5.8.0",
+    "pydantic>=2.12.5",
+]
+license = "MIT"
+keywords = [
+    "serialization",
+    "cbor",
+    "cddl"
+]
+
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed"
+]
+
+[project.urls]
+repository = "https://github.com/haggqvist/cbor-model"
+issues = "https://github.com/haggqvist/cbor-model/issues"
+
+[build-system]
+requires = ["uv_build>=0.10,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 88
+fix = true
+target-version = "py312"
+
+[tool.ruff.lint]
+ignore  = ["D104"]
+extend-select = ["I"]
+
+[tool.ruff.lint.per-file-ignores]
+"**/tests/*" = ["S101", "D"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.5.1",
+    "pytest>=9.0.2",
+]

cbor_model-0.1.0/src/cbor_model/__about__.py

@@ -0,0 +1,5 @@
+import importlib.metadata
+
+__author__ = "William Häggqvist"
+__application__ = "cbor-model"
+__version__ = importlib.metadata.version("cbor-model")

cbor_model-0.1.0/src/cbor_model/__init__.py

@@ -0,0 +1,16 @@
+from .__about__ import __application__, __author__, __version__
+from ._config import CBORConfig
+from ._field import CBORField
+from ._model import CBORModel, CBORSerializationContext
+from .cddl import CDDLGenerator
+
+__all__ = [
+    "CBORConfig",
+    "CBORField",
+    "CBORModel",
+    "CBORSerializationContext",
+    "CDDLGenerator",
+    "__application__",
+    "__author__",
+    "__version__",
+]

cbor_model-0.1.0/src/cbor_model/_config.py

@@ -0,0 +1,46 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+type CBOREncoders = dict[type, Callable[[Any], Any]]
+
+
+@dataclass(frozen=True, slots=True)
+class CBORConfig:
+    """Configuration options for :class:`~cbor_model.CBORModel` instances.
+
+    Attributes:
+        encoding: Whether to encode the model as a CBOR map (keyed by
+            `CBORField(key=...)`) or as a CBOR array (ordered by
+            `CBORField(index=...)`). Defaults to `"map"`.
+        tag: Wrap the encoded model in a CBOR tag with this tag number.
+            `None` disables tagging (default).
+        canonical: Use canonical CBOR encoding (deterministic key ordering
+            and minimal integer encoding). Defaults to `False`.
+        encoders: Custom encoders for types not natively supported by
+            cbor2. Keys are Python types; values are callables that
+            convert an instance of that type to a cbor2-encodable value
+            (e.g. `str`, `int`, `list`, `dict`).
+
+    """
+
+    encoding: Literal["map", "array"] = "map"
+    """Whether to encode the model as a CBOR map (key-value pairs) or array
+    (positional). Defaults to "map"."""
+
+    tag: int | None = None
+    """Wrap the CBORModel in a CBOR Tag on serialization."""
+
+    canonical: bool = False
+    """Whether to use canonical CBOR encoding. Defaults to `False`."""
+
+    encoders: CBOREncoders = field(default_factory=dict)
+    """Custom encoders for types that are not natively supported by cbor2.
+    The keys should be types, and the values should be callables that take an
+    instance of the type and return a value that can be encoded by cbor2 (e.g.
+    a string, int, list, dict, etc.)."""
+
+    def __post_init__(self) -> None:
+        if self.tag is not None and self.tag < 0:
+            err = f"CBOR tag {self.tag} is invalid. Tags must be non-negative integers."
+            raise ValueError(err)

cbor_model-0.1.0/src/cbor_model/_field.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, cast
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+CBOR2_RESERVED_TAGS = frozenset(
+    {0, 1, 2, 3, 4, 5, 25, 28, 29, 30, 35, 36, 37, 100, 256, 258, 260, 261},
+)
+"""CBOR tags reserved by cbor2 library with semantic decoders."""
+
+
+@dataclass(frozen=True, slots=True)
+class CBORField:
+    """Marks a :class:`~pydantic.BaseModel` field for CBOR serialization.
+
+    Exactly one of `key` or `index` must be provided. Attach a `CBORField` to a
+    field via :data:`typing.Annotated`:
+
+    ```python
+    from typing import Annotated
+    from cbor_model import CBORModel, CBORField
+
+    class MyModel(CBORModel):
+        name: Annotated[str, CBORField(key=0)]
+        value: Annotated[int, CBORField(key=1)]
+    ```
+
+    Attributes:
+        key: Map key used when the parent model uses `encoding="map"`. May be
+            an integer or a string.
+        index: Zero-based position used when the parent model uses
+            `encoding="array"`. Indices must be contiguous starting from 0,
+            with optional fields at the tail.
+        tag: CBOR tag number to wrap this field's value in on serialization.
+            Use values above 1000 to avoid conflicts with standard tags. See
+            `CBOR2_RESERVED_TAGS` for tags reserved by cbor2.
+        override_type: Override the CDDL type name emitted by
+            :class:`CDDLGenerator` for this field.
+        override_name: Override the CDDL field name emitted by
+            :class:`CDDLGenerator` for this field.
+        optional: Mark the field as optional in CDDL output regardless of
+            its Python type annotation.
+        exclude_if: A callable that receives the field value and returns
+            `True` if the field should be omitted from the serialized output.
+            Useful for custom exclusion logic beyond `None` or empty values.
+
+    """
+
+    key: int | str | None = None
+    index: int | None = None
+    tag: int | None = None
+    """Custom CBOR tag number. Use values >1000 to avoid conflicts with
+    standard tags.
+
+    See `CBOR2_RESERVED_TAGS` for tags reserved by cbor2 library.
+    """
+    override_type: str | None = None
+    override_name: str | None = None
+    optional: bool = False
+    exclude_if: Callable[[Any], bool] | None = None
+    """A Callable that takes the field value and returns `True` if the field should be excluded from serialization. This can be used to implement custom exclusion logic beyond just `None` or empty values."""  # noqa: E501
+
+    @property
+    def identifier(self) -> int | str:
+        """The CBOR map key or array index used to identify this field.
+
+        Returns `key` when the field belongs to a map-encoded model, or
+        `index` when it belongs to an array-encoded model.
+        """
+        return self.key if self.key is not None else cast("int", self.index)
+
+    def __post_init__(self) -> None:
+        if self.key is not None and self.index is not None:
+            err = "Cannot specify both key and index for CBORField"
+            raise ValueError(err)
+        if self.key is None and self.index is None:
+            err = "Must specify either key or index for CBORField"
+            raise ValueError(err)
+        if self.tag is not None:
+            if self.tag < 0:
+                err = f"CBOR tag {self.tag} is invalid. Tags must be non-negative integers."
+                raise ValueError(err)
+            if self.tag in CBOR2_RESERVED_TAGS:
+                err = (
+                    f"CBOR tag {self.tag} conflicts with cbor2 reserved tags. "
+                    f"Use tag values > 1000 to avoid conflicts with standard CBOR tags."
+                )
+                raise ValueError(err)