mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
129 lines
5.0 KiB
ReStructuredText
129 lines
5.0 KiB
ReStructuredText
.. _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: set[str] = 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
|