Исключения
==========

Все классы доступны напрямую из ``bytespec`` и в ``bytespec.errors``.
Практические примеры: :doc:`../errors`.

.. code-block:: text

   Exception
   └── BytespecError
       ├── SchemaError
       ├── EncodeError
       └── DecodeError

.. autoexception:: bytespec.BytespecError

   Общий базовый класс ошибок библиотеки, подкласс ``Exception``.

.. autoexception:: bytespec.SchemaError
   :show-inheritance:

   Неподдерживаемая или противоречивая схема/конфигурация codec.

   Возникает при неподдерживаемом типе/union, неразрешимой аннотации,
   неправильных индексах, flags, defaults, числовых specs или codec override.
   Проверяется уникальность flags и их размещение в выбранном размере,
   наличие flag у optional и отсутствие его у обязательного поля.
   Также отклоняются конфликтующие унаследованные custom headers без
   явного выбора в дочернем классе.

   Неподдерживаемые представления элементов header и префиксов, неверный тип constructor,
   отрицательная длина ``FixedBytesCodec``, неправильный ``struct``-формат
   и неизвестное имя кодировки также дают эту ошибку. Существующий Python
   codec, непригодный для текста (например, ``base64_codec``), отклоняется
   при записи или чтении строки, а не обязательно при объявлении модели.

.. autoexception:: bytespec.EncodeError
   :show-inheritance:

   Значение не может быть записано в заданный формат.

   Включает выход целого/varint за диапазон, переполнение float или длины
   префикса, ошибку кодирования текста и несовпадение длины ``FixedBytesCodec``.
   Сюда же относится constructor вне диапазона своего представления.
   Модель также отклоняет удалённый атрибут и ``None`` у обязательного поля.

.. autoexception:: bytespec.DecodeError
   :show-inheritance:

   Буфер не может быть прочитан по заданной схеме.

   Включает неполный заголовок, несовпадение constructor, объявленную длину
   за пределами буфера, обрезанное поле, выход за границу содержимого модели,
   неправильный bool, текст, ISO datetime, enum или varint.
   ``decode()`` отклоняет байты после сообщения. Неизвестный остаток внутри
   объявленной длины имеет другие правила — :ref:`unknown-wire-data`.

Отсутствие Flags при собственных или унаследованных optional-полях
вызывает ``SchemaError`` при объявлении класса. Новый header подкласса
проверяется и без объявления новых полей. Уникальность видов элементов
header отдельно не проверяется — :ref:`header-validation`.

Диагностика и обычные исключения Python
---------------------------------------

При обработке ``EncodeError``/``DecodeError`` поля модель добавляет имя класса
и поля в текст исключения. Сам объект ошибки не заменяется. Обёрнутые
``struct.error``, Unicode-ошибки и ошибки преобразования enum/datetime
сохраняются в ``__cause__``.

Смещения у декодеров обычно относятся к переданному буферу. Для элемента
списка это отдельный буфер содержимого списка, а не исходного сообщения.
Отдельных атрибутов ``field`` и ``offset`` у исключений нет.

Неправильные аргументы вызова модели, пропущенное обязательное поле
и неправильный тип результата factory дают ``TypeError``. Отрицательное
смещение даёт ``ValueError``. Явные аргументы модели не проходят полную
валидацию: значения совершенно другого типа и ошибки custom codec
могут дать стандартные исключения Python. Исключения validator передаются
без обёртки при создании и чтении модели — :doc:`../validation`.