From b0924a9e89c7daffedf542556af5bcd766056a65 Mon Sep 17 00:00:00 2001 From: kolo Date: Fri, 31 Oct 2025 22:59:19 +0300 Subject: [PATCH] dcos --- .gitignore | 1 + docs/code_snippets/input_flag_snippet1.py | 17 ++ docs/code_snippets/input_flag_snippet2.py | 11 ++ docs/code_snippets/input_flag_snippet3.py | 19 +++ docs/code_snippets/input_flag_snippet4.py | 12 ++ docs/code_snippets/input_flag_snippet5.py | 19 +++ .../possible_values_all_snippet.py | 13 ++ .../possible_values_combined_snippet.py | 26 +++ .../possible_values_neither_snippet.py | 10 ++ .../possible_values_predefined_snippet.py | 10 ++ docs/justfile | 34 ++++ docs/root/api/command/flag.rst | 2 + docs/root/api/command/input_flag.rst | 149 +++++++++++++++++- docs/root/api/command/possible_values.rst | 112 ++++++++++++- pyproject.toml | 1 + 15 files changed, 431 insertions(+), 5 deletions(-) create mode 100644 docs/code_snippets/input_flag_snippet1.py create mode 100644 docs/code_snippets/input_flag_snippet2.py create mode 100644 docs/code_snippets/input_flag_snippet3.py create mode 100644 docs/code_snippets/input_flag_snippet4.py create mode 100644 docs/code_snippets/input_flag_snippet5.py create mode 100644 docs/code_snippets/possible_values_all_snippet.py create mode 100644 docs/code_snippets/possible_values_combined_snippet.py create mode 100644 docs/code_snippets/possible_values_neither_snippet.py create mode 100644 docs/code_snippets/possible_values_predefined_snippet.py create mode 100644 docs/justfile diff --git a/.gitignore b/.gitignore index 02f9cd8..d2f4167 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,4 @@ uv.lock build source *cache +.coverage diff --git a/docs/code_snippets/input_flag_snippet1.py b/docs/code_snippets/input_flag_snippet1.py new file mode 100644 index 0000000..8138439 --- /dev/null +++ b/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 +) diff --git a/docs/code_snippets/input_flag_snippet2.py b/docs/code_snippets/input_flag_snippet2.py new file mode 100644 index 0000000..e0f0a6b --- /dev/null +++ b/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 diff --git a/docs/code_snippets/input_flag_snippet3.py b/docs/code_snippets/input_flag_snippet3.py new file mode 100644 index 0000000..853aecc --- /dev/null +++ b/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 diff --git a/docs/code_snippets/input_flag_snippet4.py b/docs/code_snippets/input_flag_snippet4.py new file mode 100644 index 0000000..62d7ce0 --- /dev/null +++ b/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 diff --git a/docs/code_snippets/input_flag_snippet5.py b/docs/code_snippets/input_flag_snippet5.py new file mode 100644 index 0000000..4825d3f --- /dev/null +++ b/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("Флаги имеют одинаковое имя") # Выведется diff --git a/docs/code_snippets/possible_values_all_snippet.py b/docs/code_snippets/possible_values_all_snippet.py new file mode 100644 index 0000000..7436593 --- /dev/null +++ b/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 diff --git a/docs/code_snippets/possible_values_combined_snippet.py b/docs/code_snippets/possible_values_combined_snippet.py new file mode 100644 index 0000000..c9b825a --- /dev/null +++ b/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+$") +) diff --git a/docs/code_snippets/possible_values_neither_snippet.py b/docs/code_snippets/possible_values_neither_snippet.py new file mode 100644 index 0000000..572bca0 --- /dev/null +++ b/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 diff --git a/docs/code_snippets/possible_values_predefined_snippet.py b/docs/code_snippets/possible_values_predefined_snippet.py new file mode 100644 index 0000000..79ff23b --- /dev/null +++ b/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 для валидации порта diff --git a/docs/justfile b/docs/justfile new file mode 100644 index 0000000..811f633 --- /dev/null +++ b/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}} diff --git a/docs/root/api/command/flag.rst b/docs/root/api/command/flag.rst index 4452405..322bc74 100644 --- a/docs/root/api/command/flag.rst +++ b/docs/root/api/command/flag.rst @@ -153,6 +153,8 @@ __eq__ ----- +.. _root_api_command_flag_predefined_flags: + PredefinedFlags --------------- diff --git a/docs/root/api/command/input_flag.rst b/docs/root/api/command/input_flag.rst index bcb07ce..bdd7e02 100644 --- a/docs/root/api/command/input_flag.rst +++ b/docs/root/api/command/input_flag.rst @@ -1,6 +1,151 @@ .. _root_api_command_input_flag: InputFlag -========== +========= -Объект ``InputFlag`` представляет собой флаг команды, который принимает значение ввода от пользователя. Он наследуется от базового класса ``Flag`` и расширяет его функциональность, добавляя возможность указания типа ввода и обработки введенных данных. +Объект ``InputFlag`` представляет собой сущность флага введённой команды. Он создаётся в результате парсинга пользовательского ввода и содержит информацию о распознанном флаге, включая его имя, префикс, введённое значение и статус валидации. + +.. seealso:: + + Документация по :ref:`Flag ` — сущность флага, регистрируемого для последующей обработки. + + Документация по :ref:`ValidationStatus ` — статусы валидации флагов. + +----- + +Инициализация +------------- + +.. 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`` + +**Пример использования:** + +.. 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 diff --git a/docs/root/api/command/possible_values.rst b/docs/root/api/command/possible_values.rst index bb7ce65..eadbd63 100644 --- a/docs/root/api/command/possible_values.rst +++ b/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:`тут ` + +.. seealso:: + + Документация по :ref:`Flag ` — сущности флага, использующей ``PossibleValues`` + + Документация по :ref:`PredefinedFlags ` — предопределенным флагам с примерами использования ``PossibleValues`` + + :ref:`Общая информация ` о флагах и их использовании в приложении ``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 + diff --git a/pyproject.toml b/pyproject.toml index 09e3a74..a679420 100644 --- a/pyproject.toml +++ b/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", ]