API Reference#

throttle_it.throttle(*windows: ~pyrate_limiter.abstracts.rate.Duration, limit_header_name: str, remaining_header_name: str, reset_header_name: str | None = None, identity: str | ~typing.Callable[[...], str] = 'global', parse_counts: ~typing.Callable[[str], ~typing.List[int]] = <function _split_ints>, parse_resets: ~typing.Callable[[str], ~typing.List[int]] | None = None, max_block: int | ~pyrate_limiter.abstracts.rate.Duration = Duration.MINUTE)#

Multi-window, server-synchronized rate limiter decorator.

This decorator uses pyrate-limiter to enforce API rate limits defined in response headers. It supports an arbitrary number of windows (e.g., per minute, per hour), automatically rebuilds the limiter from policy headers, and can synchronize with the server’s reset timestamp.

Parameters:

*windows (Duration) – One Duration object per rate-limit window. For example, Duration.MINUTE, Duration.HOUR corresponds to a two-window policy like “500 requests per minute” and “5000 requests per hour”.
limit_header_name (str) – Name of the HTTP header that provides the maximum allowed requests. The value must contain one or more integers matching the number of windows, e.g. "10/500" for two windows.
remaining_header_name (str) – Name of the HTTP header that provides the remaining quota. The format must match limit_header_name.
reset_header_name (str, optional) – Name of the HTTP header that provides the reset timestamp(s), by default None. If present, the value may be a single UNIX timestamp or multiple timestamps (one per window, same order as *windows). If any window reaches zero remaining requests, the decorator will sleep until the corresponding reset.
identity (str or callable, default="global") – Unique identifier for the limiter. If a callable, it must accept the decorated function’s arguments and return a string (e.g., per-API-key). This ensures separate rate limiting per identity.
parse_counts (callable, default=_split_ints) – Function to parse header values (limit/remaining) into a list of integers. Default parser supports values like "10/500" or "10,500".
parse_resets (callable, optional) – Function to parse the reset header value into a list of UNIX timestamps. If None, the same parser as parse_counts is used as a fallback.
max_block (int or Duration, default=Duration.MINUTE) – Maximum time the internal Limiter may block automatically when enforcing rate limits. If exceeded, a short sleep/retry loop is used.

Returns:

decorator – A function decorator that applies rate limiting to the wrapped function.

Return type:

callable

Notes

The decorated function must return a requests.Response object.
The limiter is updated dynamically from server headers after each response.
If headers are missing or malformed, the existing limiter configuration is retained.

Examples

Single-window usage (per-minute policy):

>>> import requests
>>> from throttle_it import Duration, throttle
>>>
>>>
>>> @throttle(
        Duration.MINUTE,
        limit_header_name="X-RateLimit-Limit",
        remaining_header_name="X-RateLimit-Remaining",
        reset_header_name="X-RateLimit-Reset",
    )
    def get(session, url):
        return session.get(url)
>>>
>>>
>>> with requests.Session() as s:
        r = get(s, "https://httpbin.org/get")

Multi-window usage (per-minute and per-hour policy):

>>> @throttle(
        Duration.MINUTE, Duration.HOUR,
        limit_header_name="X-RateLimit-Limit",
        remaining_header_name="X-RateLimit-Remaining",
        reset_header_name="X-RateLimit-Reset",
    )
>>> def fetch(session, url):
        return session.get(url)

API Reference#

This Page