Codecs

Имена на этой странице импортируются из bytespec.codecs. Codec принимает и возвращает отдельное значение; заголовок модели он добавляет только в случае ModelCodec. Примеры: Codecs: свой формат и свои типы.

Общий интерфейс

class bytespec.codecs.ICodec(*args: Any, **kwargs: Any)

Интерфейс записи и чтения одного значения типа T.

Экземпляр можно передать в field(codec=...). Наследование от ICodec необязательно: достаточно методов encode и decode с этим контрактом. Codec может переиспользоваться; позиция чтения передаётся через offset.

decode возвращает значение и абсолютное смещение после него. При прямом использовании оставшиеся байты проверяет вызывающий код. При реализации собственного codec передавайте ошибки данных через EncodeError и DecodeError.

encode(value: T, byte_order: ByteOrder, /) → bytes

Записать одно значение в выбранном представлении.

Параметры:

• value – Значение для записи.

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

Результат:

Бинарное представление значения.

Исключение:

EncodeError – Значение невозможно представить. Собственный codec должен сам использовать эту ошибку для ошибок данных.

decode(buffer: bytes, byte_order: ByteOrder, offset: int, /) → tuple[T, int]

Прочитать одно значение начиная с offset.

Параметры:

• buffer – Буфер с закодированным значением.

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

• offset – Неотрицательная абсолютная позиция начала значения.

Результат:

Значение и абсолютная позиция после него в том же буфере. Остальные байты не требуют полного потребления.

Исключение:

DecodeError – Недостаточно байтов или значение некорректно. Реализация должна сама проверять границы и содержимое.

Примечание

Codec элемента списка должен продвигать offset на положительное число байтов, оставаясь в границах переданного буфера.

Требования к реализации

decode() должен возвращать абсолютную позицию после значения в том же буфере, проверяя доступность нужных байтов. Экземпляр codec может переиспользоваться: храните позицию в аргументах и результате, а не в изменяемом внутреннем счётчике.

Для элемента списка обязательно продвижение на положительное число байтов в пределах переданного буфера. ListCodec повторяет чтение до конца своего содержимого и сам не проверяет увеличение смещения. Элементы нулевой длины, например FixedBytesCodec(0), не подходят: их количество невозможно восстановить из пустого содержимого.

Ошибки данных передавайте через EncodeError и DecodeError. Ошибки реализации вроде TypeError или ValueError не оборачиваются. Проверка протокола ICodec устанавливает наличие методов, но не корректность их сигнатур или реализации.

Фиксированные числа

У всех числовых codecs интерфейс encode/decode из ICodec. Используйте приведённые значения struct_format и length по умолчанию: их ручное изменение требует согласовать размер struct и шаг decoder. Конструктор проверяет синтаксис формата, но не согласованность этих параметров.

class bytespec.codecs.UInt8Codec(struct_format: str = 'B', length: int = 1)

Беззнаковое 8-битное целое: 0–255, один байт по умолчанию.

class bytespec.codecs.UInt16Codec(struct_format: str = 'H', length: int = 2)

Беззнаковое 16-битное целое: 0–65535, два байта по умолчанию.

class bytespec.codecs.UInt32Codec(struct_format: str = 'I', length: int = 4)

Беззнаковое 32-битное целое: 0 .. 2**32 - 1, четыре байта.

class bytespec.codecs.UInt64Codec(struct_format: str = 'Q', length: int = 8)

Беззнаковое 64-битное целое: 0 .. 2**64 - 1, восемь байт.

class bytespec.codecs.Int8Codec(struct_format: str = 'b', length: int = 1)

Знаковое 8-битное целое: -128–127, один байт по умолчанию.

class bytespec.codecs.Int16Codec(struct_format: str = 'h', length: int = 2)

Знаковое 16-битное целое: -32768–32767, два байта по умолчанию.

class bytespec.codecs.Int32Codec(struct_format: str = 'i', length: int = 4)

Знаковое 32-битное целое: -2**31 .. 2**31 - 1, четыре байта.

class bytespec.codecs.Int64Codec(struct_format: str = 'q', length: int = 8)

Знаковое 64-битное целое: -2**63 .. 2**63 - 1, восемь байт.

class bytespec.codecs.Float32Codec(struct_format: str = 'f', length: int = 4)

IEEE 754 binary32: четыре байта с округлением Python float.

class bytespec.codecs.Float64Codec(struct_format: str = 'd', length: int = 8)

IEEE 754 binary64: восемь байт в порядке байтов модели.

Varint и bool

class bytespec.codecs.VarUIntCodec(*args: Any, **kwargs: Any)

