mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
90 lines
5.8 KiB
ReStructuredText
90 lines
5.8 KiB
ReStructuredText
.. _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``).
|
|
|