Concepts

Short explanations of terms used in the examples. You can begin with Your first model without reading this entire page.

binary format

Binary format: rules for writing data as bytes, including which field comes first, how much space a number takes, and where a string ends. For example: one byte for temperature, followed by one byte for battery level.

field

Field: one named value in a model, such as name: str. The value is written to the message; the name name stays in the Python class.

wire format

Wire format: the exact bytes exchanged by programs. The number 42 might appear as 2a or 00 00 00 2a: the value is the same, but the formats differ. The same rules apply to files.

header

Header: metadata before the message fields. For example, a message identifier and the number of bytes after the header. The default bytespec header takes 14 bytes; you can customize or remove it.

payload

Payload: the field bytes after the header, including their length prefixes. With default settings, name="Anna" takes four bytes for the length and four for the text. PayloadLength excludes the header itself.

framing

Framing: how to tell where one packet ends and the next begins. For example, the header can store the payload length. This is especially useful when a buffer contains several messages.

byte order

Byte order determines how a number spanning multiple bytes is written. The number 258 in two bytes is 01 02 in big-endian and 02 01 in little-endian. The value stays the same; the sender and receiver must agree on the order.

length prefix

Length prefix: a number before some data that gives its size in bytes. In 04 41 6e 6e 61, the first byte means: read four more bytes (Anna). prefix_length=1 sets the size of the length number itself, not the text.

offset

Offset: a position in a buffer, counted from zero like a Python index. decode_from(buffer, 7) starts at the eighth byte. The returned offset indicates where to begin reading the next message.

flags

bitmask

Flags, or a bitmask, are a number whose individual bits indicate which optional fields are present. flag=0 assigns the rightmost bit to a field: 00000001 means present, 00000000 means absent. bytespec computes the mask from the values; you do not need to supply it manually.

codec

Codec: a rule for converting one value to bytes and back. For example, UInt32Codec writes an integer as four bytes. bytespec usually selects a codec from the annotation; a custom codec handles a special format.

varint

Varint: a variable-length integer, where small numbers take fewer bytes. For example, VarUInt writes 1 as 01 and 300 as ac 02. VarInt also supports negative numbers and uses a different representation; it is the default for a plain Python int.

Try these concepts with data: Recipes. Exact sizes and decoding rules: Binary / wire format.