dcos

.gitignore

@@ -8,3 +8,4 @@ uv.lock
 build
 source
 *cache
+.coverage

docs/code_snippets/input_flag_snippet1.py

@@ -0,0 +1,17 @@
+from argenta import InputFlag, ValidationStatus
+
+# Создание InputFlag с полным набором параметров
+output_flag = InputFlag(
+    name="output",
+    prefix="--",
+    input_value="result.txt",
+    status=ValidationStatus.VALID
+)
+
+# Флаг без значения
+help_flag = InputFlag(
+    name="help",
+    prefix="-",
+    input_value=None,
+    status=ValidationStatus.VALID
+)

docs/code_snippets/input_flag_snippet2.py

@@ -0,0 +1,11 @@
+from argenta import InputFlag, ValidationStatus
+
+flag = InputFlag(
+    name="verbose",
+    prefix="-",
+    input_value=None,
+    status=ValidationStatus.VALID
+)
+
+# Получение строкового представления флага
+print(flag.string_entity)  # -verbose

docs/code_snippets/input_flag_snippet3.py

@@ -0,0 +1,19 @@
+from argenta import InputFlag, ValidationStatus
+
+flag_with_value = InputFlag(
+    name="output",
+    prefix="--",
+    input_value="result.txt",
+    status=ValidationStatus.VALID
+)
+
+flag_without_value = InputFlag(
+    name="help",
+    prefix="-",
+    input_value=None,
+    status=ValidationStatus.VALID
+)
+
+# Строковое представление включает значение
+print(str(flag_with_value))  # --output result.txt
+print(str(flag_without_value))  # -help None

docs/code_snippets/input_flag_snippet4.py

@@ -0,0 +1,12 @@
+from argenta import InputFlag, ValidationStatus
+
+flag = InputFlag(
+    name="config",
+    prefix="--",
+    input_value="settings.json",
+    status=ValidationStatus.VALID
+)
+
+# Отладочное представление объекта
+print(repr(flag))
+# InputFlag<prefix='--', name='config', value='settings.json', status=ValidationStatus.VALID>

docs/code_snippets/input_flag_snippet5.py

@@ -0,0 +1,19 @@
+from argenta import InputFlag, ValidationStatus
+
+flag1 = InputFlag(
+    name="debug",
+    prefix="--",
+    input_value=None,
+    status=ValidationStatus.VALID
+)
+
+flag2 = InputFlag(
+    name="debug",
+    prefix="-",
+    input_value="true",
+    status=ValidationStatus.INVALID
+)
+
+# Сравнение по имени (префикс и значение не учитываются)
+if flag1 == flag2:
+    print("Флаги имеют одинаковое имя")  # Выведется

docs/code_snippets/possible_values_all_snippet.py

@@ -0,0 +1,13 @@
+from argenta.command import Flag, PossibleValues
+
+# Создание флагов с любыми значениями
+output_flag = Flag(name="output", possible_values=PossibleValues.ALL)
+message_flag = Flag(name="message", possible_values=PossibleValues.ALL)
+name_flag = Flag(name="name", possible_values=PossibleValues.ALL)
+
+# Можно передать любую строку или ничего
+# Примеры: 
+# --output result.json
+# --message "Any text here"
+# --name "User Name"
+# --message

docs/code_snippets/possible_values_combined_snippet.py

@@ -0,0 +1,26 @@
+from argenta.command import Flag, PossibleValues
+import re
+
+# Флаг без значения
+verbose_flag = Flag(
+    name="verbose",
+    possible_values=PossibleValues.NEITHER
+)
+
+# Флаг с любым значением
+output_flag = Flag(
+    name="output",
+    possible_values=PossibleValues.ALL
+)
+
+# Флаг со списком допустимых значений
+format_flag = Flag(
+    name="format",
+    possible_values=["json", "xml", "csv", "yaml"]
+)
+
+# Флаг с регулярным выражением
+email_flag = Flag(
+    name="email",
+    possible_values=re.compile(r"^[\w\.-]+@[\w\.-]+\.\w+$")
+)

