cborx 0.1.1__py3-none-any.whl

cborx/__init__.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: 0BSD
+"""Pure-Python CBOR (RFC 8949) encoder/decoder. No dependencies, no Rust."""
+
+from .decoder import CBORDecoder, DuplicateMode, TagHook, load, loads
+from .encoder import CBOREncoder, DefaultCallback, dump, dumps
+from .exceptions import CBORDecodeError, CBOREncodeError, CBORError
+from .types import CBORSimpleValue, CBORTag, UndefinedType, undefined
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "CBORDecodeError",
+    "CBORDecoder",
+    "CBOREncodeError",
+    "CBOREncoder",
+    "CBORError",
+    "CBORSimpleValue",
+    "CBORTag",
+    "DefaultCallback",
+    "DuplicateMode",
+    "TagHook",
+    "UndefinedType",
+    "dump",
+    "dumps",
+    "load",
+    "loads",
+    "undefined",
+]

cborx/_util.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: 0BSD
+"""Shared internal helpers."""
+
+import math
+import struct
+
+
+def float_min_ai(value: float) -> int:
+    """Return the smallest float additional-info width preserving a value.
+
+    The result is one of the CBOR additional information values 25
+    (half), 26 (single) or 27 (double). NaN maps to 25, the preferred
+    encoding 0xf97e00.
+    """
+    if math.isnan(value):
+        return 25
+    if _fits(">e", value):
+        return 25
+    if _fits(">f", value):
+        return 26
+    return 27
+
+
+def _fits(fmt: str, value: float) -> bool:
+    """True if value survives a round trip through format fmt."""
+    try:
+        return bool(struct.unpack(fmt, struct.pack(fmt, value))[0] == value)
+    except OverflowError:
+        return False

cborx/decoder.py

