sofab.types module

Wire-format constants, enums, the Field descriptor, and errors.

These mirror the shared SofaBuffers definitions used by corelib-c-cpp, corelib-rs, corelib-go, corelib-java and corelib-cs so the Python runtime produces byte-identical output.

sofab.types.API_VERSION = 1

SofaBuffers API version (mirrors C SOFAB_API_VERSION). Callers and the code generator use this to verify wire compatibility.

sofab.types.ID_MAX = 2147483647

Highest valid field ID (INT32_MAX).

sofab.types.UNSIGNED_MAX = 18446744073709551615

Largest unsigned wire value (UINT64_MAX).

sofab.types.SIGNED_MIN = -9223372036854775808

Signed wire value range (INT64_MIN .. INT64_MAX).

sofab.types.FIXLEN_MAX = 2147483647

Largest fixlen payload length in bytes (INT32_MAX).

sofab.types.ARRAY_MAX = 2147483647

Largest array element count (INT32_MAX).

sofab.types.MAX_DEPTH = 255

Maximum nested-sequence depth. An encoder must not open more than this many nested sequences; a decoder rejects a message nesting deeper.

sofab.types.MASK64 = 18446744073709551615

64-bit mask used by varint/zigzag wrap-around to match the C uint64_t.

class sofab.types.WireType(*values)[source]

Bases: IntEnum

The 3 low bits of a field header.

UNSIGNED = 0
SIGNED = 1
FIXLEN = 2
ARRAY_UNSIGNED = 3
ARRAY_SIGNED = 4
ARRAY_FIXLEN = 5
SEQUENCE_START = 6
SEQUENCE_END = 7
class sofab.types.FixlenSubtype(*values)[source]

Bases: IntEnum

The 3 low bits of a fixlen length header.

FP32 = 0
FP64 = 1
STRING = 2
BLOB = 3
class sofab.types.Field(id, type, size=0, count=0, subtype=None)[source]

Bases: object

Describes the field the decoder is currently positioned on.

Mirrors the C field callback’s (id, size, count) plus the wire type. size is the fixlen byte length (or the per-element size of a fixlen array); count is the element count of an array; subtype is set for fixlen and fixlen-array fields.

Parameters:
id: int
type: WireType
size: int = 0
count: int = 0
subtype: FixlenSubtype | None = None
exception sofab.types.SofaError[source]

Bases: Exception

Base class for all SofaBuffers errors.

exception sofab.types.SofaDecodeError[source]

Bases: SofaError

Malformed input — invalid regardless of what bytes might follow: an overflowing (>64-bit) varint, a bad fixlen subtype, an out-of-range id/count/length, invalid UTF-8, nesting past MAX_DEPTH, or a dangling sequence end (MESSAGE_SPEC §7 INVALID).

This is deliberately not raised for truncation — bytes that simply end inside a field are SofaIncompleteError (§7 INCOMPLETE), a distinct non-error outcome that is not a subclass of this class, so except SofaDecodeError does not catch it.

exception sofab.types.SofaIncompleteError[source]

Bases: SofaError

Truncated input — the bytes end inside a field (MESSAGE_SPEC §7 INCOMPLETE): an unterminated varint, a fixlen/array payload shorter than its declared length, an array element that runs off the end, or a nested sequence that is never closed.

This is not malformed: more bytes could complete the message, and the caller owns end-of-input. It is a sibling of SofaDecodeError under SofaError, not a subclass of it, so callers can tell “need more bytes” apart from “these bytes are garbage”.

exception sofab.types.SofaLimitError[source]

Bases: SofaError

A wire-declared array count or fixlen (string/blob) length exceeded a receiver-configured decode limit (Decoder(max_array_count=…, max_string_len=…, max_blob_len=…)).

This is a policy rejection, not wire malformation: the bytes are perfectly well-formed and would decode fine with the limit unset — the receiver simply declined to allocate for them. It is therefore a sibling of SofaDecodeError under SofaError, not a subclass of it, so except SofaDecodeError does not catch it and differential fuzzing does not see a limit rejection as a conformance divergence from another engine.

exception sofab.types.SofaRangeError[source]

Bases: SofaError

A value (or id/count) is outside the permitted range on encode.

exception sofab.types.SofaStateError[source]

Bases: SofaError

API misuse, e.g. reading a value of the wrong type for the current field, or ending a sequence that was never started.

exception sofab.types.SofaBufferError[source]

Bases: SofaError

A fixed encoder buffer filled up and no flush sink was provided.