Skip to content

livery.strongroom.cbor._codec

livery.strongroom.cbor._codec

The deterministic encoder and the strict decoder.

RFC 8949's core deterministic encoding requirements, over the subset the spec page names: integers to 64 bits, byte strings, text strings, arrays, maps with text-string keys, true, false, null, and floats under the IETF deterministic rules. Every value has one encoding, and the decoder refuses every other encoding of it, because a lenient decoder gives one value two byte sequences and so gives one object two names.

Reach for livery.strongroom.cbor.encode and livery.strongroom.cbor.decode; a refusal raises livery.strongroom.cbor.CodecError with the rule in its message.

Classes:

Name Description
CodecError

A value with no deterministic encoding, or bytes that are not one.

Functions:

Name Description
encode

Encode value deterministically.

decode

Decode data, refusing anything that is not a deterministic encoding.

Attributes:

Name Type Description
Value TypeAlias

A value the codec encodes: the subset, nested the same way.

MAX_DEPTH

Containers may nest this deep and no deeper.

Value module-attribute

Value: TypeAlias = 'bool | int | float | bytes | str | list[Any] | dict[str, Any] | None'

A value the codec encodes: the subset, nested the same way.

MAX_DEPTH module-attribute

MAX_DEPTH = 512

Containers may nest this deep and no deeper.

CodecError

Bases: ValueError

A value with no deterministic encoding, or bytes that are not one.

The message names the rule: the phrase a vector's refusal quotes.

encode

encode(value: Value) -> bytes

Encode value deterministically.

Parameters:

Name Type Description Default
value Value

an integer within 64 bits, a float, bytes, text, a list, a dict with text keys, a boolean, or None, nested at most livery.strongroom.cbor.MAX_DEPTH deep.

required

Returns:

Type Description
bytes

The one encoding of value.

Raises:

Type Description
CodecError

when value is outside the subset: an integer past 64 bits, a map key that is not text, text that is not valid UTF-8, a type the subset lacks, or nesting past the bound.

Source code in packages/strongroom/src/livery/strongroom/cbor/_codec.py
def encode(value: Value) -> bytes:
    """Encode *value* deterministically.

    Args:
        value: an integer within 64 bits, a float, bytes, text, a list,
            a dict with text keys, a boolean, or None, nested at most
            [livery.strongroom.cbor.MAX_DEPTH][] deep.

    Returns:
        The one encoding of *value*.

    Raises:
        CodecError: when *value* is outside the subset: an integer past
            64 bits, a map key that is not text, text that is not valid
            UTF-8, a type the subset lacks, or nesting past the bound.
    """
    out = bytearray()
    _encode_into(value, out, 0)
    return bytes(out)

decode

decode(data: bytes) -> Value

Decode data, refusing anything that is not a deterministic encoding.

Parameters:

Name Type Description Default
data bytes

exactly one encoded item.

required

Returns:

Type Description
Value

The value.

Raises:

Type Description
CodecError

when the bytes are not the deterministic encoding of a value in the subset: a non-shortest argument, an indefinite length, a tag, a simple value the subset lacks, a float not in its shortest form or a NaN other than the canonical one, a map key that is not text, keys out of order or repeated, text that is not valid UTF-8, nesting past the bound, truncated input, or bytes after the item.

Source code in packages/strongroom/src/livery/strongroom/cbor/_codec.py
def decode(data: bytes) -> Value:
    """Decode *data*, refusing anything that is not a deterministic encoding.

    Args:
        data: exactly one encoded item.

    Returns:
        The value.

    Raises:
        CodecError: when the bytes are not the deterministic encoding of
            a value in the subset: a non-shortest argument, an indefinite
            length, a tag, a simple value the subset lacks, a float not in
            its shortest form or a NaN other than the canonical one, a map
            key that is not text, keys out of order or repeated, text that
            is not valid UTF-8, nesting past the bound, truncated input,
            or bytes after the item.
    """
    decoder = _Decoder(data)
    value = decoder.item()
    if decoder.position != len(data):
        raise CodecError(f"trailing bytes after the item at offset {decoder.position}")
    return value