Requests Ratelimiter

0.9.3 · active · verified Mon Apr 13

Requests-Ratelimiter is a Python library that provides easy-to-use rate-limiting capabilities for the popular `requests` library. It acts as a wrapper around `pyrate-limiter`, implementing the leaky bucket algorithm to control the rate of HTTP requests. It is currently at version 0.9.3 and generally follows the release cadence of its underlying `pyrate-limiter` dependency, with updates typically driven by new features or fixes in the core rate-limiting logic.

Warnings

breaking Dropped support for Python 3.8 and 3.9 as of version 0.9.0, aligning with upstream `pyrate-limiter` requirements. Requires Python >=3.10.
Fix: Upgrade your Python environment to 3.10 or newer.
gotcha By default, each `LimiterSession` (and `LimiterAdapter`) operates independently, tracking rate limits only within its own instance. In multi-threaded environments, multiple processes, or web applications, this can lead to exceeding actual server-side rate limits.
Fix: For shared rate limits across threads, processes, or application restarts, use a persistent backend such as SQLite or Redis. This requires installing `requests-ratelimiter[sqlite]` or `requests-ratelimiter[redis]` and configuring the session with the appropriate backend.
gotcha When combining `requests-ratelimiter` with other `requests`-based libraries (e.g., `requests-cache`) using mixins, the inheritance order of mixin classes is crucial. If rate-limiting is applied *before* caching, cache hits will still count against your rate limit.
Fix: To ensure cache hits do not count towards the rate limit, the `CacheMixin` should typically be listed before `LimiterMixin` in the class inheritance. Example: `class CachedLimiterSession(CacheMixin, LimiterMixin, Session):`
breaking In earlier versions, `LimiterSession` accepted a `rates` argument to define rate limits. This was replaced by direct `per_second`, `per_minute`, etc., arguments, or by passing a `Limiter` object. Using the old `rates` argument will raise an `InvalidParams` exception from `pyrate_limiter`.
Fix: Instead of `LimiterSession(rates=[RequestRate(5, Duration.SECOND)])`, use `LimiterSession(per_second=5)` or `LimiterSession(limiter=Limiter(RequestRate(5, Duration.SECOND)))`.
gotcha The `per_host` parameter, available for both `LimiterSession` and `LimiterAdapter`, enables automatic tracking of rate limits separately for each host. If not enabled, a single rate limit applies across all hosts, which might not be the desired behavior for APIs with per-domain limits.
Fix: Set `per_host=True` when initializing `LimiterSession` or `LimiterAdapter` if you need distinct rate limits for different API endpoints/hosts: `session = LimiterSession(per_second=5, per_host=True)`.

Install

pip install requests-ratelimiter Install stable version

Imports

LimiterSession

from requests_ratelimiter import LimiterSession

LimiterAdapter

from requests_ratelimiter import LimiterAdapter

LimiterMixin

from requests_ratelimiter import LimiterMixin

RequestRate
```
from pyrate_limiter import RequestRate
```
RequestRate is part of pyrate-limiter, not requests-ratelimiter directly.
Duration
```
from pyrate_limiter import Duration
```
Duration is part of pyrate-limiter, not requests-ratelimiter directly.

Quickstart

This quickstart demonstrates how to use `LimiterSession` as a drop-in replacement for `requests.Session` to apply a simple rate limit. It also shows how to define more complex rate limits using `RequestRate` and `Duration` from the underlying `pyrate-limiter` library. The `httpbin.org/get` endpoint is used for demonstration purposes.

import os
from requests_ratelimiter import LimiterSession
from time import time

session = LimiterSession(per_second=5) # Limit to 5 requests per second
start = time()

for i in range(10):
    try:
        response = session.get('https://httpbin.org/get') # Or any other API endpoint
        response.raise_for_status()
        print(f'[t+{time()-start:.2f}] Sent request {i+1} (Status: {response.status_code})')
    except Exception as e:
        print(f'Request {i+1} failed: {e}')

# Example with custom rate using pyrate-limiter objects
from pyrate_limiter import RequestRate, Duration, Limiter
# Limit to 10 requests per minute
custom_limiter_session = LimiterSession(limiter=Limiter(RequestRate(10, Duration.MINUTE)))
start_custom = time()
for i in range(5):
    try:
        response = custom_limiter_session.get('https://httpbin.org/get')
        response.raise_for_status()
        print(f'[t+{time()-start_custom:.2f}] Sent custom-limited request {i+1} (Status: {response.status_code})')
    except Exception as e:
        print(f'Custom-limited request {i+1} failed: {e}')

view raw JSON →