Flags#

Flags is a markers for handlers that can be used in middlewares or special utilities to make classification of the handlers.

Flags can be added to the handler via decorators, handlers registration or filters.

Via decorators#

For example mark handler with chat_action flag

from aiogram import flags

@flags.chat_action
async def my_handler(message: Message)

Or just for rate-limit or something else

from aiogram import flags

@flags.rate_limit(rate=2, key="something")
async def my_handler(message: Message)

Via handler registration method#

@router.message(..., flags={'chat_action': 'typing', 'rate_limit': {'rate': 5}})

Via filters#

class Command(Filter):
    ...

    def update_handler_flags(self, flags: Dict[str, Any]) -> None:
        commands = flags.setdefault("commands", [])
        commands.append(self)

Use in middlewares#

aiogram.dispatcher.flags.check_flags(handler: HandlerObject | Dict[str, Any], magic: MagicFilter) → Any[source]#

Check flags via magic filter

Parameters:

handler – handler object or data
magic – instance of the magic

Returns:

the result of magic filter check

aiogram.dispatcher.flags.extract_flags(handler: HandlerObject | Dict[str, Any]) → Dict[str, Any][source]#

Extract flags from handler or middleware context data

Parameters:: handler – handler object or data
Returns:: dictionary with all handler flags

aiogram.dispatcher.flags.get_flag(handler: HandlerObject | Dict[str, Any], name: str, *, default: Any | None = None) → Any[source]#

Get flag by name

Parameters:

handler – handler object or data
name – name of the flag
default – default value (None)

Returns:

value of the flag or default

Example in middlewares#

async def my_middleware(handler, event, data):
    typing = get_flag(data, "typing")  # Check that handler marked with `typing` flag
    if not typing:
        return await handler(event, data)

    async with ChatActionSender.typing(chat_id=event.chat.id):
        return await handler(event, data)

Use in utilities#

For example you can collect all registered commands with handler description and then it can be used for generating commands help

def collect_commands(router: Router) -> Generator[Tuple[Command, str], None, None]:
    for handler in router.message.handlers:
        if "commands" not in handler.flags:  # ignore all handler without commands
            continue
        # the Command filter adds the flag with list of commands attached to the handler
        for command in handler.flags["commands"]:
            yield command, handler.callback.__doc__ or ""
    # Recursively extract commands from nested routers
    for sub_router in router.sub_routers:
        yield from collect_commands(sub_router)