Hide navigation sidebar
Hide table of contents sidebar
PTB has undergone significant changes in v20. Please read the documentation carefully and also check out the transition guide in the wiki.
Back to top
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

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