Router

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

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

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

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

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

  • title: Необязательный заголовок для группы команд. Отображается в списке доступных команд, помогая пользователю ориентироваться.

  • disable_redirect_stdout: Если True, отключает перехват stdout для всех команд этого роутера. Это необходимо для интерактивных команд (например, с input()). При отключении перехвата автоматически используется статическая разделительная линия. Подробнее см. в разделе Переопределение стандартного вывода.

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

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

@command(self, command: Command | str)

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

Параметры:

command – Экземпляр Command, описывающий триггер, флаги и описание команды. Может быть строкой, которая станет триггером (без возможности настройки флагов и описания).

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

1from argenta import Command, Response, Router
2
3user_router = Router(title="User Management")
4
5@user_router.command(Command("add-user", description="Adds a new user"))
6def add_user_handler(response: Response):
7    print("User added successfully!")

Системный роутер

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

system_router

Предопределённый экземпляр Router с базовыми системными командами (по умолчанию — команда выхода). Имеет заголовок «System points:», который можно переопределить в App.

Вы можете добавлять свои команды в этот роутер. Для этого используйте атрибут .system_router у созданного экхемпляра Orchestrator и используйте его декоратор @command.

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

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

exception TriggerContainSpacesException

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

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

Правильно: Command("add-user")

exception RepeatedFlagNameException

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

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

1Command("send", flags=[
2    Flag("recipient"),
3    Flag("recipient")  # Duplicate!
4])
exception RequiredArgumentNotPassedException

Возникает, если обработчик команды не принимает обязательный аргумент Response.

exception RepeatedTriggerNameException

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

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

1router = Router()
2
3@router.command(Command("start"))
4def start_handler(response: Response) -> None:
5    pass
6
7@router.command(Command("start"))  # Duplicate trigger!
8def another_start_handler(response: Response) -> None:
9    pass
exception RepeatedAliasNameException

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

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

1router = Router()
2
3@router.command(Command("start", aliases={"s", "run"}))
4def start_handler(response: Response) -> None:
5    pass
6
7@router.command(Command("begin", aliases={"s"}))  # Duplicate alias "s"!
8def begin_handler(response: Response) -> None:
9    pass