@@ -0,0 +1,456 @@
+# SPDX-License-Identifier: 0BSD
+"""Hardened iterative CBOR decoder (RFC 8949)."""
+
+import struct
+from collections.abc import Callable
+from datetime import date, datetime, timedelta, timezone
+from typing import Any, BinaryIO, Literal
+
+from ._util import float_min_ai
+from .exceptions import CBORDecodeError
+from .types import CBORSimpleValue, CBORTag, undefined
+
+TagHook = Callable[["CBORDecoder", CBORTag], Any]
+"""Called for every decoded tag when provided.
+
+Receives the decoder and a CBORTag. The return value replaces the item.
+When a tag_hook is set it overrides all built-in semantic tag handling.
+"""
+
+DuplicateMode = Literal["last", "first", "error"]
+
+_MISSING = object()
+_ARR, _MAP, _TAG = 0, 1, 2
+
+_FLOAT_FORMATS: dict[int, tuple[int, str]] = {
+    25: (2, ">e"),
+    26: (4, ">f"),
+    27: (8, ">d"),
+}
+_MINIMAL_ARG = {1: 24, 2: 0x100, 4: 0x10000, 8: 0x100000000}
+_EPOCH_DATE = date(1970, 1, 1)
+
+
+class _Frame:
+    """One open container or tag on the decode work stack."""
+
+    __slots__ = ("items", "kind", "prev_key", "remaining", "start", "tag")
+
+    def __init__(self, kind: int, remaining: int, start: int, tag: int = 0) -> None:
+        self.kind = kind
+        self.remaining = remaining  # -1 means indefinite length
+        self.items: list[Any] = []
+        self.tag = tag
+        self.start = start
+        self.prev_key: bytes | None = None
+
+
+class CBORDecoder:
+    """Decode CBOR data items.
+
+    Decoding is iterative with an explicit work stack: nesting depth is
+    bounded by max_depth and never by the Python call stack.
+    """
+
+    def __init__(
+        self,
+        *,
+        tag_hook: TagHook | None = None,
+        strict_utf8: bool = True,
+        max_depth: int = 200,
+        allow_indefinite: bool = True,
+        canonical: bool = False,
+        duplicate_keys: DuplicateMode = "last",
+    ) -> None:
+        if max_depth < 1:
+            raise ValueError("max_depth must be at least 1")
+        if duplicate_keys not in ("last", "first", "error"):
+            raise ValueError(f"invalid duplicate_keys mode {duplicate_keys!r}")
+        self._tag_hook = tag_hook
+        self._utf8_errors = "strict" if strict_utf8 else "replace"
+        self._max_depth = max_depth
+        self._allow_indefinite = allow_indefinite
+        self._canonical = canonical
+        self._duplicate_keys = duplicate_keys
+
+    def decode(
+        self, data: bytes | bytearray | memoryview, *, allow_trailing: bool = False
+    ) -> Any:
+        """Decode a single data item from data.
+
+        Raises CBORDecodeError on trailing bytes unless allow_trailing is
+        set.
+        """
+        value, pos = self.decode_item(data, 0)
+        if not allow_trailing and pos != len(data):
+            raise CBORDecodeError(f"trailing data at offset {pos}")
+        return value
+
+    def decode_item(
+        self, data: bytes | bytearray | memoryview, pos: int = 0
+    ) -> tuple[Any, int]:
+        """Decode one data item starting at pos and return (value, new pos)."""
+        mv = data if isinstance(data, memoryview) else memoryview(data)
+        frames: list[_Frame] = []
+        value: Any = _MISSING
+        start = end = pos
+        while True:
+            if value is _MISSING:
+                value, start, end = self._read_one(mv, pos, frames)
+                pos = end
+                if value is _MISSING:
+                    continue  # a container or tag frame was pushed
+            while value is not _MISSING:
+                if not frames:
+                    return value, end
+                frame = frames[-1]
+                if frame.kind == _TAG:
+                    frames.pop()
+                    value = self._apply_tag(frame.tag, value)
+                    start = frame.start
+                    continue
+                if frame.kind == _MAP and len(frame.items) % 2 == 0 and self._canonical:
+                    self._check_key_order(mv, frame, start, end)
+                frame.items.append(value)
+                if frame.remaining > 0:
+                    frame.remaining -= 1
+                if frame.remaining == 0:
+                    frames.pop()
+                    value = self._finish(frame)
+                    start = frame.start
+                    continue
+                value = _MISSING
+
+    @staticmethod
+    def _check_key_order(mv: memoryview, frame: _Frame, start: int, end: int) -> None:
+        key = bytes(mv[start:end])
+        prev = frame.prev_key
+        if prev is not None and (len(key), key) <= (len(prev), prev):
+            raise CBORDecodeError("map keys are not in canonical order")
+        frame.prev_key = key
+
+    def _read_one(
+        self, mv: memoryview, pos: int, frames: list[_Frame]
+    ) -> tuple[Any, int, int]:
+        """Read one item header and return (value or _MISSING, start, end)."""
+        start = pos
+        if pos >= len(mv):
+            raise CBORDecodeError("unexpected end of input")
+        head = mv[pos]
+        pos += 1
+        major = head >> 5
+        ai = head & 0x1F
+        if ai == 0x1F:
+            return self._read_indefinite(mv, pos, start, major, frames)
+        if ai > 0x1B:
+            raise CBORDecodeError(
+                f"reserved additional information {ai} at offset {start}"
+            )
+        if major == 7:
+            return self._read_simple_or_float(mv, pos, start, ai)
+        arg, pos = self._read_arg(mv, pos, ai)
+        if major == 0:
+            return arg, start, pos
+        if major == 1:
+            return -1 - arg, start, pos
+        if major == 2 or major == 3:
+            return self._read_string(mv, pos, start, major, arg)
+        return self._open_container(pos, start, major, arg, frames)
+
+    def _read_indefinite(
+        self, mv: memoryview, pos: int, start: int, major: int, frames: list[_Frame]
+    ) -> tuple[Any, int, int]:
+        if major == 7:
+            # Break byte: only valid closing an indefinite container.
+            if frames and frames[-1].remaining == -1:
+                frame = frames.pop()
+                if frame.kind == _MAP and len(frame.items) % 2 != 0:
+                    raise CBORDecodeError("indefinite-length map has an odd item count")
+                return self._finish(frame), frame.start, pos
+            raise CBORDecodeError(
+                f"break byte outside indefinite-length item at offset {start}"
+            )
+        if major in (0, 1, 6):
+            raise CBORDecodeError(
+                f"indefinite length not allowed for major type {major} "
+                f"at offset {start}"
+            )
+        if not self._allow_indefinite:
+            raise CBORDecodeError(
+                f"indefinite-length item not permitted at offset {start}"
+            )
+        if self._canonical:
+            raise CBORDecodeError(
+                f"indefinite-length item is not canonical at offset {start}"
+            )
+        if major in (2, 3):
+            return self._read_indef_string(mv, pos, start, major)
+        if len(frames) >= self._max_depth:
+            raise CBORDecodeError(
+                f"maximum depth {self._max_depth} exceeded at offset {start}"
+            )
+        frames.append(_Frame(_ARR if major == 4 else _MAP, -1, start))
+        return _MISSING, start, pos
+
+    def _read_arg(self, mv: memoryview, pos: int, ai: int) -> tuple[int, int]:
+        if ai < 24:
+            return ai, pos
+        nbytes = 1 << (ai - 24)  # ai 24..27 gives 1, 2, 4, 8
+        if pos + nbytes > len(mv):
+            raise CBORDecodeError("truncated integer argument")
+        arg = int.from_bytes(mv[pos : pos + nbytes], "big")
+        pos += nbytes
+        if self._canonical and arg < _MINIMAL_ARG[nbytes]:
+            raise CBORDecodeError("non-minimal integer encoding")
+        return arg, pos
+
+    def _read_string(
+        self, mv: memoryview, pos: int, start: int, major: int, arg: int
+    ) -> tuple[Any, int, int]:
+        # Check the declared length against remaining input before
+        # touching it, so a forged huge length fails cheaply.
+        if arg > len(mv) - pos:
+            raise CBORDecodeError(
+                f"declared length {arg} exceeds {len(mv) - pos} "
+                f"remaining bytes at offset {start}"
+            )
+        raw = bytes(mv[pos : pos + arg])
+        pos += arg
+        if major == 2:
+            return raw, start, pos
+        return self._decode_text(raw), start, pos
+
+    def _read_indef_string(
+        self, mv: memoryview, pos: int, start: int, major: int
+    ) -> tuple[Any, int, int]:
+        parts: list[bytes] = []
+        while True:
+            if pos >= len(mv):
+                raise CBORDecodeError("unterminated indefinite-length string")
+            head = mv[pos]
+            pos += 1
+            if head == 0xFF:
+                break
+            if head >> 5 != major:
+                raise CBORDecodeError("wrong chunk type in indefinite-length string")
+            ai = head & 0x1F
+            if ai >= 28:
+                raise CBORDecodeError(
+                    "invalid chunk header in indefinite-length string"
+                )
+            arg, pos = self._read_arg(mv, pos, ai)
+            if arg > len(mv) - pos:
+                raise CBORDecodeError("declared chunk length exceeds remaining input")
+            parts.append(bytes(mv[pos : pos + arg]))
+            pos += arg
+        if major == 2:
+            return b"".join(parts), start, pos
+        return "".join(self._decode_text(chunk) for chunk in parts), start, pos
+
+    def _read_simple_or_float(  # noqa: C901
+        self, mv: memoryview, pos: int, start: int, ai: int
+    ) -> tuple[Any, int, int]:
+        if ai < 20:
+            return CBORSimpleValue(ai), start, pos
+        if ai == 20:
+            return False, start, pos
+        if ai == 21:
+            return True, start, pos
+        if ai == 22:
+            return None, start, pos
+        if ai == 23:
+            return undefined, start, pos
+        if ai == 24:
+            if pos >= len(mv):
+                raise CBORDecodeError("truncated simple value")
+            value = mv[pos]
+            pos += 1
+            if self._canonical and value < 24:
+                raise CBORDecodeError("non-minimal simple value encoding")
+            if value == 20:
+                return False, start, pos
+            if value == 21:
+                return True, start, pos
+            if value == 22:
+                return None, start, pos
+            if value == 23:
+                return undefined, start, pos
+            return CBORSimpleValue(value), start, pos
+        nbytes, fmt = _FLOAT_FORMATS[ai]
+        if pos + nbytes > len(mv):
+            raise CBORDecodeError("truncated float")
+        fval = float(struct.unpack(fmt, mv[pos : pos + nbytes])[0])
+        pos += nbytes
+        if self._canonical and float_min_ai(fval) != ai:
+            raise CBORDecodeError("float is not in shortest form")
+        return fval, start, pos
+
+    def _open_container(
+        self, pos: int, start: int, major: int, arg: int, frames: list[_Frame]
+    ) -> tuple[Any, int, int]:
+        # The claimed length only sizes the item budget, so nothing is
+        # allocated up front, so forged counts fail at end of input.
+        if major == 4:
+            if arg == 0:
+                return [], start, pos
+            if len(frames) >= self._max_depth:
+                raise CBORDecodeError(
+                    f"maximum depth {self._max_depth} exceeded at offset {start}"
+                )
+            frames.append(_Frame(_ARR, arg, start))
+        elif major == 5:
+            if arg == 0:
+                return {}, start, pos
+            if len(frames) >= self._max_depth:
+                raise CBORDecodeError(
+                    f"maximum depth {self._max_depth} exceeded at offset {start}"
+                )
+            frames.append(_Frame(_MAP, arg * 2, start))
+        else:  # major == 6, tag: arg is the tag number, needs one item
+            if len(frames) >= self._max_depth:
+                raise CBORDecodeError(
+                    f"maximum depth {self._max_depth} exceeded at offset {start}"
+                )
+            frames.append(_Frame(_TAG, 1, start, arg))
+        return _MISSING, start, pos
+
+    def _decode_text(self, raw: bytes) -> str:
+        try:
+            return raw.decode("utf-8", self._utf8_errors)
+        except UnicodeDecodeError as e:
+            raise CBORDecodeError("invalid UTF-8 in text string") from e
+
+    def _finish(self, frame: _Frame) -> Any:
+        if frame.kind == _ARR:
+            return frame.items
+        items = frame.items
+        result: dict[Any, Any] = {}
+        try:
+            if self._duplicate_keys == "error":
+                for i in range(0, len(items), 2):
+                    key = items[i]
+                    if key in result:
+                        raise CBORDecodeError(f"duplicate map key {key!r}")
+                    result[key] = items[i + 1]
+            elif self._duplicate_keys == "first":
+                for i in range(0, len(items), 2):
+                    result.setdefault(items[i], items[i + 1])
+            else:
+                for i in range(0, len(items), 2):
+                    result[items[i]] = items[i + 1]
+        except TypeError as e:
+            raise CBORDecodeError("unhashable map key") from e
+        return result
+
+    def _apply_tag(self, tag: int, value: Any) -> Any:
+        if self._tag_hook is not None:
+            return self._tag_hook(self, CBORTag(tag, value))
+        if tag == 0:
+            return _decode_datetime(value)
+        if tag == 1:
+            return _decode_epoch(value)
+        if tag == 2:
+            return _decode_bignum(value, negative=False)
+        if tag == 3:
+            return _decode_bignum(value, negative=True)
+        if tag == 32:
+            # URI: returned as a plain str, since Python has no URI scalar type.
+            if not isinstance(value, str):
+                raise CBORDecodeError("tag 32 (URI) must wrap a text string")
+            return value
+        if tag == 55799:
+            # Self-described CBOR: pass the enclosed item through.
+            return value
+        if tag == 1004:
+            return _decode_tag_date(value)
+        return CBORTag(tag, value)
+
+
+def _decode_datetime(value: Any) -> datetime:
+    if not isinstance(value, str):
+        raise CBORDecodeError("tag 0 must wrap a text string")
+    text = value[:-1] + "+00:00" if value.endswith("Z") else value
+    try:
+        return datetime.fromisoformat(text)
+    except ValueError as e:
+        raise CBORDecodeError(f"malformed tag 0 datetime string {value!r}") from e
+
+
+def _decode_epoch(value: Any) -> datetime:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise CBORDecodeError("tag 1 must wrap a number")
+    try:
+        return datetime.fromtimestamp(value, tz=timezone.utc)
+    except (OverflowError, OSError, ValueError) as e:
+        raise CBORDecodeError(f"tag 1 timestamp {value!r} out of range") from e
+
+
+def _decode_bignum(value: Any, *, negative: bool) -> int:
+    if not isinstance(value, bytes):
+        raise CBORDecodeError("bignum tag must wrap a byte string")
+    magnitude = int.from_bytes(value, "big")
+    return -1 - magnitude if negative else magnitude
+
+
+def _decode_tag_date(value: Any) -> date:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise CBORDecodeError("tag 1004 must wrap an integer day count")
+    try:
+        return _EPOCH_DATE + timedelta(days=value)
+    except OverflowError as e:
+        raise CBORDecodeError(f"tag 1004 day count {value} out of range") from e
+
+
+def loads(
+    data: bytes | bytearray | memoryview,
+    *,
+    tag_hook: TagHook | None = None,
+    strict_utf8: bool = True,
+    max_depth: int = 200,
+    allow_indefinite: bool = True,
+    canonical: bool = False,
+    duplicate_keys: DuplicateMode = "last",
+    allow_trailing: bool = False,
+) -> Any:
+    """Decode a single CBOR data item from data.
+
+    canonical=True enforces RFC 8949 preferred serialization: non-minimal
+    integers, non-shortest floats, indefinite lengths and unsorted map
+    keys are rejected. duplicate_keys selects "last" (keep the last
+    value), "first" or "error" handling for repeated map keys.
+    """
+    return CBORDecoder(
+        tag_hook=tag_hook,
+        strict_utf8=strict_utf8,
+        max_depth=max_depth,
+        allow_indefinite=allow_indefinite,
+        canonical=canonical,
+        duplicate_keys=duplicate_keys,
+    ).decode(data, allow_trailing=allow_trailing)
+
+
+def load(
+    fp: BinaryIO,
+    *,
+    tag_hook: TagHook | None = None,
+    strict_utf8: bool = True,
+    max_depth: int = 200,
+    allow_indefinite: bool = True,
+    canonical: bool = False,
+    duplicate_keys: DuplicateMode = "last",
+) -> Any:
+    """Decode one CBOR data item from a binary file-like object.
+
+    The stream is read to end. The first data item is decoded and any
+    remaining bytes are ignored, matching single-item stream semantics.
+    """
+    return loads(
+        fp.read(),
+        tag_hook=tag_hook,
+        strict_utf8=strict_utf8,
+        max_depth=max_depth,
+        allow_indefinite=allow_indefinite,
+        canonical=canonical,
+        duplicate_keys=duplicate_keys,
+        allow_trailing=True,
+    )

