mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
kolo
ce7e24b924
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.
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: 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
|