Типы для расширений

Эти типы полезны для аннотации собственных фабрик и настроек. Для обычной модели достаточно ProtoModel, field и аннотаций из bytespec.types. Resolver, его встроенные фабрики и собранные metadata полей не являются необходимыми точками подключения пользовательского кода.

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

Field settings passed to a user-defined codec factory.

In models, create them via field(). The factory may read prefix_length, encoding, and other settings to construct a codec.

Параметры:

  • index – Explicit field position, or None for automatic selection.

  • flag – Presence bit index for an optional field, or None.

  • default – Default value or the MISSING sentinel.

  • default_factory – Zero-argument factory or MISSING.

  • prefix_length – Length prefix size, or None to use the default.

  • encoding – Text encoding, UTF-8 by default.

  • codec – Explicitly assigned codec instance, or None.

Настройки поля, которые получает фабрика codec: индекс, flag, default, factory, префикс, кодировка и явный codec. В моделях создавайте их через field(), а не через конструктор FieldInfo.

bytespec.models.PrefixLength

Поддержаны числа 1, 2, 4, 8 и аннотация VarUInt. VarInt не поддерживается. None в field оставляет default codec. псевдоним для Literal[1, 2, 4, 8] | Annotated[int, VarIntSpec(signed=False)]

bytespec.models.UIntEncoding

Те же беззнаковые представления для Constructor, PayloadLength и Flags. Числа означают ширину в байтах, VarUInt — переменное представление. псевдоним для Literal[1, 2, 4, 8] | Annotated[int, VarIntSpec(signed=False)]

bytespec.models.DefaultFactory: TypeAlias = collections.abc.Callable[[], typing.Any] | bytespec.missing._MissingType

Функция без аргументов либо служебный маркер отсутствия фабрики.

class bytespec.resolvers.CodecFactory(*args, **kwargs)[исходный код]

Codec factory returned by rules configured via configure_codecs().

When selecting a codec for a scalar field, it is called with two arguments: the annotation and FieldInfo. It returns a ready-to-use codec instance. The third protocol argument is optional and is not passed in this path.

Тип callable из configure_codecs(). В текущем пути выбора скалярного codec передаются только annotation и field_info. Не требуйте третий аргумент: в протоколе он необязателен.

__call__(annotation: Any, field_info: FieldInfo, resolve: Callable[[Any, FieldInfo], ResolvedType] | None = None, /) → ICodec[Any][исходный код]

В сигнатуре фабрики может встречаться ResolveCallback — внутренний callback разрешения аннотации. Для регистрации собственного скалярного типа он не нужен.

Выбор codec

Сначала отделяется optional-часть аннотации. Далее выбирается явный field(codec=...), затем зарегистрированная фабрика для аннотации, затем обрабатывается Annotated. Если они не дали результата, применяются правила для вложенных моделей, enum и списков.

Фабрика скалярного типа вызывается при создании класса с аннотацией и FieldInfo. Она сама учитывает prefix_length и encoding, если они нужны её codec. Возвращённое configure_codecs() отображение дополняет унаследованные правила; совпадающий ключ заменяет фабрику для этого типа. После сборки схемы экземпляры codecs используются при записи и чтении.