Основные понятия

Короткие объяснения терминов, которые встречаются в примерах. Начать работу можно с Первая модель, не читая эту страницу целиком.

binary format

Бинарный формат — правила записи данных в байты: какое поле идёт первым, сколько места занимает число, где заканчивается строка. Например: один байт температуры, затем один байт заряда батареи.

field

Поле — одно именованное значение модели, например name: str. Значение записывается в сообщение; имя name остаётся в Python-классе.

wire format

Формат передачи — точные байты, которыми обмениваются программы. Число 42 может выглядеть как 2a или 00 00 00 2a: значение одно, но форматы разные. Те же правила применимы к файлам.

header

Заголовок — служебные данные перед полями сообщения. Например, идентификатор сообщения и число байтов после заголовка. Стандартный заголовок bytespec занимает 14 байт; его можно настроить или убрать.

payload

Содержимое сообщения — байты полей после заголовка, включая их префиксы длины. У name="Anna" со стандартной настройкой это четыре байта длины и четыре байта текста. PayloadLength не включает сам заголовок.

framing

Выделение границ сообщений — способ понять, где заканчивается один пакет и начинается следующий. Например, заголовок хранит длину содержимого. Это особенно полезно, когда в одном буфере лежат несколько сообщений.

byte order

Порядок байтов определяет запись числа, занимающего несколько байтов. Число 258 в двух байтах: 01 02 при big-endian и 02 01 при little-endian. Само значение не меняется; отправитель и получатель должны выбрать один порядок.

length prefix

Префикс длины — число перед данными, указывающее их размер в байтах. В 04 41 6e 6e 61 первый байт означает: прочитать ещё четыре байта (Anna). prefix_length=1 задаёт размер самого числа длины, а не текста.

offset

Смещение — позиция в буфере, отсчитываемая от нуля, как индекс в Python. decode_from(buffer, 7) начинает чтение с восьмого байта. Возвращённое смещение указывает, где начинать чтение следующего сообщения.

flags

bitmask

Флаги, или битовая маска, — число, в котором отдельные биты обозначают наличие необязательных полей. flag=0 выделяет полю крайний правый бит: 00000001 — поле есть, 00000000 — его нет. bytespec вычисляет маску по значениям; вручную передавать её не нужно.

codec

Кодек — правило преобразования одного значения в байты и обратно. Например, UInt32Codec записывает целое число четырьмя байтами. Обычно bytespec выбирает кодек по аннотации; собственный нужен для особого формата.

varint

Целое переменной длины: небольшие числа занимают меньше байтов. Например, VarUInt записывает 1 как 01, а 300 как ac 02. VarInt также поддерживает отрицательные числа и использует другую запись; именно он выбран для обычного Python int.

Попробовать эти понятия на данных: Практические задачи. Точные размеры и правила чтения: Binary / wire format.