Distributed rate limiters
Project description
Redis rate limiters
A library for regulating traffic with respect to concurrency or time. It sync and async context managers for a semaphore- and a token bucket implementation.
The rate limiting implementations are distributed, using Redis, and leverages Lua scripts to greatly improve performance and simplify the code. Lua scripts run on the Redis server, and make each implementation fully atomic.
Both implementations are compatible for use with redis-clusters. We currently only support Python 3.11, but can add support for older versions if needed.
Installation
pip install redis-rate-limiters
Semaphore
The semaphore classes are useful when you have concurrency restrictions; e.g., say you're allowed 5 active requests at the time for a given API token.
Beware that the client will block until the Semaphore is acquired,
or the max_sleep
limit is exceeded. If the max_sleep
limit is exceeded, a MaxSleepExceededError
is raised.
Here's how you might use the async version:
import asyncio
from httpx import AsyncClient
from limiters import AsyncSemaphore
limiter = AsyncSemaphore(
name="foo", # name of the resource you are limiting traffic for
capacity=5, # allow 5 concurrent requests
max_sleep=30, # raise an error if it takes longer than 30 seconds to acquire the semaphore
expiry=30 # set expiry on the semaphore keys in Redis to prevent deadlocks
)
async def get_foo():
async with AsyncClient() as client:
async with limiter:
client.get(...)
async def main():
await asyncio.gather(
get_foo() for i in range(100)
)
and here is how you might use the sync version:
import requests
from limiters import SyncSemaphore
limiter = SyncSemaphore(
name="foo",
capacity=5,
max_sleep=30,
expiry=30
)
def main():
with limiter:
requests.get(...)
Token bucket
The TocketBucket
classes are useful if you're working with time-based
rate limits. Say, you are allowed 100 requests per minute, for a given API token.
If the max_sleep
limit is exceeded, a MaxSleepExceededError
is raised.
Here's how you might use the async version:
import asyncio
from httpx import AsyncClient
from limiters import AsyncTokenBucket
limiter = AsyncTokenBucket(
name="foo", # name of the resource you are limiting traffic for
capacity=5, # hold up to 5 tokens
refill_frequency=1, # add tokens every second
refill_amount=1, # add 1 token when refilling
max_sleep=30, # raise an error there are no free tokens for 30 seconds
)
async def get_foo():
async with AsyncClient() as client:
async with limiter:
client.get(...)
async def main():
await asyncio.gather(
get_foo() for i in range(100)
)
and here is how you might use the sync version:
import requests
from limiters import SyncTokenBucket
limiter = SyncTokenBucket(
name="foo",
capacity=5,
refill_frequency=1,
refill_amount=1,
max_sleep=30,
)
def main():
with limiter:
requests.get(...)
Using them as a decorator
As a decorator
We don't ship decorators in the package, but if you would like to limit the rate at which a whole function is run, you can create your own, like this:
from limiters import AsyncSemaphore
# Define a decorator function
def limit(name, capacity):
def middle(f):
async def inner(*args, **kwargs):
async with AsyncSemaphore(name=name, capacity=capacity):
return await f(*args, **kwargs)
return inner
return middle
# Then pass the relevant limiter arguments like this
@limit(name="foo", capacity=5)
def fetch_foo(id: UUID) -> Foo:
Contributing
Contributions are very welcome. Here's how to get started:
- Set up a Python 3.11+ venv, and
pip install poetry
- Install dependencies with
poetry install
- Run
pre-commit install
to set up pre-commit - Run
docker compose up
to run Redis (or run Redis for tests some other way) - Make your code changes, with tests
- Commit your changes and open a PR
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for redis_rate_limiters-0.1.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8aae0a7630f8f8eeb7b06702d991b45bf4f871f9896dd098bfd5f6fe2f8a2063 |
|
MD5 | 37eeb40b6ac48b4268a80899e523561b |
|
BLAKE2b-256 | 571d5b88bef16393aa5be0cc2bbe0a7de78e7d2a16439037d56e67adadf5b535 |
Hashes for redis_rate_limiters-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 18e2628e993e8083fc06454f4156390eacb0c9b9cb5a1ac2448dc350043be8a9 |
|
MD5 | 27cb0d176828975d2d7ad50debf0dc20 |
|
BLAKE2b-256 | d6d56968713f315a9591a9f7daab412060330646000009f83db4598d5e172656 |