Rate Limiter¶
Zero-dependency multi-algorithm rate limiter with sync + async support — stdlib only, Python 3.10+.
Replaces:
limits,pyrate-limiter,aiolimiter,limiter
Overview¶
The ratelimit module provides four in-memory rate-limiting algorithms behind a common RateLimiter protocol, plus convenience wrappers (decorator, context manager, string quota notation).
| File | Description | Dependencies |
|---|---|---|
ratelimit.py |
4 algorithms + convenience API | None (stdlib only) |
Algorithms¶
| Algorithm | Class | Best for |
|---|---|---|
| Token Bucket | TokenBucketLimiter |
Per-IP throttling, smooth rate with burst tolerance |
| Fixed Window | FixedWindowLimiter |
Simple counter-per-window, lowest overhead |
| Sliding Window Counter | SlidingWindowLimiter |
Accurate without boundary-burst artifacts |
| GCRA | GCRALimiter |
Constant-rate shaping via single TAT timestamp |
Features¶
- 4 algorithms behind a common
RateLimiterProtocol - Sync + async —
acquire()/peek()andaacquire()/apeek()on all classes - Decorator + context manager —
@ratelimit("10/s")orwith ratelimit("5/m") - String quota notation — parse
"100/s","10 per minute burst 20" - Thread-safe wrapper —
ThreadSafeLimiterwith per-key locking - Wait-and-retry — block up to
timeoutseconds for quota - Injectable clock — deterministic testing via
clockparameter - Amortized eviction — stale keys cleaned every 128 acquire calls
How to Use in Your Project¶
Quick Start¶
Direct usage¶
from ratelimit import TokenBucketLimiter
limiter = TokenBucketLimiter(rate=10.0, capacity=20)
result = limiter.acquire("client-ip")
if not result.allowed:
return 429, {"Retry-After": str(result.retry_after)}
Factory with string quota¶
from ratelimit import create_limiter
limiter = create_limiter("sliding_window", "100/m burst 200")
result = limiter.acquire("user-123")
Decorator¶
from ratelimit import ratelimit
@ratelimit("10/s", algorithm="token_bucket")
def handle_request():
...
@ratelimit("5/s")
async def async_handler():
...
Context manager¶
from ratelimit import ratelimit
with ratelimit("5/m", key="user-1") as result:
print(f"remaining: {result.remaining}")
async with ratelimit("5/m", key="user-1") as result:
await do_work()
Wait-and-retry¶
from ratelimit import ratelimit
# Block up to 5 seconds waiting for quota
with ratelimit("10/s", timeout=5.0):
do_work()
Thread safety¶
from ratelimit import TokenBucketLimiter, ThreadSafeLimiter
limiter = ThreadSafeLimiter(TokenBucketLimiter(rate=100.0, capacity=100))
# Safe to call from multiple threads — per-key locking
result = limiter.acquire("client-ip")
Async API¶
from ratelimit import TokenBucketLimiter
limiter = TokenBucketLimiter(rate=10.0, capacity=20)
result = await limiter.aacquire("client-ip")
state = await limiter.apeek("client-ip")
RateLimitResult¶
Every acquire() / peek() call returns a RateLimitResult:
| Field | Type | Description |
|---|---|---|
allowed |
bool |
Whether the request is permitted |
limit |
int \| float |
Total quota (capacity or window limit) |
remaining |
int \| float |
Remaining quota (may be float for fractional tokens) |
reset_at |
float |
Monotonic timestamp when quota replenishes |
retry_after |
float \| None |
Seconds to wait before retrying (None when allowed) |
Quota String Format¶
| Pattern | Example |
|---|---|
N/unit |
"100/s", "10/m", "5/h", "1/d" |
N per unit |
"10 per minute" |
N/unit burst B |
"100/s burst 200" |
N per unit burst B |
"10 per minute burst 20" |
Supported units: s/sec/second, m/min/minute, h/hr/hour, d/day (plurals accepted).
Performance¶
All four algorithms run under 1μs per acquire() call, 6-7x faster than the limits library on comparable algorithms, and within 5% of token-bucket's C-extension on FixedWindow.
See full benchmark results for detailed comparisons, multi-threaded throughput, and optimization history.