.. _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