Модель и поля
=============

.. autoclass:: bytespec.ProtoModel

   Базовый класс декларативной модели. Конструктор принимает только именованные
   значения объявленных полей. Первый пример: :doc:`../getting-started`.
   Работа с файлами и буферами: :doc:`../models`.

   .. automethod:: encode

      Возвращает заголовок и payload модели как ``bytes``.

   .. automethod:: decode

      Читает ровно одно сообщение; байты после его конца запрещены.

   .. automethod:: decode_from

      Читает сообщение с неотрицательного смещения. Возвращает экземпляр и
      абсолютную позицию конца сообщения в переданном буфере.

   .. automethod:: configure_codecs

      Возвращает отображение типов на фабрики codecs. Вызов при создании
      подкласса дополняет или заменяет унаследованные правила.
      Пример: :doc:`../codecs`.

   .. automethod:: __validate__

      Вызывается после присвоения полей только при определении метода в
      самом конкретном классе. Mutation и encode повторно его не вызывают.
      Примеры и правила ошибок — :doc:`../validation`.

   .. py:attribute:: __constructor__
      :type: int
      :value: 1

      Число для элемента Constructor; не выбирает класс автоматически.

   .. py:attribute:: __byte_order__
      :type: bytespec.ByteOrder
      :value: ByteOrder.BIG

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

   .. py:attribute:: __header__

      Tuple элементов framing. По умолчанию
      ``(Constructor(2), Flags(8), PayloadLength(4))``. Пустой tuple убирает
      framing. Элементы — :doc:`headers`; руководство — :doc:`../headers`.

   Настройки задаются при объявлении класса. Служебную собранную схему
   не следует редактировать вручную.

.. autofunction:: bytespec.field

   Описывает поле; без ``index`` выбирается следующий свободный индекс.
   ``flag`` — номер бита присутствия optional. Default и factory применяются
   при пропуске аргумента и взаимно исключаются. ``prefix_length`` и
   ``encoding`` настраивают автоматически выбранный codec, ``codec`` задаёт
   готовый экземпляр явно. См. :doc:`../fields` и :doc:`../optional-defaults`.

.. autoclass:: bytespec.ByteOrder
   :members: BIG, LITTLE
   :undoc-members:

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

.. _field-index-rules:

Правила объявления полей
------------------------

Схема собирается при объявлении подкласса. Полем становится аннотированный
атрибут без присвоенного значения или с ``field()``. Обычное присваивание
значения пропускает атрибут при сборке схемы. Неаннотированные атрибуты
не сериализуются. Голая аннотация ``ClassVar`` автоматически не исключается;
для настроек класса используйте обычное присваивание.

Индексы — уникальные неотрицательные целые числа от ``0`` до ``N - 1``,
где ``N`` — число полей. Если индекс не задан, выбирается наименьший ещё
свободный при обходе объявления. Поздние явные индексы заранее не резервируются.
Поэтому смешивание способов может привести к дубликату. Обычно достаточно
порядка объявления; при явном задании проще указать все индексы.
Индексы и имена полей в байты не записываются.

.. _default-rules:

Defaults и создание экземпляра
------------------------------

Пропущенное значение определяется в порядке: ``default``, вызов
``default_factory``, ``None`` для optional. Иначе возникает ``TypeError``
о пропущенном обязательном поле. Неизвестные именованные аргументы также
отклоняются. ``default`` и ``default_factory`` взаимно исключаются;
одновременное объявление вызывает ``SchemaError``.

Default проверяется при создании класса: ``None`` допустим только для
optional, другое значение должно соответствовать типу. Фабрика без аргументов
вызывается при создании экземпляра; неподходящий тип результата вызывает
``TypeError``. Списки проверяются как контейнеры, без проверки каждого элемента.
Диапазоны чисел и размеры значений при этой проверке не проверяются.

Явно переданные аргументы присваиваются как есть, без полной runtime-валидации
и преобразования типов. Объект изменяем; ``encode()`` читает текущее состояние.
Модели одного конкретного класса сравниваются по сериализуемым полям;
``repr`` показывает имя класса и эти поля. Объекты разных классов не равны,
даже если поля совпадают. Автоматического преобразования в словарь нет.
После присвоения всех полей вызывается собственный ``__validate__`` класса;
полный жизненный цикл описан в :doc:`../validation`.

Аннотации и наследование
------------------------

Аннотации разрешаются сразу; имена используемых типов должны быть доступны.
Отдельного шага для разрешения ссылок на ещё не объявленные классы нет.
Проще определять модели на уровне модуля, вложенные классы — раньше внешних.

Подкласс со своими полями собирает схему из собственных аннотаций:
сериализуемые поля родителя с ними **не объединяются**. Подкласс без новых
полей сохраняет унаследованные поля, но получает собственную схему с текущими
настройками framing. Codecs, defaults и factories этих полей сохраняются;
они не разрешаются заново. Самостоятельный класс без полей получает пустую
схему и тоже поддерживает encode/decode.
Правила custom headers и multiple inheritance — :doc:`../inheritance`.
Для композиции используйте :doc:`../collections`.