Модель и поля¶

class bytespec.ProtoModel(**kwargs: Any)[исходный код]¶

Базовый класс модели для бинарной сериализации.

Объявите поля аннотациями и создайте экземпляр с именованными аргументами. encode() записывает сообщение, decode() восстанавливает экземпляр того же класса. Для настроек отдельного поля используйте field().

Параметры:: **kwargs – Значения полей. Пропущенные поля получают default, результат factory или None для optional; остальные поля обязательны.

Примечание

Аннотации задают бинарный формат, но явно переданные значения не проходят полную проверку типов в конструкторе. Поля изменяемы. Схема проверяется при объявлении подкласса. Если подкласс объявляет свои поля, сериализуемые поля родителя с ними не объединяются.

Базовый класс декларативной модели. Конструктор принимает только именованные значения объявленных полей. Первый пример: Первая модель. Работа с файлами и буферами: Файлы и несколько сообщений.

encode(include_constructor: bool = True) → bytes[исходный код]¶

Записать текущее состояние модели в одно бинарное сообщение.

Параметры:: include_constructor – Записывать элементы Constructor из __header__. False пропускает их целиком, сохраняя остальные элементы.
Результат:: Элементы __header__ в заданном порядке, затем поля. Optional-поля со значением None не записываются.
Исключение:: EncodeError – Обязательное значение отсутствует или значение поля нельзя записать в выбранном представлении.

Примечание

Ошибки реализации собственного codec не оборачиваются автоматически. __validate__ повторно не вызывается.

Возвращает заголовок и payload модели как bytes.

classmethod decode(buffer: bytes) → Self[исходный код]¶

Восстановить модель из буфера с ровно одним сообщением.

Параметры:: buffer – Полное бинарное сообщение, соответствующее классу модели.
Результат:: Новый экземпляр класса с прочитанными значениями полей.
Исключение:: DecodeError – Неполные/некорректные данные, неверный constructor или дополнительные байты после конца сообщения.

Примечание

Для нескольких сообщений в одном буфере используйте decode_from. Неизвестный остаток внутри объявленного payload пропускается.

Читает ровно одно сообщение; байты после его конца запрещены.

classmethod decode_from(buffer: bytes, offset: int, expect_constructor: bool = True) → tuple[Self, int][исходный код]¶

Прочитать одно сообщение с заданной позиции в буфере.

Параметры:

buffer – Буфер, содержащий полное сообщение.
offset – Неотрицательная абсолютная позиция начала сообщения.
expect_constructor – Читать и проверять элементы Constructor. False пропускает их целиком; таких байтов во входе быть не должно.

Результат:

Пара из нового экземпляра и абсолютной позиции после сообщения. Её можно передать следующему вызову для чтения соседнего сообщения.

Исключение:

DecodeError – Неполные или некорректные данные, неверный constructor либо выход поля за границы объявленного payload.
ValueError – Отрицательный offset.

Примечание

Остаток внутри объявленного payload и неизвестные биты flags пропускаются без сохранения. Байты после сообщения остаются вызывающему коду. Сетевые фрагменты между вызовами не накапливаются. Без PayloadLength конец определяется известными полями, отдельной границы body нет. Создание экземпляра запускает его собственный __validate__; исключения validator передаются без обёртки.

Читает сообщение с неотрицательного смещения. Возвращает экземпляр и абсолютную позицию конца сообщения в переданном буфере.

classmethod configure_codecs() → dict[type, CodecFactory]¶

Задать дополнительные правила выбора codec для типов полей.

Переопределите этот classmethod в модели. Правила применяются при объявлении класса, дополняют унаследованные и заменяют совпадающие ключи.

Результат:: Отображение Python-типов на фабрики codecs. Фабрика получает аннотацию и FieldInfo и возвращает готовый экземпляр codec. По умолчанию дополнительных правил нет.

Возвращает отображение типов на фабрики codecs. Вызов при создании подкласса дополняет или заменяет унаследованные правила. Пример: Codecs: свой формат и свои типы.

__validate__() → None[исходный код]¶

Проверить связи между уже присвоенными значениями полей.

Переопределите метод в конкретной модели и поднимите исключение при нарушении инварианта. Возвращаемое значение игнорируется. Метод автоматически вызывается в конце __init__, в том числе при decode, только если определён в самом конкретном классе. Для проверки родителя вызовите super().__validate__() из дочернего метода.

Присваивания атрибутов и encode повторно метод не вызывают. Пользовательские исключения передаются без обёртки.

Вызывается после присвоения полей только при определении метода в самом конкретном классе. Mutation и encode повторно его не вызывают. Примеры и правила ошибок — Проверка значений модели.

__constructor__: int = 1¶: Число для элемента Constructor; не выбирает класс автоматически.

__byte_order__: bytespec.ByteOrder = ByteOrder.BIG¶: Порядок байтов фиксированных чисел, prefixes и header.

