.. _root_api_router:

Router
=============

Объект ``Router`` является фундаментальным строительным блоком для организации логики в приложении ``Argenta``. Его основная задача — группировать связанные команды и их обработчики. Каждый роутер представляет собой логический контейнер для определенного набора функциональности.

Например, в приложении для управления пользователями один роутер может отвечать за команды, связанные с аутентификацией (``login``, ``logout``), а другой — за операции с профилем (``profile show``, ``profile edit``).

-----

Инициализация
-------------

.. code-block:: python
   :linenos:

      __init__(self, title: str | None = None, 
               disable_redirect_stdout: bool = False) -> None

Создаёт новый экземпляр маршрутизатора.

* ``title`` : Необязательный заголовок для группы команд, которые регистрируются в этом роутере. Этот заголовок будет отображаться в списке доступных команд, помогая пользователю ориентироваться.
* ``disable_redirect_stdout`` : Если установлено в ``True``, отключает механизм перехвата стандартного вывода (``stdout``) для всех команд этого роутера. Это необходимо для команд, которые требуют интерактивного ввода от пользователя (например, с помощью ``input()``). При отключении перехвата вывода автоматически используется статическая разделительная линия. Подробнее в :ref:`соответствующем разделе <root_redirect_stdout>`

-----

Регистрация команд
------------------

Для регистрации новой команды и привязки к ней функции-обработчика используется декоратор ``@command``.

.. py:method:: @command(self, command: Command | str)

   Декоратор для регистрации функции как обработчика для указанной команды.

   :param command: Экземпляр класса ``argenta.command.Command``, описывающий триггер, флаги и описание команды. Также может быть просто строкой, которая будет являться триггером, в этом случае нет возможности настроить флаги, описание и всё остальное.

   **Пример использования:**

   .. literalinclude:: ../../code_snippets/router/snippet.py
      :linenos:
      :language: python
      
-----

Системный роутер по умолчанию
-----------------------------

``Argenta`` поставляется со встроенным системным роутером, который автоматически подключается к каждому приложению.

.. py:data:: system_router

   Предопределенный экземпляр ``Router``, который содержит базовые системные команды. По умолчанию в него включена команда выхода из приложения (обычно **exit**). Он имеет заголовок **"System points:"**, который можно переопределить в инстансе приложения -> ``App``.

   Вы можете добавлять свои команды в этот роутер, для этого импортируйте ``argenta.router.defaults.system_router`` и декорируйте необходимые хэндлеры его методом.

-----   
   
Возможные исключения
--------------------

При регистрации команд и флагов в ``Router`` могут возникнуть следующие исключения, сигнализирующие о некорректной конфигурации:

.. py:exception:: TriggerContainSpacesException

   Выбрасывается, если триггер команды, передаваемый в ``Command``, содержит пробелы. Триггеры команд должны быть одним словом.

   **Неправильно:** ``Command("add user")``
   **Правильно:** ``Command("add-user")``

.. py:exception:: RepeatedFlagNameException

   Возникает, если при определении флагов для одной команды были использованы дублирующиеся имена (как короткие, так и длинные). Каждое имя флага в рамках одной команды должно быть уникальным.

   **Пример, вызывающий исключение:**

   .. code-block:: python
      :linenos:

      Command("send", flags=[
          Flag("recipient"),
          Flag("recipient") 
      ])

.. py:exception:: RequiredArgumentNotPassedException

   Это исключение возникает, если какой-либо обработчик команды не ожидает обязательный аргумент, которым является объект ответа(``Response``).