.. _root_api_command_possible_values:


PossibleValues
==============

`PossibleValues` — это перечисление (`Enum`), которое определяет специальные режимы валидации для значений флагов. Его задача — предоставить стандартные константы для управления поведением флагов. `PossibleValues` используется в параметре `possible_values` класса `Flag`, чтобы указать, может ли флаг принимать значения и какие ограничения на них накладываются.

`PossibleValues` наследуется от `Enum` и содержит два основных значения: `NEITHER` (для флагов без значений) и `ALL` (для флагов, принимающих любые значения). Это перечисление используется вместе со списками строк и регулярными выражениями для создания гибкой системы валидации.

.. note::
   Результат валидации доступен через атрибут `status` у экземпляра `InputFlag`. Подробнее см. :ref:`здесь <root_api_command_input_flag>`.

.. seealso::

   Документация по :ref:`Flag <root_api_command_flag>` — класс флага, использующий `PossibleValues`.
   
   Документация по :ref:`PredefinedFlags <root_api_command_flag_predefined_flags>` — готовые флаги с примерами использования `PossibleValues`.
   
   :ref:`Общая информация <root_flags>` о флагах и их использовании в приложении ``Argenta``

-----

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

NEITHER
~~~~~~~

.. code-block:: python
   :linenos:

   PossibleValues.NEITHER = 'NEITHER'

Указывает, что флаг **не должен** иметь значения.

Флаги с этим значением работают как булевы переключатели: их наличие в командной строке само по себе является информацией. Попытка передать такому флагу значение приведёт к ошибке валидации.

**Примеры флагов с** ``NEITHER``:

* ``--help`` — флаг справки
* ``--verbose`` — флаг подробного вывода
* ``--force`` — флаг принудительного выполнения
* ``-A`` / ``--all`` — флаг выбора всех элементов

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

.. literalinclude:: ../../../code_snippets/possible_values/neither.py
   :linenos:
   :language: python

-----

ALL
~~~

.. code-block:: python
   :linenos:

   PossibleValues.ALL = 'ALL'

Указывает, что флаг может принимать **любое** значение.

Флаги с этим значением универсальны и не накладывают ограничений на передаваемые данные. Валидация всегда будет успешной.

**Примеры флагов с** ``ALL``:

* ``--output`` — путь к выходному файлу
* ``--message`` — произвольное текстовое сообщение
* ``--name`` — произвольное имя
* ``--data`` — произвольные данные

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

.. literalinclude:: ../../../code_snippets/possible_values/all.py
   :linenos:
   :language: python

-----

Использование в Flag
---------------------

Параметр possible_values
~~~~~~~~~~~~~~~~~~~~~~~~~

`PossibleValues` используется как один из возможных типов для параметра `possible_values` при создании экземпляра `Flag`.

**Доступные типы для** `possible_values`:

1.  `PossibleValues.NEITHER`: флаг без значения.
2.  `PossibleValues.ALL`: флаг с любым значением (по умолчанию).
3.  `list[str]`: флаг с ограниченным набором значений.
4.  `Pattern[str]`: флаг со значением, проверяемым по регулярному выражению.

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

.. literalinclude:: ../../../code_snippets/possible_values/combined.py
   :linenos:
   :language: python

-----

Использование в PredefinedFlags
-------------------------------

Многие предопределённые флаги используют `PossibleValues.NEITHER`:

.. literalinclude:: ../../../code_snippets/possible_values/predefined.py
   :linenos:
   :language: python