AIORateLimiter

class telegram.ext.AIORateLimiter(overall_max_rate=<FloodLimit.MESSAGES_PER_SECOND>, overall_time_period=1, group_max_rate=<FloodLimit.MESSAGES_PER_MINUTE_PER_GROUP>, group_time_period=60, max_retries=0)[source]

Bases: telegram.ext.BaseRateLimiter

Implementation of BaseRateLimiter using the library aiolimiter.

Important

If you want to use this class, you must install PTB with the optional requirement rate-limiter, i.e.

pip install "python-telegram-bot[rate-limiter]"

The rate limiting is applied by combining two levels of throttling and process_request() roughly boils down to:

async with group_limiter(group_id):
    async with overall_limiter:
        await callback(*args, **kwargs)

Here, group_id is determined by checking if there is a chat_id parameter in the data. The overall_limiter is applied only if a chat_id argument is present at all.

Attention

  • Some bot methods accept a chat_id parameter in form of a @username for supergroups and channels. As we can’t know which @username corresponds to which integer chat_id, these will be treated as different groups, which may lead to exceeding the rate limit.

  • As channels can’t be differentiated from supergroups by the @username or integer chat_id, this also applies the group related rate limits to channels.

  • A RetryAfter exception will halt all requests for retry_after + 0.1 seconds. This may be stricter than necessary in some cases, e.g. the bot may hit a rate limit in one group but might still be allowed to send messages in another group or with allow_paid_broadcast set to True.

Tip

With Bot API 7.1 (PTB v27.1), Telegram introduced the parameter allow_paid_broadcast. This allows bots to send up to 1000 messages per second by paying a fee in Telegram Stars.

Changed in version 21.11: This class automatically takes the allow_paid_broadcast parameter into account and throttles the requests accordingly.

Note

This class is to be understood as minimal effort reference implementation. If you would like to handle rate limiting in a more sophisticated, fine-tuned way, we welcome you to implement your own subclass of BaseRateLimiter. Feel free to check out the source code of this class for inspiration.

Added in version 20.0.

Parameters:
async initialize()[source]

Does nothing.

async process_request(callback, args, kwargs, endpoint, data, rate_limit_args)[source]

Processes a request by applying rate limiting.

See telegram.ext.BaseRateLimiter.process_request() for detailed information on the arguments.

Parameters:

rate_limit_args (None | int) – If set, specifies the maximum number of retries to be made in case of a RetryAfter exception. Defaults to AIORateLimiter.max_retries.

async shutdown()[source]

Does nothing.