mirror of
https://github.com/aiogram/aiogram.git
synced 2025-12-12 02:03:04 +00:00
7776cf9cf6
* Update API, added some new features * Fixed unknown chat_action value * Separate events from dispatcher messages * Disabled cache for I18n LazyProxy * Rework events isolation * Added chat member status changed filter, update Bot API 5.7, other small changes * Improve exceptions in chat member status filter * Fixed tests, covered flags and events isolation modules * Try to fix flake8 unused type ignore * Fixed linter error * Cover chat member updated filter * Cover chat action sender * Added docs for chat action util * Try to fix tests for python <= 3.9 * Fixed headers * Added docs for flags functionality * Added docs for chat_member_updated filter * Added change notes * Update dependencies and fix mypy checks * Bump version
89 lines
2.4 KiB
ReStructuredText
89 lines
2.4 KiB
ReStructuredText
=====
|
|
Flags
|
|
=====
|
|
|
|
Flags is a markers for handlers that can be used in `middlewares <#use-in-middlewares>`_
|
|
or special `utilities <#use-in-utilities>`_ to make classification of the handlers.
|
|
|
|
Flags can be added to the handler via `decorators <#via-decorators>`_,
|
|
`handlers registration <#via-handler-registration-method>`_ or
|
|
`filters <via-filters>`_.
|
|
|
|
Via decorators
|
|
==============
|
|
|
|
For example mark handler with `chat_action` flag
|
|
|
|
.. code-block:: python
|
|
|
|
from aiogram import flags
|
|
|
|
@flags.chat_action
|
|
async def my_handler(message: Message)
|
|
|
|
Or just for rate-limit or something else
|
|
|
|
.. code-block:: python
|
|
|
|
from aiogram import flags
|
|
|
|
@flags.rate_limit(rate=2, key="something")
|
|
async def my_handler(message: Message)
|
|
|
|
Via handler registration method
|
|
===============================
|
|
|
|
.. code-block:: python
|
|
|
|
@router.message(..., flags={'chat_action': 'typing', 'rate_limit': {'rate': 5}})
|
|
|
|
Via filters
|
|
===========
|
|
|
|
.. code-block:: python
|
|
|
|
class Command(BaseFilter):
|
|
...
|
|
|
|
def update_handler_flags(self, flags: Dict[str, Any]) -> None:
|
|
commands = flags.setdefault("commands", [])
|
|
commands.append(self)
|
|
|
|
|
|
|
|
Use in middlewares
|
|
==================
|
|
|
|
.. automodule:: aiogram.dispatcher.flags.getter
|
|
:members:
|
|
|
|
Example in middlewares
|
|
----------------------
|
|
|
|
.. code-block:: python
|
|
|
|
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
|
|
|
|
.. code-block:: python
|
|
|
|
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)
|