cborx/encoder.py

@@ -0,0 +1,335 @@
+# SPDX-License-Identifier: 0BSD
+"""CBOR encoder (RFC 8949)."""
+
+import io
+import struct
+from collections.abc import Callable
+from datetime import date, datetime, timezone
+from typing import Any, BinaryIO
+
+from ._util import float_min_ai
+from .exceptions import CBOREncodeError
+from .types import CBORSimpleValue, CBORTag, UndefinedType, undefined
+
+_UINT64_MAX = (1 << 64) - 1
+_EPOCH_DATE = date(1970, 1, 1)
+
+DefaultCallback = Callable[["CBOREncoder", Any], Any]
+"""Called for objects with no built-in encoding.
+
+The callback may either call encoder.encode(substitute) or return a
+substitute object, which is then encoded in place of the original.
+"""
+
+
+def _to_bignum(value: int) -> bytes:
+    return value.to_bytes((value.bit_length() + 7) // 8, "big")
+
+
+class CBOREncoder:
+    """Encode Python objects to a binary stream as CBOR."""
+
+    def __init__(
+        self,
+        fp: BinaryIO,
+        *,
+        canonical: bool = False,
+        indefinite: bool = False,
+        datetime_as_timestamp: bool = False,
+        default: DefaultCallback | None = None,
+        max_depth: int = 200,
+    ) -> None:
+        if canonical and indefinite:
+            raise ValueError("canonical and indefinite encoding are mutually exclusive")
+        self._fp = fp
+        self._canonical = canonical
+        self._indefinite = indefinite
+        self._datetime_as_timestamp = datetime_as_timestamp
+        self._default = default
+        self._max_depth = max_depth
+        self._active: bytearray | None = None
+
+    def encode(self, obj: Any) -> None:
+        """Write obj to the stream as a single CBOR data item."""
+        active = self._active
+        if active is not None:
+            # Nested call from a default callback: append in place so the
+            # substituted bytes land at the correct position.
+            self._encode(obj, active, 0)
+            return
+        buf = bytearray()
+        try:
+            self._encode(obj, buf, 0)
+        except RecursionError as e:
+            raise CBOREncodeError("object graph too deep to encode") from e
+        self._fp.write(bytes(buf))
+
+    def _encode(self, obj: Any, buf: bytearray, depth: int) -> None:
+        if depth > self._max_depth:
+            raise CBOREncodeError("maximum container depth exceeded")
+        prev = self._active
+        self._active = buf
+        try:
+            self._write_item(obj, buf, depth)
+        finally:
+            self._active = prev
+
+    def _write_item(self, obj: Any, buf: bytearray, depth: int) -> None:  # noqa: C901
+        if obj is None:
+            buf.append(0xF6)
+        elif obj is True:
+            buf.append(0xF5)
+        elif obj is False:
+            buf.append(0xF4)
+        elif obj is undefined:
+            buf.append(0xF7)
+        elif isinstance(obj, int):
+            self._write_int(obj, buf)
+        elif isinstance(obj, float):
+            self._write_float(obj, buf)
+        elif isinstance(obj, str):
+            self._write_text(obj, buf)
+        elif isinstance(obj, (bytes, bytearray, memoryview)):
+            self._write_bytes(bytes(obj), buf)
+        elif isinstance(obj, CBORTag):
+            self._write_tag(obj, buf, depth)
+        elif isinstance(obj, CBORSimpleValue):
+            self._write_simple(obj, buf)
+        elif isinstance(obj, UndefinedType):
+            buf.append(0xF7)
+        elif isinstance(obj, datetime):
+            self._write_datetime(obj, buf, depth)
+        elif isinstance(obj, date):
+            self._write_date(obj, buf, depth)
+        elif isinstance(obj, (list, tuple)):
+            self._write_array(obj, buf, depth)
+        elif isinstance(obj, dict):
+            self._write_map(obj, buf, depth)
+        else:
+            self._write_default(obj, buf, depth)
+
+    @staticmethod
+    def _write_head(buf: bytearray, major: int, arg: int) -> None:
+        if arg < 0 or arg > _UINT64_MAX:
+            raise CBOREncodeError(f"argument {arg} out of range for CBOR header")
+        base = major << 5
+        if arg < 24:
+            buf.append(base | arg)
+        elif arg <= 0xFF:
+            buf += bytes((base | 24, arg))
+        elif arg <= 0xFFFF:
+            buf.append(base | 25)
+            buf += arg.to_bytes(2, "big")
+        elif arg <= 0xFFFFFFFF:
+            buf.append(base | 26)
+            buf += arg.to_bytes(4, "big")
+        else:
+            buf.append(base | 27)
+            buf += arg.to_bytes(8, "big")
+
+    def _write_int(self, n: int, buf: bytearray) -> None:
+        if n >= 0:
+            if n <= _UINT64_MAX:
+                self._write_head(buf, 0, n)
+            else:
+                self._write_head(buf, 6, 2)
+                self._write_bytes(_to_bignum(n), buf)
+        else:
+            magnitude = -1 - n
+            if magnitude <= _UINT64_MAX:
+                self._write_head(buf, 1, magnitude)
+            else:
+                self._write_head(buf, 6, 3)
+                self._write_bytes(_to_bignum(magnitude), buf)
+
+    def _write_float(self, value: float, buf: bytearray) -> None:
+        ai = float_min_ai(value) if self._canonical else 27
+        if ai == 25:
+            buf.append(0xF9)
+            buf += struct.pack(">e", value)
+        elif ai == 26:
+            buf.append(0xFA)
+            buf += struct.pack(">f", value)
+        else:
+            buf.append(0xFB)
+            buf += struct.pack(">d", value)
+
+    def _write_text(self, s: str, buf: bytearray) -> None:
+        try:
+            raw = s.encode("utf-8")
+        except UnicodeEncodeError as e:
+            raise CBOREncodeError("text string contains lone surrogates") from e
+        if self._indefinite:
+            buf.append(0x7F)
+            self._write_head(buf, 3, len(raw))
+            buf += raw
+            buf.append(0xFF)
+            return
+        self._write_head(buf, 3, len(raw))
+        buf += raw
+
+    def _write_bytes(self, raw: bytes, buf: bytearray) -> None:
+        if self._indefinite:
+            buf.append(0x5F)
+            self._write_head(buf, 2, len(raw))
+            buf += raw
+            buf.append(0xFF)
+            return
+        self._write_head(buf, 2, len(raw))
+        buf += raw
+
+    def _write_tag(self, obj: CBORTag, buf: bytearray, depth: int) -> None:
+        if isinstance(obj.tag, bool) or not isinstance(obj.tag, int):
+            raise CBOREncodeError("CBORTag tag must be an integer")
+        self._write_head(buf, 6, obj.tag)
+        self._encode(obj.value, buf, depth + 1)
+
+    @staticmethod
+    def _write_simple(obj: CBORSimpleValue, buf: bytearray) -> None:
+        value = obj.value
+        if (
+            isinstance(value, bool)
+            or not isinstance(value, int)
+            or not 0 <= value <= 0xFF
+        ):
+            raise CBOREncodeError(f"simple value {value!r} out of range 0..255")
+        if 24 <= value <= 31:
+            raise CBOREncodeError(f"simple value {value} is reserved")
+        if value < 24:
+            buf.append(0xE0 | value)
+        else:
+            buf += bytes((0xF8, value))
+
+    def _write_datetime(self, obj: datetime, buf: bytearray, depth: int) -> None:
+        if self._datetime_as_timestamp:
+            aware = obj if obj.tzinfo is not None else obj.replace(tzinfo=timezone.utc)
+            timestamp = float(aware.timestamp())
+            self._write_head(buf, 6, 1)
+            self._encode(
+                int(timestamp) if timestamp.is_integer() else timestamp, buf, depth + 1
+            )
+            return
+        text = obj.isoformat()
+        if text.endswith("+00:00"):
+            text = text[:-6] + "Z"
+        self._write_head(buf, 6, 0)
+        self._encode(text, buf, depth + 1)
+
+    def _write_date(self, obj: date, buf: bytearray, depth: int) -> None:
+        # RFC 8949 calendar date: tag 1004, days since 1970-01-01.
+        self._write_head(buf, 6, 1004)
+        self._encode((obj - _EPOCH_DATE).days, buf, depth + 1)
+
+    def _write_array(
+        self, obj: list[Any] | tuple[Any, ...], buf: bytearray, depth: int
+    ) -> None:
+        if self._indefinite:
+            buf.append(0x9F)
+            for item in obj:
+                self._encode(item, buf, depth + 1)
+            buf.append(0xFF)
+            return
+        self._write_head(buf, 4, len(obj))
+        for item in obj:
+            self._encode(item, buf, depth + 1)
+
+    def _write_map(self, obj: dict[Any, Any], buf: bytearray, depth: int) -> None:
+        if self._indefinite:
+            buf.append(0xBF)
+            for key, value in obj.items():
+                self._encode(key, buf, depth + 1)
+                self._encode(value, buf, depth + 1)
+            buf.append(0xFF)
+            return
+        self._write_head(buf, 5, len(obj))
+        if self._canonical:
+            pairs = [(self._key_bytes(key, depth), value) for key, value in obj.items()]
+            pairs.sort(key=lambda pair: (len(pair[0]), pair[0]))
+            for key_bytes, value in pairs:
+                buf += key_bytes
+                self._encode(value, buf, depth + 1)
+        else:
+            for key, value in obj.items():
+                self._encode(key, buf, depth + 1)
+                self._encode(value, buf, depth + 1)
+
+    def _key_bytes(self, key: Any, depth: int) -> bytes:
+        buf = bytearray()
+        self._encode(key, buf, depth + 1)
+        return bytes(buf)
+
+    def _write_default(self, obj: Any, buf: bytearray, depth: int) -> None:
+        if self._default is None:
+            raise CBOREncodeError(f"cannot encode object of type {type(obj).__name__}")
+        before = len(buf)
+        substitute = self._default(self, obj)
+        wrote = len(buf) != before
+        if substitute is None:
+            if not wrote:
+                # Emitting nothing would silently corrupt the stream (a
+                # map would lose its value).
+                raise CBOREncodeError(
+                    f"default callback emitted nothing for {type(obj).__name__}"
+                )
+            return
+        if wrote:
+            raise CBOREncodeError(
+                "default callback both wrote via encode() and returned a value"
+            )
+        if substitute is obj:
+            raise CBOREncodeError("default callback returned the object it was given")
+        self._encode(substitute, buf, depth + 1)
+
+
+def dumps(
+    obj: Any,
+    *,
+    canonical: bool = False,
+    indefinite: bool = False,
+    datetime_as_timestamp: bool = False,
+    default: DefaultCallback | None = None,
+    max_depth: int = 200,
+) -> bytes:
+    """Encode obj to CBOR and return the bytes.
+
+    canonical selects deterministic encoding per RFC 8949 section 4.2:
+    shortest-form integers, shortest preserving floats, definite lengths
+    and map keys sorted by encoded key bytes (shorter first, then
+    lexicographic). indefinite emits indefinite-length byte strings,
+    text strings, arrays and maps instead of definite ones. It cannot
+    be combined with canonical. datetime_as_timestamp encodes datetime
+    as tag 1 (seconds since epoch, naive treated as UTC) instead of
+    tag 0 (ISO 8601 text). default handles otherwise unencodable
+    objects.
+    """
+    fp = io.BytesIO()
+    CBOREncoder(
+        fp,
+        canonical=canonical,
+        indefinite=indefinite,
+        datetime_as_timestamp=datetime_as_timestamp,
+        default=default,
+        max_depth=max_depth,
+    ).encode(obj)
+    return fp.getvalue()
+
+
+def dump(
+    obj: Any,
+    fp: BinaryIO,
+    *,
+    canonical: bool = False,
+    indefinite: bool = False,
+    datetime_as_timestamp: bool = False,
+    default: DefaultCallback | None = None,
+    max_depth: int = 200,
+) -> None:
+    """Encode obj to CBOR and write it to a binary file-like object."""
+    CBOREncoder(
+        fp,
+        canonical=canonical,
+        indefinite=indefinite,
+        datetime_as_timestamp=datetime_as_timestamp,
+        default=default,
+        max_depth=max_depth,
+    ).encode(obj)

cborx/exceptions.py

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: 0BSD
+"""Exception hierarchy for cborx."""
+
+
+class CBORError(Exception):
+    """Base class for all cborx errors."""
+
+
+class CBOREncodeError(CBORError):
+    """Raised when an object cannot be encoded as CBOR."""
+
+
+class CBORDecodeError(CBORError):
+    """Raised when input bytes cannot be decoded as CBOR."""

cborx/types.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: 0BSD
+"""Public value types for the CBOR codec."""
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class CBORTag:
+    """A CBOR semantic tag (major type 6) wrapping a value.
+
+    Tags without built-in handling decode to CBORTag. Encoding a CBORTag
+    writes the tag header followed by the encoded value.
+    """
+
+    tag: int
+    value: Any
+
+
+@dataclass(frozen=True, slots=True)
+class CBORSimpleValue:
+    """An unassigned CBOR simple value (major type 7).
+
+    Values 20, 21, 22 and 23 are the named simple values false, true, null
+    and undefined and are never wrapped: decoding yields False, True, None
+    and undefined instead. Values 24 through 31 are reserved by RFC 8949
+    and are rejected by the encoder.
+    """
+
+    value: int
+
+
+class UndefinedType:
+    """Type of the undefined sentinel."""
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "undefined"
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, UndefinedType)
+
+    def __hash__(self) -> int:
+        return hash(UndefinedType)
+
+    def __copy__(self) -> "UndefinedType":
+        return self
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> "UndefinedType":
+        return self
+
+
+undefined = UndefinedType()
+"""Sentinel for the CBOR simple value undefined (0xf7)."""

