Argenta/docs/root/api/command/validation_status.rst

.. _root_api_command_validation_status:

ValidationStatus
================

Enum ``ValidationStatus`` представляет собой перечисление, определяющее состояние валидации значений флагов в приложении ``Argenta``. Его основная задача — предоставить стандартизированные константы для отображения результата проверки введённых пользователем флагов и их значений. ``ValidationStatus`` используется в атрибуте ``status`` класса ``InputFlag`` для информирования о том, прошёл ли флаг валидацию успешно.

``ValidationStatus`` наследуется от стандартного класса ``Enum`` и содержит три основных значения: ``VALID`` для корректных флагов, ``INVALID`` для некорректных флагов и ``UNDEFINED`` для незарегистрированных флагов.

.. note::

   Статус валидации устанавливается автоматически при создании экземпляра ``InputFlag`` на основе проверки через соответствующий ``Flag``.

.. seealso::

   Документация по :ref:`InputFlag <root_api_command_input_flag>` — сущности входного флага, использующей ``ValidationStatus``
   
   Документация по :ref:`Flag <root_api_command_flag>` — сущности флага с методом валидации
   
   Документация по :ref:`PossibleValues <root_api_command_possible_values>` — типам допустимых значений флагов

-----

Значения enum
-------------

VALID
~~~~~

.. code-block:: python
   :linenos:

   ValidationStatus.VALID = 'VALID'

Указывает, что флаг и его значение **прошли** валидацию успешно.

Флаги с этим статусом полностью соответствуют правилам, заданным в параметре ``possible_values`` соответствующего ``Flag``. Такие флаги могут быть безопасно использованы в логике приложения без дополнительных проверок.

**Условия получения статуса** ``VALID``:

* Флаг с ``PossibleValues.NEITHER`` передан без значения
* Флаг с ``PossibleValues.ALL`` передан с любым значением или без него
* Флаг со списком значений передан с одним из допустимых значений
* Флаг с регулярным выражением передан со значением, соответствующим паттерну

**Пример использования:**

.. literalinclude:: ../../../code_snippets/validation_status_valid_snippet1.py
   :linenos:
   :language: python

-----

INVALID
~~~~~~~

.. code-block:: python
   :linenos:

   ValidationStatus.INVALID = 'INVALID'

Указывает, что флаг или его значение **не прошли** валидацию.

Флаги с этим статусом нарушают правила, установленные в ``possible_values`` соответствующего ``Flag``. Такие флаги должны быть обработаны как ошибочные, и их использование может привести к некорректной работе приложения.

**Условия получения статуса** ``INVALID``:

* Флаг с ``PossibleValues.NEITHER`` передан со значением
* Флаг со списком значений передан с недопустимым значением
* Флаг с регулярным выражением передан со значением, не соответствующим паттерну
* Флаг требует значение, но передан без него (для определённых типов валидации)

**Пример использования:**

.. literalinclude:: ../../../code_snippets/validation_status_invalid_snippet2.py
   :linenos:
   :language: python

-----

UNDEFINED
~~~~~~~~~

.. code-block:: python
   :linenos:

   ValidationStatus.UNDEFINED = 'UNDEFINED'

Указывает, что флаг был введён, но не зарегистрирован.

**Условия получения статуса** ``UNDEFINED``:

* Флаг был введён с любым значением, но не зарегистрирован

-----


Практические примеры
--------------------

Комплексный пример валидации
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Пример демонстрирует использование всех статусов в реальном сценарии:

.. literalinclude:: ../../../code_snippets/validation_status_comprehensive_snippet6.py
   :linenos:
   :language: python