Команды с описаниями и аргументами

Бот в основном состоит из команд. Raito добавляет три небольших декоратора из пространства имён rt, которые делают команды самоописательными и типобезопасными.

Описания

rt.description добавляет к команде понятное описание. Raito собирает их и регистрирует в Telegram, поэтому они сами появляются в меню команд клиента.

from aiogram import Router, filters, types
from raito import rt

router = Router(name="ping")


@router.message(filters.Command("ping"))
@rt.description("Check that the bot is alive")
async def ping(message: types.Message) -> None:
    await message.answer("pong 🏓")

Чтобы опубликовать меню, вызовите raito.Raito.register_commands() один раз при запуске, обычно из хендлера lifespan:

await raito.register_commands(bot)

Скрытие команды

Некоторые команды служебные. Пометьте их rt.hidden (без скобок), и они останутся рабочими хендлерами, но не попадут в меню слэш-команд:

@router.message(filters.Command("debug"))
@rt.hidden
async def debug(message: types.Message) -> None:
    ...

Типизированные аргументы

Для команды вроде /add 2 3 rt.params берёт позиционные аргументы, приводит их к указанным типам и передаёт в хендлер по именам:

@router.message(filters.Command("add"))
@rt.description("Add two numbers")
@rt.params(a=int, b=int)
async def add(message: types.Message, a: int, b: int) -> None:
    await message.answer(f"{a} + {b} = {a + b}")

Поддерживаются типы int, float, str и bool (bool принимает true/yes/on/1/ok/+). Если аргумента нет или он не приводится, Raito вместо вызова хендлера отвечает автоматически собранной подсказкой, поэтому /add two 3 покажет справку, а не трейсбек.

Совет

Аргументы позиционные и делятся по пробелам в порядке объявления. @rt.params(name=str) для /hello John Doe даст name="John", так что для многословного ввода используйте один аргумент в конце или разбирайте message.text сами.

Важно

Позиционные аргументы команд подходят для инструментов разработчика и тестов, но не для обычных пользователей. Вам удобно набрать /add 2 3, а вот просить рядового пользователя передавать аргументы в правильном порядке уже неудобно. Чтобы собирать данные у настоящих пользователей, спрашивайте по одному через сцену (на базе FSM) или через диалог (wait_for).

Теперь у вас есть команды с описаниями и типами. Дальше ограничим, кто может их вызывать: Доступ по ролям.