Канонический unsigned varint: 0 .. 2**64 - 1, от 1 до 10 байт.

Группы по 7 бит записываются начиная с младшей. Порядок байтов модели на представление не влияет.

Канонический unsigned varint, диапазон UInt64.

class bytespec.codecs.VarIntCodec(*args: Any, **kwargs: Any)

Знаковый varint: ZigZag + unsigned varint, диапазон Int64.

Занимает 1–10 байт независимо от порядка байтов модели.

ZigZag + unsigned varint, диапазон Int64.

class bytespec.codecs.BoolCodec(*args: Any, **kwargs: Any)

Логическое значение в одном байте: 0 или 1.

Записывает истинность значения как 0/1; принимает при чтении только 0/1.

Строки, bytes, дата и UUID

class bytespec.codecs.StrCodec(prefix_length: Literal[1, 2, 4, 8] | Annotated[int, VarIntSpec(signed=False)] = 4, encoding: str = 'utf-8')

Текст с префиксом длины закодированных байтов, не символов.

Параметры:

• prefix_length – Размер префикса: 1, 2, 4, 8 байт или VarUInt. По умолчанию 4 байта.

• encoding – Кодировка Python, по умолчанию UTF-8.

Исключение:

SchemaError – Неподдерживаемый префикс или неизвестная кодировка.

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

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

Байты с префиксом их длины.

Параметры:

prefix_length – Размер префикса: 1, 2, 4, 8 байт или VarUInt. По умолчанию 4 байта. Сам префикс не входит в записанную длину.

Исключение:

SchemaError – Неподдерживаемый префикс, включая VarInt.

Префикс длины и содержимое bytes.

class bytespec.codecs.FixedBytesCodec(length: int)

Ровно length байт без префикса длины.

Параметры:

length – Неотрицательный фиксированный размер значения.

Исключение:

SchemaError – Отрицательная длина.

Ровно length байт без префикса. Длина должна быть неотрицательной.

class bytespec.codecs.DatetimeCodec(prefix_length: Literal[1, 2, 4, 8] | Annotated[int, VarIntSpec(signed=False)] = 4, encoding: str = 'utf-8')

Дата как строка ISO 8601 с префиксом длины.

Сохраняется смещение UTC из isoformat(), но не имя часовой зоны. Дата без tzinfo остаётся без него после чтения.

Параметры:

• prefix_length – Размер префикса: 1, 2, 4, 8 байт или VarUInt.

• encoding – Кодировка ISO-строки, по умолчанию UTF-8.

Исключение:

SchemaError – Неподдерживаемый префикс или неизвестная кодировка.

datetime.isoformat() через StrCodec; чтение через datetime.fromisoformat().

class bytespec.codecs.UUIDCodec

UUID как ровно 16 байт UUID.bytes, без префикса длины.

Порядок байтов модели не меняет это представление на bytes_le.

Ровно 16 байт UUID.bytes независимо от порядка байтов модели.

Составные значения

class bytespec.codecs.ListCodec(item_codec: ICodec[Any], prefix_length: Literal[1, 2, 4, 8] | Annotated[int, VarIntSpec(signed=False)] = 4)

Список с префиксом общего размера закодированных элементов в байтах.

Параметры:

• item_codec – Codec одного элемента. При чтении должен продвигать offset на положительное число байтов в пределах переданного буфера.

• prefix_length – Размер префикса: 1, 2, 4, 8 байт или VarUInt. По умолчанию 4 байта. Префикс не хранит количество элементов.

Исключение:

SchemaError – Неподдерживаемый префикс длины.

Префикс длины общего payload в байтах. item_codec должен читать один элемент за вызов и увеличивать смещение в границах буфера.

class bytespec.codecs.EnumCodec(enum_type: type[Enum], value_codec: ICodec[Any])

Enum, записываемый через codec его значения.

Параметры:

• enum_type – Класс enum для восстановления через enum_type(value).

• value_codec – Codec для .value, например StrCodec или UInt8Codec.

Кодирует .value через переданный value_codec, восстанавливает элемент вызовом enum_type(value).

class bytespec.codecs.ModelCodec(model_type: type[ProtoModel])

Вложенная модель со своим framing без Constructor и порядком байтов.

Параметры:

model_type – Конкретный класс для чтения через decode_from(). Автоматического выбора подкласса по constructor нет.

Вызывает encode(include_constructor=False) и model_type.decode_from(..., expect_constructor=False). Модель использует свой порядок байтов и header, пропуская Constructor. Другие элементы сохраняются. Тип вложенной модели определяется аннотацией.