mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 18:15:28 +03:00
docs
This commit is contained in:
@@ -3,7 +3,7 @@
|
||||
Flag
|
||||
=====
|
||||
|
||||
``Flag`` — это сущность, описывающая флаг команды. Её основная задача — определить параметры флага, включая его имя, префикс и правила валидации. `Flag` используется при создании команд и предоставляет механизм для проверки значений, введённых пользователем.
|
||||
``Flag`` — это сущность, описывающая флаг команды. Её основная задача — определить параметры флага, включая его имя, префикс и правила валидации.
|
||||
|
||||
.. seealso::
|
||||
|
||||
@@ -11,7 +11,7 @@ Flag
|
||||
|
||||
Документация по :ref:`InputFlag <root_api_command_input_flag>` — объект обработанного флага, введённого пользователем.
|
||||
|
||||
:ref:`Общая информация <root_flags>` о флагах и их использовании в приложении ``Argenta``
|
||||
:ref:`Общая информация <root_flags>` о флагах и их использовании в ``Argenta``
|
||||
|
||||
-----
|
||||
|
||||
@@ -31,7 +31,7 @@ Flag
|
||||
|
||||
* ``name``: Имя флага (обязательный параметр).
|
||||
* ``prefix``: Префикс флага (``-``, ``--``, ``---``). По умолчанию ``--``.
|
||||
* ``possible_values``: Правила валидации значения. Может быть списком строк, регулярным выражением или значением из `PossibleValues`. По умолчанию `PossibleValues.ALL`.
|
||||
* ``possible_values``: Правила валидации значения. Может быть списком строк, регулярным выражением или значением из ``PossibleValues``. По умолчанию ``PossibleValues.ALL``, то есть любое значение допустимо.
|
||||
|
||||
**Атрибуты:**
|
||||
|
||||
@@ -45,12 +45,7 @@ Flag
|
||||
|
||||
.. py:attribute:: possible_values
|
||||
|
||||
Определяет допустимые значения для флага:
|
||||
|
||||
* Список строк: флаг принимает только значения из этого списка.
|
||||
* Регулярное выражение (`Pattern[str]`): значение проверяется на соответствие паттерну.
|
||||
* `PossibleValues.ALL`: флаг принимает любое значение.
|
||||
* `PossibleValues.NEITHER`: флаг не должен иметь значения.
|
||||
Допустимые значения для флага.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -78,12 +73,6 @@ string_entity
|
||||
|
||||
Это свойство объединяет префикс и имя в единую строку, которая представляет флаг так, как он выглядел бы в командной строке.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flag/snippet3.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
Магические методы
|
||||
@@ -97,7 +86,7 @@ __str__
|
||||
|
||||
__str__(self) -> str
|
||||
|
||||
Возвращает строковое представление флага (аналогично `string_entity`).
|
||||
Возвращает строковое представление флага (аналогично ``string_entity``).
|
||||
|
||||
:return: Строковое представление флага
|
||||
|
||||
@@ -119,7 +108,7 @@ __repr__
|
||||
|
||||
Возвращает отладочное представление объекта.
|
||||
|
||||
:return: Строка в формате `Flag<prefix=..., name=...>`.
|
||||
:return: Строка в формате ``Flag<prefix=..., name=...>``.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -137,13 +126,12 @@ __eq__
|
||||
|
||||
__eq__(self, other: object) -> bool
|
||||
|
||||
Сравнивает два флага на равенство по их строковому представлению (`string_entity`).
|
||||
Сравнивает два флага на равенство по их строковому представлению (``string_entity``).
|
||||
|
||||
:param other: Объект для сравнения
|
||||
:return: ``True``, если флаги равны, иначе ``False``
|
||||
:raises NotImplementedError: Если `other` не является экземпляром `Flag`.
|
||||
:return: **True**, если флаги равны, иначе **False**
|
||||
|
||||
Два флага считаются равными, если их `string_entity` идентичны.
|
||||
Два флага считаются равными, если их ``string_entity`` идентичны.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -160,9 +148,9 @@ PredefinedFlags
|
||||
|
||||
``argenta.command.PredefinedFlags``
|
||||
|
||||
Класс `PredefinedFlags` предоставляет набор готовых флагов для использования в приложениях без их ручного создания. Эти флаги покрывают наиболее распространённые сценарии и следуют общепринятым соглашениям.
|
||||
Класс ``PredefinedFlags`` предоставляет набор готовых флагов для использования в приложениях без их ручного создания. Эти флаги покрывают распространённые сценарии.
|
||||
|
||||
Все предопределённые флаги являются атрибутами класса и представляют собой готовые экземпляры `Flag`.
|
||||
Все предопределённые флаги являются атрибутами класса и представляют собой готовые экземпляры ``Flag``.
|
||||
|
||||
-----
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Command
|
||||
=======
|
||||
|
||||
``Command`` — это основная единица функциональности в приложении. Каждая команда определяет действие, которое пользователь может выполнить, введя соответствующий триггер. Команды регистрируются в роутерах и формируют интерфейс взаимодействия с приложением.
|
||||
``Command`` — это основная единица функциональности в приложении. Каждая команда связывает хэндлер с триггером, введя который он будет вызван для обработки.
|
||||
|
||||
``Command`` инкапсулирует всю информацию о команде: её триггер (ключевое слово для вызова), описание, набор флагов и список псевдонимов.
|
||||
|
||||
@@ -18,13 +18,13 @@ Command
|
||||
__init__(self, trigger: str, *,
|
||||
description: str | None = None,
|
||||
flags: Flag | Flags = DEFAULT_WITHOUT_FLAGS,
|
||||
aliases: list[str] | None = None) -> None
|
||||
aliases: list[str] | list[Never] = DEFAULT_WITHOUT_ALIASES) -> None
|
||||
|
||||
Создаёт новую команду для регистрации в роутере.
|
||||
|
||||
* ``trigger``: Строковый триггер, который пользователь вводит для вызова команды. Является основным идентификатором.
|
||||
* ``description``: Необязательное описание, объясняющее назначение команды. Отображается в справке.
|
||||
* ``flags``: Набор флагов для настройки поведения. Может быть одиночным объектом `Flag` или коллекцией `Flags`.
|
||||
* ``flags``: Набор флагов для настройки поведения. Может быть одиночным объектом ``Flag`` или коллекцией ``Flags``.
|
||||
* ``aliases``: Список строковых псевдонимов для основного триггера.
|
||||
|
||||
**Атрибуты:**
|
||||
@@ -39,7 +39,7 @@ Command
|
||||
|
||||
.. py:attribute:: registered_flags
|
||||
|
||||
Объект `Flags`, содержащий все зарегистрированные флаги. Автоматически конвертируется из одиночного `Flag` в коллекцию при инициализации.
|
||||
Объект ``Flags``, содержащий все зарегистрированные флаги. Если был передан ``Flag``, то автоматически конвертируется из одиночного в коллекцию при инициализации.
|
||||
|
||||
.. py:attribute:: aliases
|
||||
|
||||
@@ -58,7 +58,7 @@ Command
|
||||
Регистрация команд
|
||||
------------------
|
||||
|
||||
Команды регистрируются в роутерах с помощью декоратора ``@router.command()``, после чего становятся доступными для вызова.
|
||||
Команды передаются в качестве аргумента в декоратор ``@router.command()``.
|
||||
|
||||
**Базовый пример:**
|
||||
|
||||
@@ -79,21 +79,9 @@ Command
|
||||
|
||||
**Пример с псевдонимами:**
|
||||
|
||||
.. code-block:: python
|
||||
.. literalinclude:: ../../../code_snippets/command/snippet5.py
|
||||
:linenos:
|
||||
|
||||
from argenta import Router, Command
|
||||
|
||||
router = Router(title="System")
|
||||
|
||||
@router.command(Command(
|
||||
"shutdown",
|
||||
description="Shutdown the system",
|
||||
aliases=["poweroff", "halt", "stop"]
|
||||
))
|
||||
def handle_shutdown(response):
|
||||
response.write("Shutting down the system...")
|
||||
|
||||
Теперь пользователь может вызвать команду любым из способов:
|
||||
|
||||
.. code-block:: bash
|
||||
@@ -103,7 +91,7 @@ Command
|
||||
halt
|
||||
stop
|
||||
|
||||
Все эти варианты выполнят одну и ту же функцию ``handle_shutdown``.
|
||||
Все эти варианты вызовут один и тот же хэндлер ``handle_shutdown``.
|
||||
|
||||
-----
|
||||
|
||||
@@ -115,12 +103,7 @@ InputCommand
|
||||
``InputCommand`` представляет собой обработанную команду, введённую пользователем. Этот внутренний класс создаётся автоматически при обработке пользовательского ввода. Прямая работа с ним возможна при создании пользовательского обработчика для неизвестных команд.
|
||||
|
||||
.. seealso ::
|
||||
Подробнее о пользовательских обработчиках исключений см. :ref:`здесь <root_error_handling>`.
|
||||
|
||||
Создаёт экземпляр обработанной команды.
|
||||
|
||||
:param trigger: Триггер команды, извлечённый из пользовательского ввода.
|
||||
:param input_flags: Флаги, переданные пользователем.
|
||||
Подробнее о пользовательских обработчиках исключений см. :ref:`здесь <root_error_handling_unknown_command>`.
|
||||
|
||||
**Атрибуты:**
|
||||
|
||||
@@ -132,7 +115,7 @@ InputCommand
|
||||
.. py:attribute:: input_flags
|
||||
:no-index:
|
||||
|
||||
Объект `InputFlags`, содержащий все переданные с командой флаги. Автоматически конвертируется из одиночного `InputFlag` в коллекцию.
|
||||
Объект ``InputFlags``, содержащий все введённые и распаршенные флаги.
|
||||
|
||||
.. toctree ::
|
||||
:hidden:
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
InputFlag
|
||||
=========
|
||||
|
||||
Объект `InputFlag` представляет собой флаг, введённый пользователем. Он создаётся в результате обработки пользовательского ввода и содержит информацию о распознанном флаге: его имя, префикс, значение и статус валидации.
|
||||
Объект ``InputFlag`` представляет собой флаг, введённый пользователем. Он создаётся в результате обработки пользовательского ввода и содержит информацию о распознанном флаге: его имя, префикс, значение и статус валидации.
|
||||
|
||||
.. seealso::
|
||||
|
||||
@@ -13,26 +13,6 @@ InputFlag
|
||||
|
||||
-----
|
||||
|
||||
Инициализация
|
||||
-------------
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
__init__(
|
||||
self, name: str, *,
|
||||
prefix: Literal['-', '--', '---'] = '--',
|
||||
input_value: str | None,
|
||||
status: ValidationStatus | None
|
||||
)
|
||||
|
||||
Создаёт новый объект введённого флага.
|
||||
|
||||
* ``name``: Имя введённого флага.
|
||||
* ``prefix``: Префикс флага (``-``, ``--``, ``---``). По умолчанию ``--``.
|
||||
* ``input_value``: Значение, переданное с флагом. Может быть `None`.
|
||||
* ``status``: Статус валидации из перечисления `ValidationStatus`.
|
||||
|
||||
.. warning ::
|
||||
Экземпляры этого класса не предназначены для прямого создания. Они содержатся в объекте :ref:`Response <root_api_response>`.
|
||||
|
||||
@@ -55,13 +35,7 @@ InputFlag
|
||||
.. py:attribute:: status
|
||||
:no-index:
|
||||
|
||||
Статус валидации флага: `ValidationStatus.VALID`, `ValidationStatus.INVALID` или `ValidationStatus.UNDEFINED`.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/input_flag/snippet1.py
|
||||
:linenos:
|
||||
:language: python
|
||||
Статус валидации флага: ``ValidationStatus.VALID``, ``ValidationStatus.INVALID`` или ``ValidationStatus.UNDEFINED``.
|
||||
|
||||
-----
|
||||
|
||||
@@ -81,14 +55,6 @@ string_entity
|
||||
|
||||
:return: Строковое представление флага
|
||||
|
||||
Это свойство объединяет префикс и имя в строку, представляющую флаг так, как он был введён в командной строке.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/input_flag/snippet2.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
Магические методы
|
||||
@@ -124,7 +90,7 @@ __repr__
|
||||
|
||||
Возвращает отладочное представление объекта.
|
||||
|
||||
:return: Строка в формате `InputFlag<prefix=..., name=..., value=..., status=...>`.
|
||||
:return: Строка в формате ``InputFlag<prefix=..., name=..., value=..., status=...>``.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -145,13 +111,6 @@ __eq__
|
||||
Сравнивает два введённых флага на равенство по имени.
|
||||
|
||||
:param other: Объект для сравнения.
|
||||
:return: `True`, если имена флагов совпадают, иначе `False`.
|
||||
:raises NotImplementedError: Если `other` не является экземпляром `InputFlag`.
|
||||
:return: **True**, если имена флагов совпадают, иначе **False**.
|
||||
|
||||
Два введённых флага считаются равными, если их имена совпадают.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/input_flag/snippet5.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
@@ -4,26 +4,23 @@
|
||||
PossibleValues
|
||||
==============
|
||||
|
||||
`PossibleValues` — это перечисление (`Enum`), которое определяет специальные режимы валидации для значений флагов. Его задача — предоставить стандартные константы для управления поведением флагов. `PossibleValues` используется в параметре `possible_values` класса `Flag`, чтобы указать, может ли флаг принимать значения и какие ограничения на них накладываются.
|
||||
``PossibleValues`` — это перечисление (``Enum``), которое определяет специальные режимы валидации для значений флагов. ``PossibleValues`` используется в параметре ``possible_values`` класса ``Flag``, чтобы указать, может ли флаг принимать значения и какие ограничения на них накладываются.
|
||||
|
||||
`PossibleValues` наследуется от `Enum` и содержит два основных значения: `NEITHER` (для флагов без значений) и `ALL` (для флагов, принимающих любые значения). Это перечисление используется вместе со списками строк и регулярными выражениями для создания гибкой системы валидации.
|
||||
``PossibleValues`` содержит два основных значения: ``NEITHER`` (для флагов, которые не могут принимать значения) и ``ALL`` (для флагов, принимающих любые значения). Это перечисление используется вместе со списками строк и регулярными выражениями для создания гибкой системы валидации.
|
||||
|
||||
.. note::
|
||||
Результат валидации доступен через атрибут `status` у экземпляра `InputFlag`. Подробнее см. :ref:`здесь <root_api_command_input_flag>`.
|
||||
Результат валидации доступен через атрибут ``status`` у экземпляра ``InputFlag``. Подробнее см. :ref:`здесь <root_api_command_input_flag>`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
Документация по :ref:`Flag <root_api_command_flag>` — класс флага, использующий `PossibleValues`.
|
||||
Документация по :ref:`Flag <root_api_command_flag>` — класс флага, использующий ``PossibleValues``.
|
||||
|
||||
Документация по :ref:`PredefinedFlags <root_api_command_flag_predefined_flags>` — готовые флаги с примерами использования `PossibleValues`.
|
||||
Документация по :ref:`ValidationStatus <root_api_command_validation_status>` — результат валидации ввёденного флага.
|
||||
|
||||
:ref:`Общая информация <root_flags>` о флагах и их использовании в приложении ``Argenta``
|
||||
|
||||
-----
|
||||
|
||||
Значения enum
|
||||
-------------
|
||||
|
||||
NEITHER
|
||||
~~~~~~~
|
||||
|
||||
@@ -65,10 +62,8 @@ ALL
|
||||
|
||||
**Примеры флагов с** ``ALL``:
|
||||
|
||||
* ``--output`` — путь к выходному файлу
|
||||
* ``--message`` — произвольное текстовое сообщение
|
||||
* ``--name`` — произвольное имя
|
||||
* ``--data`` — произвольные данные
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -78,35 +73,20 @@ ALL
|
||||
|
||||
-----
|
||||
|
||||
Использование в Flag
|
||||
---------------------
|
||||
|
||||
Параметр possible_values
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
`PossibleValues` используется как один из возможных типов для параметра `possible_values` при создании экземпляра `Flag`.
|
||||
``PossibleValues`` используется как один из возможных типов для параметра ``possible_values`` при создании экземпляра ``Flag``.
|
||||
|
||||
**Доступные типы для** `possible_values`:
|
||||
**Доступные типы для** ``possible_values``:
|
||||
|
||||
1. `PossibleValues.NEITHER`: флаг без значения.
|
||||
2. `PossibleValues.ALL`: флаг с любым значением (по умолчанию).
|
||||
3. `list[str]`: флаг с ограниченным набором значений.
|
||||
4. `Pattern[str]`: флаг со значением, проверяемым по регулярному выражению.
|
||||
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user