docs/code_snippets/possible_values_neither_snippet.py

@@ -0,0 +1,10 @@
+from argenta.command import Flag, PossibleValues
+
+# Создание флагов без значений
+help_flag = Flag(name="help", possible_values=PossibleValues.NEITHER)
+verbose_flag = Flag(name="verbose", possible_values=PossibleValues.NEITHER)
+force_flag = Flag(name="force", possible_values=PossibleValues.NEITHER)
+
+# Такие флаги используются как переключатели
+# Правильно: myapp --help
+# Неправильно: myapp --help something

docs/code_snippets/possible_values_predefined_snippet.py

@@ -0,0 +1,10 @@
+from argenta.command.flag.defaults import PredefinedFlags
+
+# Проверка типа possible_values в предопределенных флагах
+print(PredefinedFlags.HELP.possible_values)       # PossibleValues.NEITHER
+print(PredefinedFlags.INFO.possible_values)       # PossibleValues.NEITHER
+print(PredefinedFlags.ALL.possible_values)        # PossibleValues.NEITHER
+
+# Сетевые флаги используют регулярные выражения, а не PossibleValues
+# PredefinedFlags.HOST использует Pattern для валидации IP
+# PredefinedFlags.PORT использует Pattern для валидации порта

docs/justfile

@@ -0,0 +1,34 @@
+set windows-shell := ["powershell.exe", "-NoLogo", "-Command"]
+set shell := ["bash", "-c"]
+
+# Variables
+sphinxopts := ""
+sphinxbuild := "sphinx-build"
+sourcedir := "."
+builddir := "_build"
+
+# Default recipe (help)
+default:
+    @{{sphinxbuild}} -M help "{{sourcedir}}" "{{builddir}}" {{sphinxopts}}
+
+# Build all language versions
+build-all:
+    {{sphinxbuild}} -b html -D language=ru {{sourcedir}} {{builddir}}/html/ru
+    {{sphinxbuild}} -b html -D language=en {{sourcedir}} {{builddir}}/html/en
+
+# Live preview for Russian version
+live-ru:
+    sphinx-autobuild -b html . _build/html/ru -D language=ru
+
+# Live preview for English version
+live-en:
+    sphinx-autobuild -b html . _build/html/en -D language=en
+
+# Update translation files
+update-langs:
+    {{sphinxbuild}} -b gettext . _build/gettext
+    sphinx-intl update -p _build/gettext -l en
+
+# Generic build target (html, latex, etc.)
+build target:
+    {{sphinxbuild}} -M {{target}} "{{sourcedir}}" "{{builddir}}" {{sphinxopts}}

docs/root/api/command/flag.rst

@@ -153,6 +153,8 @@ __eq__
 
 -----
 
+.. _root_api_command_flag_predefined_flags:
+
 PredefinedFlags
 ---------------
 

docs/root/api/command/input_flag.rst

@@ -1,6 +1,151 @@
 .. _root_api_command_input_flag:
 
 InputFlag
-==========
+=========
 