cborx-0.1.1.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.5
+Name: cborx
+Version: 0.1.1
+Summary: Pure-Python CBOR (RFC 8949) encoder/decoder. No dependencies, no Rust.
+Project-URL: Homepage, https://quad4.io
+Project-URL: Repository, https://github.com/Quad4-Software/cborx
+Project-URL: Issues, https://github.com/Quad4-Software/cborx/issues
+Project-URL: Changelog, https://github.com/Quad4-Software/cborx/blob/master/CHANGELOG.md
+Author: Quad4
+License-Expression: 0BSD
+License-File: LICENSE
+Keywords: binary,cbor,codec,rfc8949,serialization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# cborx
+
+[![CI](https://github.com/Quad4-Software/cborx/actions/workflows/ci.yml/badge.svg)](https://github.com/Quad4-Software/cborx/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/Quad4-Software/cborx/actions/workflows/codeql.yml/badge.svg)](https://github.com/Quad4-Software/cborx/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/Quad4-Software/cborx/badge)](https://securityscorecards.dev/viewer/?uri=github.com/Quad4-Software/cborx)
+[![PyPI](https://img.shields.io/pypi/v/cborx)](https://pypi.org/project/cborx/)
+[![License: 0BSD](https://img.shields.io/badge/license-0BSD-blue)](LICENSE)
+
+Pure-Python CBOR (RFC 8949) encoder/decoder. No dependencies, no Rust.
+
+A hardened, fully typed replacement for cbor2 without a native
+extension. The decoder is iterative, bounds every claimed length
+against the remaining input, and enforces a configurable nesting
+limit, so hostile input fails fast instead of exhausting memory or
+the call stack.
+
+## Install
+
+```sh
+pip install cborx
+```
+
+## Usage
+
+```python
+import cborx
+
+data = cborx.dumps({"a": [1, 2, 3], "b": None})
+assert cborx.loads(data) == {"a": [1, 2, 3], "b": None}
+
+# Deterministic encoding: shortest-form integers and floats, map keys
+# sorted by encoded key bytes (RFC 8949 section 4.2).
+canonical = cborx.dumps({"b": 1, "a": 2}, canonical=True)
+
+# Strict canonical validation on decode, duplicate-key policy, depth
+# and indefinite-length controls.
+cborx.loads(data, canonical=True, duplicate_keys="error", max_depth=100)
+
+# Unhandled semantic tags round-trip as CBORTag. A tag_hook overrides
+# all built-in tag handling.
+cborx.loads(b"\xd8\x2a\x01", tag_hook=lambda decoder, tag: (tag.tag, tag.value))
+assert cborx.loads(cborx.dumps(cborx.CBORTag(42, "x"))) == cborx.CBORTag(42, "x")
+
+# A default callback handles otherwise unencodable objects, like cbor2.
+cborx.dumps(object(), default=lambda encoder, obj: {"type": type(obj).__name__})
+
+# Simple values and the undefined sentinel.
+assert cborx.loads(b"\xf7") is cborx.undefined
+assert cborx.loads(b"\xf0") == cborx.CBORSimpleValue(16)
+```
+
+Built-in semantic tags: 0 (ISO 8601 datetime), 1 (epoch datetime),
+2/3 (bignum integers beyond the 64-bit range), 32 (URI, decoded to a
+plain str since Python has no URI scalar), 1004 (calendar date) and
+55799 (self-described CBOR, passed through). All other tags decode to
+CBORTag. See RFC 8949: https://www.rfc-editor.org/rfc/rfc8949
+
+## Development
+
+```sh
+uv sync --group dev
+make check
+```
+
+License: 0BSD. Quad4 Software, https://quad4.io

cborx-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+cborx/__init__.py,sha256=tJr2AeOht5RywKWAkdyP25I_ImwmvnVmWXwsX4oB6Fg,705
+cborx/_util.py,sha256=rsBuDidZNfyrdNO_eGoBwOutIWzigQN_lOooBKAy2hM,767
+cborx/decoder.py,sha256=ZcLyWoR5dopbb1ybLhPI-dbufww5xU7W8RCg45EOBKs,17178
+cborx/encoder.py,sha256=LlwZXM7RI0m9CbXxgK1pjubuj__OpgK0Ue-Ij1DY_hk,11806
+cborx/exceptions.py,sha256=DogJ_-DUPAiMuaduFAHiCw7VMr6MOaODfnLAYn6c_Qw,334
+cborx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cborx/types.py,sha256=yeX-WPZpZcU1RPpbGOj-ws-fcYLVIz80u0IhqzmX5pE,1419
+cborx-0.1.1.dist-info/METADATA,sha256=GStVn2V_xuDfLMEgVlPw9Y-4NKvPY3vXcerw_PVK18Y,3390
+cborx-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+cborx-0.1.1.dist-info/licenses/LICENSE,sha256=3Hnwsz5EXuTC9iTlGjzA171dKQtIVsgjFoF5DEMRl48,633
+cborx-0.1.1.dist-info/RECORD,,

cborx-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

cborx-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,12 @@
+Copyright (c) 2026 Quad4
+
+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.