__header__¶: Tuple элементов framing. По умолчанию (Constructor(2), Flags(8), PayloadLength(4)). Пустой tuple убирает framing. Элементы — Элементы header; руководство — Header и framing.

Настройки задаются при объявлении класса. Служебную собранную схему не следует редактировать вручную.

bytespec.field(index: int | None = None, *, flag: int | None = None, default: Any = MISSING, default_factory: Callable[[], Any] | _MissingType = MISSING, prefix_length: Literal[1, 2, 4, 8] | Annotated[int, VarIntSpec(signed=False)] | None = None, encoding: str = 'utf-8', codec: ICodec[Any] | None = None) → Any[исходный код]¶

Настроить сериализуемое поле модели.

Параметры:

index – Позиция поля, начиная с нуля. Если не задана, выбирается наименьший свободный индекс в порядке объявления полей.
flag – Номер бита присутствия (0–63). Обязателен для T | None; должен быть уникальным и помещаться в размер flags модели.
default – Значение при пропуске аргумента конструктора. Явное None отличается от отсутствия default и допустимо только для optional.
default_factory – Функция без аргументов, создающая значение при пропуске поля. Нельзя задавать вместе с default.
prefix_length – Размер префикса длины: 1, 2, 4, 8 байт или VarUInt. None оставляет настройку codec по умолчанию. Для списка настраивает сам список, а не его элементы.
encoding – Кодировка текстовых значений. По умолчанию UTF-8.
codec – Готовый экземпляр codec, заменяющий автоматический выбор. Остальные настройки поля не перенастраивают этот экземпляр.

Результат:

Описание поля для использования в теле класса модели.

Примечание

Совместимость настроек проверяется при объявлении модели. Неподдерживаемые или противоречивые настройки вызывают SchemaError.

Описывает поле; без index выбирается следующий свободный индекс. flag — номер бита присутствия optional. Default и factory применяются при пропуске аргумента и взаимно исключаются. prefix_length и encoding настраивают автоматически выбранный codec, codec задаёт готовый экземпляр явно. См. Поля и значения по умолчанию и Необязательные поля.

class bytespec.ByteOrder(*values)[исходный код]¶

Порядок байтов фиксированных чисел и префиксов модели.

BIG — big-endian (>), LITTLE — little-endian (<). На varint, содержимое bytes и представление UUID настройка не влияет.

Порядок байтов фиксированных чисел и префиксов.

BIG = '>'¶

LITTLE = '<'¶

Правила объявления полей¶

Схема собирается при объявлении подкласса. Полем становится аннотированный атрибут без присвоенного значения или с field(). Обычное присваивание значения пропускает атрибут при сборке схемы. Неаннотированные атрибуты не сериализуются. Голая аннотация ClassVar автоматически не исключается; для настроек класса используйте обычное присваивание.

Индексы — уникальные неотрицательные целые числа от 0 до N - 1, где N — число полей. Если индекс не задан, выбирается наименьший ещё свободный при обходе объявления. Поздние явные индексы заранее не резервируются. Поэтому смешивание способов может привести к дубликату. Обычно достаточно порядка объявления; при явном задании проще указать все индексы. Индексы и имена полей в байты не записываются.

Defaults и создание экземпляра¶

Пропущенное значение определяется в порядке: default, вызов default_factory, None для optional. Иначе возникает TypeError о пропущенном обязательном поле. Неизвестные именованные аргументы также отклоняются. default и default_factory взаимно исключаются; одновременное объявление вызывает SchemaError.

Default проверяется при создании класса: None допустим только для optional, другое значение должно соответствовать типу. Фабрика без аргументов вызывается при создании экземпляра; неподходящий тип результата вызывает TypeError. Списки проверяются как контейнеры, без проверки каждого элемента. Диапазоны чисел и размеры значений при этой проверке не проверяются.

Явно переданные аргументы присваиваются как есть, без полной runtime-валидации и преобразования типов. Объект изменяем; encode() читает текущее состояние. Модели одного конкретного класса сравниваются по сериализуемым полям; repr показывает имя класса и эти поля. Объекты разных классов не равны, даже если поля совпадают. Автоматического преобразования в словарь нет. После присвоения всех полей вызывается собственный __validate__ класса; полный жизненный цикл описан в Проверка значений модели.

Аннотации и наследование¶

Аннотации разрешаются сразу; имена используемых типов должны быть доступны. Отдельного шага для разрешения ссылок на ещё не объявленные классы нет. Проще определять модели на уровне модуля, вложенные классы — раньше внешних.

Подкласс со своими полями собирает схему из собственных аннотаций: сериализуемые поля родителя с ними не объединяются. Подкласс без новых полей сохраняет унаследованные поля, но получает собственную схему с текущими настройками framing. Codecs, defaults и factories этих полей сохраняются; они не разрешаются заново. Самостоятельный класс без полей получает пустую схему и тоже поддерживает encode/decode. Правила custom headers и multiple inheritance — Наследование моделей. Для композиции используйте Списки и вложенные модели.