asgi-ratelimit

0.10.0 verified Fri May 01 auth: no python

ASGI middleware for rate limiting requests using a token bucket algorithm. Current version 0.10.0, requires Python >=3.6,<4.0. Release cadence is irregular.

pip install asgi-ratelimit

Common errors

error TypeError: unhashable type: 'list' ↓

cause auth_func returns a list/tuple instead of a hashable string.

fix

Change auth_func to return a string, e.g., lambda scope: scope['client'][0]

error ModuleNotFoundError: No module named 'asgi_ratelimit.backends' ↓

cause In v0.9+ backends may have moved to top-level package.

fix

Import backend from the main module: from asgi_ratelimit import RedisBackend

Warnings

gotcha The `auth_func` must return a hashable string (e.g., IP, user ID). Returning a tuple or non-hashable will cause a runtime TypeError. ↓

fix Ensure auth_func returns a string, e.g., lambda scope: scope['client'][0].

gotcha Rate limiter backends (Redis, memory) must be configured explicitly; default is in-memory dictionary (not shared across processes). ↓

fix For distributed apps, pass a Redis backend: from asgi_ratelimit import RedisBackend; RateLimitMiddleware(..., backend=RedisBackend('redis://localhost')).

deprecated The `backend` parameter in v0.9+ changed; the old direct class import `from asgi_ratelimit.backends import RedisBackend` may break if using newer structuring. ↓

fix Use correct top-level import: `from asgi_ratelimit import RedisBackend` or check version for exact path.

Imports

RateLimitMiddleware
```
from asgi_ratelimit import RateLimitMiddleware
```
Correct import path for the middleware class.
RateLimit
```
from asgi_ratelimit import RateLimit
```
Decorator or helper for rate limiting.

Quickstart

Basic rate limiting middleware wrapping an ASGI app.

from asgi_ratelimit import RateLimitMiddleware, RateLimit

app = RateLimitMiddleware(
    some_asgi_app,
    auth_func=lambda scope: scope["client"][0],
    limiter=RateLimit(10, 60)  # 10 requests per 60 seconds
)