BaseRateLimiter¶
- class telegram.ext.BaseRateLimiter[source]¶
Bases:
ABC
,typing.Generic
Abstract interface class that allows to rate limit the requests that python-telegram-bot sends to the Telegram Bot API. An implementation of this class must implement all abstract methods and properties.
This class is a
Generic
class and accepts one type variable that specifies the type of the argumentrate_limit_args
ofprocess_request()
and the methods ofExtBot
.Hint
Requests to
get_updates()
are never rate limited.See also
Added in version 20.0.
- abstract async initialize()[source]¶
Initialize resources used by this class. Must be implemented by a subclass.
- abstract async process_request(callback, args, kwargs, endpoint, data, rate_limit_args)[source]¶
Process a request. Must be implemented by a subclass.
This method must call
callback
and return the result of the call. When the callback is called is up to the implementation.Important
This method must only return once the result of
callback
is known!If a
RetryAfter
error is raised, this method may try to make a new request by calling the callback again.Warning
This method should not handle any other exception raised by
callback
!There are basically two different approaches how a rate limiter can be implemented:
React only if necessary. In this case, the
callback
is called without any precautions. If aRetryAfter
error is raised, processing requests is halted for theretry_after
and finally thecallback
is called again. This approach is often amendable for bots that don’t have a large user base and/or don’t send more messages than they get updates.Throttle all outgoing requests. In this case the implementation makes sure that the requests are spread out over a longer time interval in order to stay below the rate limits. This approach is often amendable for bots that have a large user base and/or send more messages than they get updates.
An implementation can use the information provided by
data
,endpoint
andrate_limit_args
to handle each request differently.Examples
It is usually desirable to call
telegram.Bot.answer_inline_query()
as quickly as possible, while delayingtelegram.Bot.send_message()
is acceptable.There are different rate limits for group chats and private chats.
When sending broadcast messages to a large number of users, these requests can typically be delayed for a longer time than messages that are direct replies to a user input.
- Parameters:
callback (Callable[…, coroutine]) – The coroutine function that must be called to make the request.
args (tuple[
object
]) – The positional arguments for thecallback
function.kwargs (dict[
str
,object
]) – The keyword arguments for thecallback
function.endpoint (
str
) – The endpoint that the request is made for, e.g."sendMessage"
.The parameters that were passed to the method of
ExtBot
. Anyapi_kwargs
are included in this and anydefaults
are already applied.Example
When calling:
await ext_bot.send_message( chat_id=1, text="Hello world!", api_kwargs={"custom": "arg"} )
then
data
will be:{"chat_id": 1, "text": "Hello world!", "custom": "arg"}
rate_limit_args (
None
|object
) – Custom arguments passed to the methods ofExtBot
. Can e.g. be used to specify the priority of the request.
- Returns:
The result of the callback function.
- Return type: