dcos

docs/root/api/command/possible_values.rst

@@ -1,6 +1,112 @@
 .. _root_api_command_possible_values:
 
-PossibleValues
-****************
 
-mda
+PossibleValues
+==============
+
+Enum ``PossibleValues`` представляет собой перечисление, определяющее специальные режимы валидации значений флагов в приложении ``Argenta``. Его основная задача — предоставить стандартизированные константы для управления поведением флагов в отношении допустимых значений. ``PossibleValues`` используется в параметре ``possible_values`` класса ``Flag`` для определения того, может ли флаг принимать значения и какие ограничения на них накладываются.
+
+``PossibleValues`` наследуется от стандартного класса ``Enum`` и содержит два основных значения: ``NEITHER`` для флагов без значений и ``ALL`` для флагов, принимающих любые значения. Этот enum используется совместно со списками строк и регулярными выражениями для создания гибкой системы валидации флагов.
+
+.. 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_snippet.py
+   :linenos:
+   :language: python
+
+-----
+
+ALL
+~~~
+
+.. code-block:: python
+   :linenos:
+
+   PossibleValues.ALL = 'ALL'
+
+Указывает, что флаг может принимать **любое** значение без ограничений.
+
+Флаги с этим значением являются универсальными и не накладывают никаких ограничений на передаваемые данные. Валидация всегда успешна для любой строки или её отсутствия.
+
+**Примеры флагов с** ``ALL``:
+
+* ``--output`` — путь к выходному файлу
+* ``--message`` — произвольное текстовое сообщение
+* ``--name`` — произвольное имя
+* ``--data`` — произвольные данные
+
+**Пример использования:**
+
+.. literalinclude:: ../../../code_snippets/possible_values_all_snippet.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_snippet.py
+   :linenos:
+   :language: python
+
+-----
+
+Использование в PredefinedFlags
+-------------------------------
+
+Многие предопределенные флаги используют ``PossibleValues.NEITHER``:
+
+.. literalinclude:: ../../../code_snippets/possible_values_predefined_snippet.py
+   :linenos:
+   :language: python
+