mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
feat: impl docs (#4)
The entire public api is covered with documentation in two languages - Russian and English. the library now supports the latest three versions of python - 3.12, 3.13 and 3.14 minor design changes: now, when a Boolean flag is entered, its value is an empty string, not None. tests have been adapted to the supported versions of python, readmi has been redesigned in two languages, German is no longer available.
This commit is contained in:
kolo
@@ -0,0 +1,257 @@
|
||||
.. _root_api_command_flag:
|
||||
|
||||
Flag
|
||||
=====
|
||||
|
||||
``Flag`` — это сущность, описывающая флаг команды. Её основная задача — определить параметры флага, включая его имя, префикс и правила валидации.
|
||||
|
||||
.. seealso::
|
||||
|
||||
Документация по :ref:`PossibleValues <root_api_command_possible_values>` — перечисление, определяющее типы допустимых значений.
|
||||
|
||||
Документация по :ref:`InputFlag <root_api_command_input_flag>` — объект обработанного флага, введённого пользователем.
|
||||
|
||||
:ref:`Общая информация <root_flags>` о флагах и их использовании в ``Argenta``
|
||||
|
||||
-----
|
||||
|
||||
Инициализация
|
||||
-------------
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
__init__(
|
||||
self, name: str, *,
|
||||
prefix: Literal["-", "--", "---"] = "--",
|
||||
possible_values: list[str] | Pattern[str] | PossibleValues = PossibleValues.ALL,
|
||||
) -> None
|
||||
|
||||
Создаёт новый флаг для регистрации в команде.
|
||||
|
||||
* ``name``: Имя флага (обязательный параметр).
|
||||
* ``prefix``: Префикс флага (``-``, ``--``, ``---``). По умолчанию ``--``.
|
||||
* ``possible_values``: Правила валидации значения. Может быть списком строк, регулярным выражением или значением из ``PossibleValues``. По умолчанию ``PossibleValues.ALL``, то есть любое значение допустимо.
|
||||
|
||||
**Атрибуты:**
|
||||
|
||||
.. py:attribute:: name
|
||||
|
||||
Имя флага в виде строки.
|
||||
|
||||
.. py:attribute:: prefix
|
||||
|
||||
Префикс флага. Один из: ``"-"``, ``"--"``, ``"---"``.
|
||||
|
||||
.. py:attribute:: possible_values
|
||||
|
||||
Допустимые значения для флага.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flag/snippet.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
Свойства
|
||||
--------
|
||||
|
||||
string_entity
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
@property
|
||||
string_entity(self) -> str
|
||||
|
||||
Возвращает строковое представление флага в формате ``prefix + name``.
|
||||
|
||||
:return: Строковое представление флага
|
||||
|
||||
Это свойство объединяет префикс и имя в единую строку, которая представляет флаг так, как он выглядел бы в командной строке.
|
||||
|
||||
-----
|
||||
|
||||
Магические методы
|
||||
-----------------
|
||||
|
||||
__str__
|
||||
~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
__str__(self) -> str
|
||||
|
||||
Возвращает строковое представление флага (аналогично ``string_entity``).
|
||||
|
||||
:return: Строковое представление флага
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flag/snippet4.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
__repr__
|
||||
~~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
__repr__(self) -> str
|
||||
|
||||
Возвращает отладочное представление объекта.
|
||||
|
||||
:return: Строка в формате ``Flag<prefix=..., name=...>``.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flag/snippet5.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
__eq__
|
||||
~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
__eq__(self, other: object) -> bool
|
||||
|
||||
Сравнивает два флага на равенство по их строковому представлению (``string_entity``).
|
||||
|
||||
:param other: Объект для сравнения
|
||||
:return: **True**, если флаги равны, иначе **False**
|
||||
|
||||
Два флага считаются равными, если их ``string_entity`` идентичны.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flag/snippet6.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
.. _root_api_command_flag_predefined_flags:
|
||||
|
||||
PredefinedFlags
|
||||
---------------
|
||||
|
||||
``argenta.command.PredefinedFlags``
|
||||
|
||||
Класс ``PredefinedFlags`` предоставляет набор готовых флагов для использования в приложениях без их ручного создания. Эти флаги покрывают распространённые сценарии.
|
||||
|
||||
Все предопределённые флаги являются атрибутами класса и представляют собой готовые экземпляры ``Flag``.
|
||||
|
||||
-----
|
||||
|
||||
Информационные флаги
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
.. py:attribute:: PredefinedFlags.HELP
|
||||
|
||||
Флаг для отображения справки: ``--help``
|
||||
|
||||
* ``name``: ``"help"``
|
||||
* ``prefix``: ``"--"`` (по умолчанию)
|
||||
* ``possible_values``: ``PossibleValues.NEITHER``
|
||||
|
||||
.. py:attribute:: PredefinedFlags.SHORT_HELP
|
||||
|
||||
Короткая версия флага справки: ``-H``
|
||||
|
||||
* ``name``: ``"H"``
|
||||
* ``prefix``: ``"-"``
|
||||
* ``possible_values``: ``PossibleValues.NEITHER``
|
||||
|
||||
.. py:attribute:: PredefinedFlags.INFO
|
||||
|
||||
Флаг для отображения информации: ``--info``
|
||||
|
||||
* ``name``: ``"info"``
|
||||
* ``prefix``: ``"--"`` (по умолчанию)
|
||||
* ``possible_values``: ``PossibleValues.NEITHER``
|
||||
|
||||
.. py:attribute:: PredefinedFlags.SHORT_INFO
|
||||
|
||||
Короткая версия флага информации: ``-I``
|
||||
|
||||
* ``name``: ``"I"``
|
||||
* ``prefix``: ``"-"``
|
||||
* ``possible_values``: ``PossibleValues.NEITHER``
|
||||
|
||||
-----
|
||||
|
||||
Флаги выбора
|
||||
~~~~~~~~~~~~
|
||||
|
||||
.. py:attribute:: PredefinedFlags.ALL
|
||||
|
||||
Флаг для выбора всех элементов: ``--all``
|
||||
|
||||
* ``name``: ``"all"``
|
||||
* ``prefix``: ``"--"``
|
||||
* ``possible_values``: ``PossibleValues.NEITHER``
|
||||
|
||||
.. py:attribute:: PredefinedFlags.SHORT_ALL
|
||||
|
||||
Короткая версия флага выбора всех элементов: ``-A``
|
||||
|
||||
* ``name``: ``"A"``
|
||||
* ``prefix``: ``"-"``
|
||||
* ``possible_values``: ``PossibleValues.NEITHER``
|
||||
|
||||
-----
|
||||
|
||||
Сетевые флаги
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. py:attribute:: PredefinedFlags.HOST
|
||||
|
||||
Флаг для указания IP-адреса хоста: ``--host``
|
||||
|
||||
* ``name``: ``"host"``
|
||||
* ``prefix``: ``"--"`` (по умолчанию)
|
||||
* ``possible_values``: Регулярное выражение для валидации IPv4: ``r"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$"``
|
||||
|
||||
.. py:attribute:: PredefinedFlags.SHORT_HOST
|
||||
|
||||
Короткая версия флага хоста: ``-H``
|
||||
|
||||
* ``name``: ``"H"``
|
||||
* ``prefix``: ``"-"``
|
||||
* ``possible_values``: Регулярное выражение для валидации IPv4: ``r"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$"``
|
||||
|
||||
.. py:attribute:: PredefinedFlags.PORT
|
||||
|
||||
Флаг для указания порта: ``--port``
|
||||
|
||||
* ``name``: ``"port"``
|
||||
* ``prefix``: ``"--"`` (по умолчанию)
|
||||
* ``possible_values``: Регулярное выражение для валидации порта: ``r"^\d{1,5}$"``
|
||||
|
||||
.. py:attribute:: PredefinedFlags.SHORT_PORT
|
||||
|
||||
Короткая версия флага порта: ``-P``
|
||||
|
||||
* ``name``: ``"P"``
|
||||
* ``prefix``: ``"-"``
|
||||
* ``possible_values``: Регулярное выражение для валидации порта: ``r"^\d{1,5}$"``
|
||||
|
||||
-----
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flag/predefined_flags.py
|
||||
:linenos:
|
||||
:language: python
|
||||
@@ -0,0 +1,113 @@
|
||||
.. _root_api_command_flags:
|
||||
|
||||
Flags
|
||||
======
|
||||
|
||||
``Flags`` — это коллекция флагов команды. Её основная задача — группировать и управлять набором флагов, зарегистрированных для конкретной команды. ``Flags`` служит контейнером, который позволяет удобно добавлять, извлекать, итерировать флаги и проверять их наличие.
|
||||
|
||||
.. seealso::
|
||||
|
||||
Документация по отдельным флагам (:ref:`Flag <root_api_command_flag>`, :ref:`InputFlag <root_api_command_input_flag>`)
|
||||
|
||||
Документация по :ref:`InputFlags <root_api_command_input_flags>` — коллекция обработанных флагов, введённых пользователем.
|
||||
|
||||
:ref:`Общая информация <root_flags>` о флагах и их использовании в приложении ``Argenta``
|
||||
|
||||
-----
|
||||
|
||||
Инициализация
|
||||
-------------
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
__init__(self, flags: list[Flag] | None = None) -> None
|
||||
|
||||
Создаёт новую коллекцию флагов.
|
||||
|
||||
* ``flags``: Необязательный список флагов типа ``Flag`` для инициализации коллекции. Если не указан, создаётся пустая коллекция.
|
||||
|
||||
**Атрибуты:**
|
||||
|
||||
.. py:attribute:: flags
|
||||
:no-index:
|
||||
|
||||
Список всех зарегистрированных флагов типа ``Flag``.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flags/snippet.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
Методы
|
||||
------
|
||||
|
||||
add_flag
|
||||
~~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
add_flag(self, flag: Flag) -> None
|
||||
|
||||
Добавляет флаг в коллекцию.
|
||||
|
||||
:param flag: Флаг типа ``Flag`` для добавления.
|
||||
:return: None.
|
||||
|
||||
Используется для динамического расширения набора флагов.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flags/snippet2.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
add_flags
|
||||
~~~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
add_flags(self, flags: list[Flag]) -> None
|
||||
|
||||
Добавляет в коллекцию список флагов.
|
||||
|
||||
:param flags: Список флагов типа ``Flag`` для добавления.
|
||||
:return: None.
|
||||
|
||||
Метод расширяет коллекцию, добавляя в неё все флаги из переданного списка. Эффективен для пакетного добавления.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flags/snippet3.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
get_flag_by_name
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
get_flag_by_name(self, name: str) -> Flag | None
|
||||
|
||||
Возвращает флаг по имени.
|
||||
|
||||
:param name: Имя искомого флага.
|
||||
:return: Объект ``Flag`` или ``None``, если флаг не найден.
|
||||
|
||||
Метод возвращает флаг с соответствующим именем. Если флаг не найден, возвращается ``None``.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flags/snippet4.py
|
||||
:linenos:
|
||||
:language: python
|
||||
@@ -0,0 +1,128 @@
|
||||
.. _root_api_command_index:
|
||||
|
||||
Command
|
||||
=======
|
||||
|
||||
``Command`` — это основная единица функциональности в приложении. Каждая команда связывает хэндлер с триггером, введя который он будет вызван для обработки.
|
||||
|
||||
``Command`` инкапсулирует всю информацию о команде: её триггер (ключевое слово для вызова), описание, набор флагов и список псевдонимов.
|
||||
|
||||
-----
|
||||
|
||||
Инициализация
|
||||
-------------
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
__init__(self, trigger: str, *,
|
||||
description: str | None = None,
|
||||
flags: Flag | Flags = DEFAULT_WITHOUT_FLAGS,
|
||||
aliases: list[str] | list[Never] = DEFAULT_WITHOUT_ALIASES) -> None
|
||||
|
||||
Создаёт новую команду для регистрации в роутере.
|
||||
|
||||
* ``trigger``: Строковый триггер, который пользователь вводит для вызова команды. Является основным идентификатором.
|
||||
* ``description``: Необязательное описание, объясняющее назначение команды. Отображается в справке.
|
||||
* ``flags``: Набор флагов для настройки поведения. Может быть одиночным объектом ``Flag`` или коллекцией ``Flags``.
|
||||
* ``aliases``: Список строковых псевдонимов для основного триггера.
|
||||
|
||||
**Атрибуты:**
|
||||
|
||||
.. py:attribute:: trigger
|
||||
|
||||
Основной триггер команды. Используется для её идентификации при обработке пользовательского ввода.
|
||||
|
||||
.. py:attribute:: description
|
||||
|
||||
Текстовое описание команды. Если не передано, используется значение по умолчанию.
|
||||
|
||||
.. py:attribute:: registered_flags
|
||||
|
||||
Объект ``Flags``, содержащий все зарегистрированные флаги. Если был передан ``Flag``, то автоматически конвертируется из одиночного в коллекцию при инициализации.
|
||||
|
||||
.. py:attribute:: aliases
|
||||
|
||||
Список строковых псевдонимов. Пуст, если псевдонимы не заданы.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/command/snippet.py
|
||||
:linenos:
|
||||
|
||||
.. seealso ::
|
||||
Подробнее про флаги: :ref:`Flags <root_api_command_flags>` и :ref:`Флаги команд <root_flags>`.
|
||||
|
||||
-----
|
||||
|
||||
Регистрация команд
|
||||
------------------
|
||||
|
||||
Команды передаются в качестве аргумента в декоратор ``@router.command()``.
|
||||
|
||||
**Базовый пример:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/command/snippet2.py
|
||||
:linenos:
|
||||
|
||||
**Команды с флагами:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/command/snippet3.py
|
||||
:linenos:
|
||||
|
||||
-----
|
||||
|
||||
Работа с псевдонимами
|
||||
---------------------
|
||||
|
||||
Псевдонимы позволяют вызывать один и тот же обработчик разными триггерами, сохраняя флаги и описание команды.
|
||||
|
||||
**Пример с псевдонимами:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/command/snippet5.py
|
||||
:linenos:
|
||||
|
||||
Теперь пользователь может вызвать команду любым из способов:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
shutdown
|
||||
poweroff
|
||||
halt
|
||||
stop
|
||||
|
||||
Все эти варианты вызовут один и тот же хэндлер ``handle_shutdown``.
|
||||
|
||||
-----
|
||||
|
||||
.. _root_api_command_input_command:
|
||||
|
||||
InputCommand
|
||||
------------
|
||||
|
||||
``InputCommand`` представляет собой обработанную команду, введённую пользователем. Этот внутренний класс создаётся автоматически при обработке пользовательского ввода. Прямая работа с ним возможна при создании пользовательского обработчика для неизвестных команд.
|
||||
|
||||
.. seealso ::
|
||||
Подробнее о пользовательских обработчиках исключений см. :ref:`здесь <root_error_handling_unknown_command>`.
|
||||
|
||||
**Атрибуты:**
|
||||
|
||||
.. py:attribute:: trigger
|
||||
:no-index:
|
||||
|
||||
Строковый триггер, введённый пользователем.
|
||||
|
||||
.. py:attribute:: input_flags
|
||||
:no-index:
|
||||
|
||||
Объект ``InputFlags``, содержащий все введённые и распаршенные флаги.
|
||||
|
||||
.. toctree ::
|
||||
:hidden:
|
||||
|
||||
flag
|
||||
possible_values
|
||||
input_flag
|
||||
validation_status
|
||||
flags
|
||||
input_flags
|
||||
@@ -0,0 +1,116 @@
|
||||
.. _root_api_command_input_flag:
|
||||
|
||||
InputFlag
|
||||
=========
|
||||
|
||||
Объект ``InputFlag`` представляет собой флаг, введённый пользователем. Он создаётся в результате обработки пользовательского ввода и содержит информацию о распознанном флаге: его имя, префикс, значение и статус валидации.
|
||||
|
||||
.. seealso::
|
||||
|
||||
Документация по :ref:`Flag <root_api_command_flag>` — класс для регистрации флага.
|
||||
|
||||
Документация по :ref:`ValidationStatus <root_api_command_validation_status>` — статусы валидации флагов.
|
||||
|
||||
-----
|
||||
|
||||
.. warning ::
|
||||
Экземпляры этого класса не предназначены для прямого создания. Они содержатся в объекте :ref:`Response <root_api_response>`.
|
||||
|
||||
**Атрибуты:**
|
||||
|
||||
.. py:attribute:: name
|
||||
:no-index:
|
||||
|
||||
Имя введённого флага.
|
||||
|
||||
.. py:attribute:: prefix
|
||||
:no-index:
|
||||
|
||||
Префикс флага: ``-``, ``--`` или ``---``.
|
||||
|
||||
.. py:attribute:: input_value
|
||||
|
||||
Значение, переданное с флагом. Может быть ``''`` (пустой строкой) для флагов без значений.
|
||||
|
||||
.. py:attribute:: status
|
||||
:no-index:
|
||||
|
||||
Статус валидации флага: ``ValidationStatus.VALID``, ``ValidationStatus.INVALID`` или ``ValidationStatus.UNDEFINED``.
|
||||
|
||||
-----
|
||||
|
||||
Свойства
|
||||
--------
|
||||
|
||||
string_entity
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
@property
|
||||
string_entity(self) -> str
|
||||
|
||||
Возвращает строковое представление флага в формате ``prefix + name``.
|
||||
|
||||
:return: Строковое представление флага
|
||||
|
||||
-----
|
||||
|
||||
Магические методы
|
||||
-----------------
|
||||
|
||||
__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**.
|
||||
|
||||
Два введённых флага считаются равными, если их имена совпадают.
|
||||
@@ -0,0 +1,135 @@
|
||||
.. _root_api_command_input_flags:
|
||||
|
||||
InputFlags
|
||||
==========
|
||||
|
||||
``InputFlags`` — это коллекция флагов, введённых пользователем. Её основная задача — группировать и управлять набором флагов, переданных вместе с командой. ``InputFlags`` служит контейнером, который позволяет удобно извлекать, итерировать и проверять наличие флагов, а также работать с их значениями и статусами валидации.
|
||||
|
||||
.. seealso::
|
||||
|
||||
Документация по отдельным флагам (:ref:`Flag <root_api_command_flag>`, :ref:`InputFlag <root_api_command_input_flag>`)
|
||||
|
||||
Документация по :ref:`InputFlags <root_api_command_input_flags>` — коллекция обработанных флагов, введённых пользователем.
|
||||
|
||||
Документация по :ref:`Response <root_api_response>` — объект ответа, содержащий ``InputFlags``
|
||||
|
||||
:ref:`Общая информация <root_flags>` о флагах и их использовании в приложении ``Argenta``
|
||||
|
||||
-----
|
||||
|
||||
Инициализация
|
||||
-------------
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
__init__(self, flags: list[InputFlag] | None = None) -> None
|
||||
|
||||
Создаёт новую коллекцию введённых флагов.
|
||||
|
||||
* ``flags``: Необязательный список флагов типа ``InputFlag`` для инициализации коллекции. Если не указан, создаётся пустая коллекция.
|
||||
|
||||
.. warning ::
|
||||
Экземпляры этого класса обычно не создаются напрямую. Они автоматически формируются системой при обработке пользовательского ввода и доступны через атрибут ``input_flags`` объекта ``Response``.
|
||||
|
||||
**Атрибуты:**
|
||||
|
||||
.. py:attribute:: flags
|
||||
:no-index:
|
||||
|
||||
Список всех введённых флагов типа ``InputFlag``. Пуст, если флаги не были переданы при инициализации или пользователь не ввёл их с командой.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/input_flags/snippet1.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
Методы
|
||||
------
|
||||
|
||||
get_flag_by_name
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
get_flag_by_name(self, name: str) -> InputFlag | None
|
||||
|
||||
Возвращает флаг по имени.
|
||||
|
||||
:param name: Имя искомого флага (без префикса).
|
||||
:return: Объект ``InputFlag`` или ``None``, если флаг не найден.
|
||||
|
||||
Метод возвращает первый флаг с соответствующим именем (без учёта префикса).
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/input_flags/snippet2.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
add_flag
|
||||
~~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
add_flag(self, flag: InputFlag) -> None
|
||||
|
||||
Добавляет введённый флаг в коллекцию.
|
||||
|
||||
:param flag: Флаг типа ``InputFlag`` для добавления.
|
||||
:return: None.
|
||||
|
||||
Метод добавляет флаг в конец списка ``flags``. Используется для динамического расширения коллекции.
|
||||
|
||||
.. note::
|
||||
Этот метод используется редко, так как `InputFlags` обычно создаётся автоматически. Однако он может быть полезен для тестирования или ручного создания коллекций.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/input_flags/snippet3.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
add_flags
|
||||
~~~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
add_flags(self, flags: list[InputFlag]) -> None
|
||||
|
||||
Добавляет в коллекцию список введённых флагов.
|
||||
|
||||
:param flags: Список флагов типа ``InputFlag`` для добавления.
|
||||
:return: None.
|
||||
|
||||
Метод расширяет коллекцию, добавляя в неё все флаги из переданного списка. Эффективен для пакетного добавления.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/input_flags/snippet4.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
Практические примеры
|
||||
--------------------
|
||||
|
||||
Обработка всех флагов с проверкой статусов
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/input_flags/snippet10.py
|
||||
:linenos:
|
||||
:language: python
|
||||
@@ -0,0 +1,92 @@
|
||||
.. _root_api_command_possible_values:
|
||||
|
||||
|
||||
PossibleValues
|
||||
==============
|
||||
|
||||
``PossibleValues`` — это перечисление, которое определяет специальные режимы валидации для значений флагов. ``PossibleValues`` используется в параметре ``possible_values`` класса ``Flag``, чтобы указать, может ли флаг принимать значения и какие ограничения на них накладываются.
|
||||
|
||||
``PossibleValues`` содержит два основных значения: ``NEITHER`` (для флагов, которые не могут принимать значения) и ``ALL`` (для флагов, принимающих любые значения). Это перечисление используется вместе со списками строк и регулярными выражениями для создания гибкой системы валидации.
|
||||
|
||||
.. note::
|
||||
Результат валидации доступен через атрибут ``status`` у экземпляра ``InputFlag``. Подробнее см. :ref:`здесь <root_api_command_input_flag>`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
Документация по :ref:`Flag <root_api_command_flag>` — класс флага, использующий ``PossibleValues``.
|
||||
|
||||
Документация по :ref:`ValidationStatus <root_api_command_validation_status>` — результат валидации ввёденного флага.
|
||||
|
||||
:ref:`Общая информация <root_flags>` о флагах и их использовании в приложении ``Argenta``
|
||||
|
||||
-----
|
||||
|
||||
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``:
|
||||
|
||||
* ``--message`` — произвольное текстовое сообщение
|
||||
* ``--name`` — произвольное имя
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/possible_values/all.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
Параметр 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
|
||||
@@ -0,0 +1,78 @@
|
||||
.. _root_api_command_validation_status:
|
||||
|
||||
ValidationStatus
|
||||
================
|
||||
|
||||
``ValidationStatus`` — это перечисление, которое определяет состояние валидации флага. Его задача — предоставить стандартные константы для отображения результата проверки. ``ValidationStatus`` используется в атрибуте ``status`` класса ``InputFlag``.
|
||||
|
||||
``ValidationStatus`` содержит три значения: **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>` — типы допустимых значений.
|
||||
|
||||
-----
|
||||
|
||||
VALID
|
||||
~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
ValidationStatus.VALID = 'VALID'
|
||||
|
||||
Указывает, что флаг и его значение **прошли** валидацию.
|
||||
|
||||
Флаги с этим статусом соответствуют правилам, заданным в ``possible_values`` соответствующего ``Flag``. Их можно безопасно использовать в логике приложения без дополнительных проверок.
|
||||
|
||||
**Условия получения статуса** ``VALID``:
|
||||
|
||||
* Флаг с ``PossibleValues.NEITHER`` передан без значения.
|
||||
* Флаг с ``PossibleValues.ALL`` передан с любым значением или без него.
|
||||
* Значение флага входит в список разрешённых.
|
||||
* Значение флага соответствует регулярному выражению.
|
||||
|
||||
-----
|
||||
|
||||
INVALID
|
||||
~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
ValidationStatus.INVALID = 'INVALID'
|
||||
|
||||
Указывает, что флаг или его значение **не прошли** валидацию.
|
||||
|
||||
Флаги с этим статусом нарушают правила, заданные в ``possible_values`` соответствующего ``Flag``. Их следует обрабатывать как ошибочные.
|
||||
|
||||
**Условия получения статуса** ``INVALID``:
|
||||
|
||||
* Флаг с ``PossibleValues.NEITHER`` передан со значением.
|
||||
* Значение флага не входит в список разрешённых.
|
||||
* Значение флага не соответствует регулярному выражению.
|
||||
* Флаг требует значение, но передан без него.
|
||||
|
||||
-----
|
||||
|
||||
UNDEFINED
|
||||
~~~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
ValidationStatus.UNDEFINED = 'UNDEFINED'
|
||||
|
||||
Указывает, что введённый флаг не был зарегистрирован в команде.
|
||||
|
||||
**Условия получения статуса** ``UNDEFINED``:
|
||||
|
||||
* Введённый флаг не найден среди зарегистрированных для данной команды.
|
||||
Reference in New Issue
Block a user