Типы и спецификации¶

Числовые аннотации и спецификации импортируются из bytespec.types; datetime и UUID — из стандартной библиотеки. Значения остаются обычными Python-объектами. Практические примеры: Числа и другие типы.

Поддерживаемые аннотации¶

Таблица описывает автоматический выбор представления. Собственный тип поддерживается через явный codec или configure_codecs().

Python-тип / аннотация	Представление	Настройки
`UInt8/16/32/64`, `Int8/16/32/64`	Фиксированное целое, одноимённый `…Codec`	Порядок байтов модели
`int`	`VarIntCodec`: ZigZag + varint, диапазон Int64	Для другого формата выберите числовую аннотацию
`Float32`, `Float64`	IEEE 754 binary32/binary64	Порядок байтов модели
`VarUInt`, `VarInt`	Unsigned varint / ZigZag + varint, 1–10 байт	Независимы от порядка байтов
`bool`	`BoolCodec`: один байт 0/1	Нет
`str`	`StrCodec`: длина в байтах и текст	`encoding`, `prefix_length`
`bytes`	`BytesCodec`: длина и байты	`prefix_length`
`datetime.datetime`	`DatetimeCodec`: строка `isoformat()`	`encoding`, `prefix_length`
`uuid.UUID`	`UUIDCodec`: ровно 16 байт `UUID.bytes`	Без префикса, не зависит от порядка байтов
Подкласс `str` и `Enum`	`EnumCodec` + `StrCodec`: строковое `.value`	`encoding`, `prefix_length`
`IntEnum` / подкласс `int` и `Enum`	`EnumCodec` + `VarIntCodec`: числовое `.value`	Для другого представления — явный `EnumCodec`
`list[T]`	`ListCodec`: длина в байтах и элементы	Префикс списка; тип `T` настраивается отдельно
Подкласс `ProtoModel`	`ModelCodec`: свой header без Constructor	Настройки вложенного класса
`T \| None` / `Optional[T]`	Значение `T` при установленном бите присутствия	Обязательный `field(flag=...)`
`Annotated[T, ...]`	Представление `T` с одной поддерживаемой спецификацией	Спецификации ниже

По умолчанию текст использует UTF-8, префиксы переменной длины занимают 4 байта. StrEnum подходит на версиях Python, где он доступен. Обычный Enum без наследования от str или int требует явного codec.

Нет встроенного выбора для голых float, list, datetime.date, datetime.time, а также dict, tuple, set, Any, Literal и union нескольких ненулевых типов. list[T | None] не поддерживается.

Целые¶

bytespec.types.UInt8¶: псевдоним для Annotated[int, IntegerSpec(bits=8, signed=False)]

bytespec.types.UInt16¶: псевдоним для Annotated[int, IntegerSpec(bits=16, signed=False)]

bytespec.types.UInt32¶: псевдоним для Annotated[int, IntegerSpec(bits=32, signed=False)]

bytespec.types.UInt64¶: псевдоним для Annotated[int, IntegerSpec(bits=64, signed=False)]

bytespec.types.Int8¶: псевдоним для Annotated[int, IntegerSpec(bits=8, signed=True)]

bytespec.types.Int16¶: псевдоним для Annotated[int, IntegerSpec(bits=16, signed=True)]

bytespec.types.Int32¶: псевдоним для Annotated[int, IntegerSpec(bits=32, signed=True)]

bytespec.types.Int64¶: псевдоним для Annotated[int, IntegerSpec(bits=64, signed=True)]

Float и varint¶

bytespec.types.Float32¶: псевдоним для Annotated[float, FloatSpec(bits=32)]

bytespec.types.Float64¶: псевдоним для Annotated[float, FloatSpec(bits=64)]

bytespec.types.VarUInt¶: псевдоним для Annotated[int, VarIntSpec(signed=False)]

bytespec.types.VarInt¶: псевдоним для Annotated[int, VarIntSpec(signed=True)]

VarUInt ограничен диапазоном 0 .. 2**64 - 1; VarInt — -2**63 .. 2**63 - 1. Каноническое представление описано в Binary / wire format. Float32 может округлять значение; отдельного запрета на NaN и бесконечности нет. BoolCodec.encode() использует истинность значения, а decoder принимает строго байты 0/1.

Спецификации Annotated¶

class bytespec.types.IntegerSpec(bits: Literal[8, 16, 32, 64], signed: bool)[исходный код]¶

Выбрать фиксированное целое в Annotated[int, ...].

Параметры:

bits – Число бит: 8, 16, 32 или 64.
signed – Разрешить отрицательные значения (знаковое представление).

Фиксированное целое: bits равен 8, 16, 32 или 64, signed задаёт знак.

class bytespec.types.FloatSpec(bits: Literal[32, 64])[исходный код]¶

Выбрать число IEEE 754 в Annotated[float, ...].

Параметры:: bits – Число бит: 32 или 64. Float32 округляет Python float до своего представления.

Число IEEE 754: bits равен 32 или 64.

class bytespec.types.VarIntSpec(signed: bool)[исходный код]¶

Выбрать varint в Annotated[int, ...].

Параметры:: signed – При True использовать ZigZag и диапазон Int64; при False — unsigned varint и диапазон UInt64.

Varint; при signed=True сначала используется ZigZag.

class bytespec.types.CodecSpec(prefix_length: bytespec.models.PrefixLength | None = None, encoding: str | None = None, codec: ICodec[Any] | None = None)[исходный код]¶

Задать переиспользуемые настройки поля через Annotated.

Параметры:

prefix_length – Размер префикса: 1, 2, 4, 8 байт или VarUInt. None не меняет настройку поля; VarInt не поддерживается.
encoding – Кодировка текста. Непустое значение заменяет кодировку поля.
codec – Готовый экземпляр codec вместо автоматического выбора.

Примечание

В одном Annotated допускается одна поддерживаемая спецификация. Явный field(codec=...) имеет приоритет перед CodecSpec.

Настройки для переиспользования через Annotated. codec принимает экземпляр ICodec. Приоритет настроек: Строки, длины и настройки полей.

bytespec.types.Spec = bytespec.types.spec.IntegerSpec | bytespec.types.spec.FloatSpec | bytespec.types.spec.VarIntSpec | bytespec.types.spec.CodecSpec¶: Объединение четырёх поддерживаемых видов спецификаций.

Совместное использование настроек¶

В одном Annotated допускается только одна распознаваемая спецификация; посторонние metadata игнорируются. Числовые аннотации уже содержат spec: например, UInt16 — Annotated[int, IntegerSpec(16, signed=False)]. Добавлять к нему второй spec через внешний Annotated нельзя.

CodecSpec перезаписывает prefix_length поля, если он не None, и encoding, если она непустая; переданный в spec codec выбирается явно. field(codec=...) применяется раньше metadata и имеет приоритет. Остальные параметры field() не перенастраивают готовый экземпляр codec.

Произвольный struct-формат поля задавайте через свой codec, см. Codecs: свой формат и свои типы. Замена codec полностью определяет результат decode: аннотация логического типа не преобразует его автоматически обратно.

Вспомогательная аннотация¶

bytespec.types.UIntUnion¶: Union беззнаковых числовых аннотаций для типизации Python-кода. Сам по себе не является допустимой аннотацией сериализуемого поля: автоматический выбор между несколькими числовыми форматами не поддержан. псевдоним для Annotated[int, IntegerSpec(bits=16, signed=False)] | Annotated[int, IntegerSpec(bits=32, signed=False)] | Annotated[int, IntegerSpec(bits=64, signed=False)] | Annotated[int, IntegerSpec(bits=8, signed=False)]