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

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

.. autoclass:: bytespec.models.FieldInfo

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

.. autodata:: bytespec.models.PrefixLength

   Поддержаны числа ``1``, ``2``, ``4``, ``8`` и аннотация ``VarUInt``.
   ``VarInt`` не поддерживается. ``None`` в field оставляет default codec.

.. autodata:: bytespec.models.UIntEncoding

   Те же беззнаковые представления для Constructor, PayloadLength и Flags.
   Числа означают ширину в байтах, VarUInt — переменное представление.

.. autodata:: bytespec.models.DefaultFactory

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

.. autoclass:: bytespec.resolvers.CodecFactory
   :members: __call__
   :undoc-members:

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

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

Выбор codec
-----------

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

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