Extension types

These types are useful for annotating custom factories and settings. Ordinary models only need ProtoModel, field, and annotations from bytespec.types. The resolver, its built-in factories, and the collected field metadata are not required integration points for user code.

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)[source]

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.

Parameters:

  • 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.

The field settings received by a codec factory: index, flag, default, factory, prefix, encoding, and explicit codec. In models, create them using field(), rather than the FieldInfo constructor.

bytespec.models.PrefixLength

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

bytespec.models.UIntEncoding

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

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

A function with no arguments, or an internal sentinel indicating no factory.

class bytespec.resolvers.CodecFactory(*args, **kwargs)[source]

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.

The callable type used in configure_codecs(). The current scalar codec selection path passes only annotation and field_info. Do not require a third argument: it is optional in the protocol.

__call__(annotation: Any, field_info: FieldInfo, resolve: Callable[[Any, FieldInfo], ResolvedType] | None = None, /) → ICodec[Any][source]

A factory signature may include ResolveCallback, an internal callback for resolving an annotation. It is not needed to register a custom scalar type.

Codec selection

The optional part of the annotation is separated first. Selection then checks for an explicit field(codec=...), followed by a registered factory for the annotation, then processes Annotated. If none of these produces a result, the rules for nested models, enums, and lists apply.

A scalar type factory is called at class creation with the annotation and FieldInfo. It handles prefix_length and encoding itself if its codec needs them. The mapping returned by configure_codecs() extends inherited rules; a matching key replaces the factory for that type. Once the schema has been built, the codec instances are used for writing and reading.