-Объект ``InputFlag`` представляет собой флаг команды, который принимает значение ввода от пользователя. Он наследуется от базового класса ``Flag`` и расширяет его функциональность, добавляя возможность указания типа ввода и обработки введенных данных.
+Объект ``InputFlag`` представляет собой сущность флага введённой команды. Он создаётся в результате парсинга пользовательского ввода и содержит информацию о распознанном флаге, включая его имя, префикс, введённое значение и статус валидации.
+
+.. seealso::
+
+   Документация по :ref:`Flag <root_api_command_flag>` — сущность флага, регистрируемого для последующей обработки.
+
+   Документация по :ref:`ValidationStatus <root_api_validation_status>` — статусы валидации флагов.
+
+-----
+
+Инициализация
+-------------
+
+.. code-block:: python
+   :linenos:
+
+   __init__(
+       self, name: str, *,
+       prefix: Literal['-', '--', '---'] = '--',
+       input_value: str | None,
+       status: ValidationStatus | None
+   )
+
+Создаёт новый объект введённого флага.
+
+* ``name`` : Имя введённого флага (обязательный параметр)
+* ``prefix`` : Префикс флага. По умолчанию ``"--"``. Возможные значения: ``"-"``, ``"--"``, ``"---"``
+* ``input_value`` : Значение введённого флага. Может быть ``None`` если флаг не принимает значения
+* ``status`` : Статус валидации флага из перечисления ``ValidationStatus``
+
+**Атрибуты:**
+
+.. py:attribute:: name
+
+   Имя введённого флага в виде строки.
+
+.. py:attribute:: prefix
+
+   Префикс флага. Один из: ``"-"``, ``"--"``, ``"---"``.
+
+.. py:attribute:: input_value
+
+   Значение, переданное с флагом в командной строке. Может быть ``None`` для флагов без значений.
+
+.. py:attribute:: status
+
+   Статус валидации флага. Один из: ``ValidationStatus.VALID``, ``ValidationStatus.INVALID``, ``ValidationStatus.UNDEFINED``.
+
+**Пример использования:**
+
+.. literalinclude:: ../../../code_snippets/input_flag_snippet1.py
+   :linenos:
+   :language: python
+
+-----
+
+Свойства
+--------
+
+string_entity
+~~~~~~~~~~~~~
+
+.. code-block:: python
+   :linenos:
+
+   @property
+   string_entity(self) -> str
+
+Возвращает строковое представление флага в формате ``prefix + name``.
+
+:return: Строковое представление флага
+
+Это свойство объединяет префикс и имя флага в единую строку, которая представляет, как флаг был введён в командной строке.
+
+**Пример использования:**
+
+.. literalinclude:: ../../../code_snippets/input_flag_snippet2.py
+   :linenos:
+   :language: python
+
+-----
+
+Магические методы
+-----------------
+
+__str__
+~~~~~~~
+
+.. code-block:: python
+   :linenos:
+
+   __str__(self) -> str
+
+Возвращает строковое представление введённого флага вместе с его значением.
+
+:return: Строка в формате ``флаг значение``
+
+**Пример использования:**
+
+.. literalinclude:: ../../../code_snippets/input_flag_snippet3.py
+   :linenos:
+   :language: python
+
+-----
+
+__repr__
+~~~~~~~~
+
+.. code-block:: python
+   :linenos:
+
+   __repr__(self) -> str
+
+Возвращает отладочное представление объекта введённого флага.
+
+:return: Строка в формате ``InputFlag<prefix=..., name=..., value=..., status=...>``
+
+**Пример использования:**
+
+.. literalinclude:: ../../../code_snippets/input_flag_snippet4.py
+   :linenos:
+   :language: python
+
+-----
+
+__eq__
+~~~~~~
+
+.. code-block:: python
+   :linenos:
+
+   __eq__(self, other: object) -> bool
+
+Сравнивает два введённых флага на равенство по их имени.
+
+:param other: Объект для сравнения
+:return: ``True``, если имена флагов совпадают, иначе ``False``
+:raises NotImplementedError: Если ``other`` не является экземпляром ``InputFlag``
+
+Два введённых флага считаются равными, если их имена идентичны.
+
+**Пример использования:**
+
+.. literalinclude:: ../../../code_snippets/input_flag_snippet5.py
+   :linenos:
+   :language: python

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
+

pyproject.toml

@@ -31,6 +31,7 @@ docs = [
 tests = [
     "pyfakefs>=5.5.0",
     "pytest>=8.3.2",
+    "pytest-cov>=7.0.0",
     "pytest-mock>=3.15.1",
 ]