Header elements

All three classes are imported from bytespec. Instances are supplied in the __header__ tuple when declaring a model. Practical guide: Headers and framing; inheritance: Model inheritance.

class bytespec.Constructor(encoding: Literal[1, 2, 4, 8] | Annotated[int, VarIntSpec(signed=False)])

Model identifier from constructor, validated during decoding.

Parameters:

encoding – Unsigned integer width in bytes (1, 2, 4, 8) or VarUInt.

Note

The int type is validated when building the schema; the value range is validated during encoding. Nested models skip this element.

Uses __constructor__ (1 by default). When this element is present, the value’s type is checked when building the model; its range is checked during encode. include_constructor=False in encode and expect_constructor=False in decode_from omit the element entirely; this does not mean reading without validating the value. Nested models use this same omission.

class bytespec.PayloadLength(encoding: Literal[1, 2, 4, 8] | Annotated[int, VarIntSpec(signed=False)])

The size of all encoded fields, excluding the entire header.

Parameters:

encoding – The unsigned integer width in bytes (1, 2, 4, 8), or VarUInt.

Note

When reading, bounds the field buffer by the declared length. The position of this element within the header does not change the meaning of the stored number.

The length of all fields after the complete header, excluding the entire header, regardless of the element’s position. Without it, decode_from returns the end of the known fields and does not establish a separate body boundary.

class bytespec.Flags(encoding: Literal[1, 2, 4, 8] | Annotated[int, VarIntSpec(signed=False)])

A bitmap indicating the presence of optional fields, computed from their values.

Parameters:

encoding – The unsigned integer width in bytes (1, 2, 4, 8), or VarUInt.

Note

A field is present if its value is not None. Bit numbers are set using field(flag=…) and are limited to 0–63; with a fixed width, all used bits are checked to ensure they fit.

A bitmap of present optional fields. Flags(1) holds bits 0–7; Flags(8) and Flags(VarUInt) hold bits 0–63. If optional fields exist, omitting this element raises SchemaError at class declaration, including in subclasses with inherited fields. See What is checked in 0.1.0.

The common encoding parameter accepts 1, 2, 4, 8 (bytes), or VarUInt from bytespec.types. Other encodings raise SchemaError. The model sets the byte order for fixed-width encodings.

These elements describe computed and validated metadata numbers. Use a nested model for custom header values; there is no need to add them through internal schema-building contexts.