BaseRateLimiter

class telegram.ext.BaseRateLimiter

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 argument rate_limit_args of process_request() and the methods of ExtBot.

Hint

Requests to get_updates() are never rate limited.

Use In

telegram.ext.ApplicationBuilder.rate_limiter()

See also

Architecture Overview, Avoiding Flood Limits

Added in version 20.0.

abstract async initialize()

Initialize resources used by this class. Must be implemented by a subclass.

abstract async process_request(callback, args, kwargs, endpoint, data, rate_limit_args)

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:

1. React only if necessary. In this case, the callback is called without any precautions. If a RetryAfter error is raised, processing requests is halted for the retry_after and finally the callback 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.

2. 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 and rate_limit_args to handle each request differently.

Examples

• It is usually desirable to call telegram.Bot.answer_inline_query() as quickly as possible, while delaying telegram.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 the callback function.

• kwargs (Dict[str, object]) – The keyword arguments for the callback function.

• endpoint (str) – The endpoint that the request is made for, e.g. "sendMessage".

• data (Dict[str, object]) –

  The parameters that were passed to the method of ExtBot. Any api_kwargs are included in this and any defaults 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 of ExtBot. Can e.g. be used to specify the priority of the request.

Returns:

The result of the callback function.

Return type:

bool | Dict[str, object] | None

abstract async shutdown()

Stop & clear resources used by this class. Must be implemented by a subclass.