mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 18:15:28 +03:00
148 lines
6.8 KiB
ReStructuredText
148 lines
6.8 KiB
ReStructuredText
.. _root_api_command_index:
|
|
|
|
Command
|
|
=======
|
|
|
|
Объект ``Command`` представляет собой основную единицу функциональности в приложении ``Argenta``. Каждая команда определяет конкретное действие, которое пользователь может выполнить, введя соответствующий триггер. Команды регистрируются в роутерах и образуют интерфейс взаимодействия с приложением.
|
|
|
|
``Command`` инкапсулирует всю необходимую информацию о команде: её триггер (ключевое слово для вызова), описание, набор флагов для настройки поведения и список псевдонимов для альтернативных способов вызова.
|
|
|
|
-----
|
|
|
|
Инициализация
|
|
-------------
|
|
|
|
.. code-block:: python
|
|
:linenos:
|
|
|
|
__init__(self, trigger: str, *,
|
|
description: str | None = None,
|
|
flags: Flag | Flags = DEFAULT_WITHOUT_FLAGS,
|
|
aliases: list[str] | None = None) -> None
|
|
|
|
Создает новую команду для регистрации в роутере.
|
|
|
|
* ``trigger`` : Строковый триггер команды, который пользователь должен ввести для её вызова. Это основной идентификатор команды в системе.
|
|
|
|
* ``description`` : Необязательное описание команды, объясняющее её назначение. Если не указано, используется значение по умолчанию ``"Command without description"``. Отображается в справке и списке доступных команд.
|
|
|
|
* ``flags`` : Набор флагов команды для настройки её поведения. Может быть одиночным объектом ``Flag`` или коллекцией ``Flags``. По умолчанию команда создается без флагов.
|
|
|
|
* ``aliases`` : Список строковых синонимов для основного триггера. Позволяет вызывать команду альтернативными способами. По умолчанию список пуст.
|
|
|
|
**Атрибуты:**
|
|
|
|
.. py:attribute:: trigger
|
|
|
|
Основной триггер команды в виде строки. Используется для идентификации команды при парсинге пользовательского ввода.
|
|
|
|
.. py:attribute:: description
|
|
|
|
Текстовое описание команды. Если не было передано при инициализации, содержит значение ``"Command without 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:
|
|
|
|
-----
|
|
|
|
Работа с псевдонимами
|
|
---------------------
|
|
|
|
Псевдонимы позволяют вызывать один и тот же хэндлер разными триггерами, сохраняя при этом флаги команды и описание.
|
|
|
|
**Пример с псевдонимами:**
|
|
|
|
.. code-block:: python
|
|
: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
|
|
|
|
shutdown
|
|
poweroff
|
|
halt
|
|
stop
|
|
|
|
Все эти варианты выполнят одну и ту же функцию ``handle_shutdown``.
|
|
|
|
-----
|
|
|
|
.. _root_api_command_input_command:
|
|
|
|
InputCommand
|
|
------------
|
|
|
|
Класс ``InputCommand`` представляет собой распаршенную команду, введенную пользователем. Это внутренний класс, который создается автоматически при парсинге пользовательского ввода. Непосредственная работа с данным классом возможна при создании кастомного хэндлера для обработки неизвестных команд.
|
|
|
|
.. seealso ::
|
|
Подробнее про кастомные хэндлеры обработки исключений ввода :ref:`тут <root_error_handling>`
|
|
|
|
Создает экземпляр распарсенной команды.
|
|
|
|
:param trigger: Триггер команды, извлеченный из пользовательского ввода
|
|
:param input_flags: Флаги, переданные пользователем при вызове команды
|
|
|
|
**Атрибуты:**
|
|
|
|
.. py:attribute:: trigger
|
|
:no-index:
|
|
|
|
Строковый триггер команды, введенный пользователем.
|
|
|
|
.. py:attribute:: input_flags
|
|
|
|
Объект ``InputFlags``, содержащий все флаги, переданные с командой. Автоматически конвертируется из одиночного ``InputFlag`` в коллекцию.
|
|
|
|
.. toctree ::
|
|
:hidden:
|
|
|
|
flag
|
|
possible_values
|
|
input_flag
|
|
validation_status
|
|
flags
|
|
input_flags
|