Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# 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.