# Redis rate limiters
A library which regulates traffic, with respect to concurrency or time.
It implements sync and async context managers for a [semaphore](#semaphore)- and a [token bucket](#token-bucket)-implementation.
The rate limiters are distributed, using Redis, and leverages Lua scripts to
improve performance and simplify the code. Lua scripts
run on Redis, and make each implementation fully atomic, while
also reducing the number of round-trips required.
Use is supported for standalone redis instances, and clusters.
We currently only support Python 3.11, but can add support for older versions if needed.
## Installation
```
pip install redis-rate-limiters
```
## Usage
### 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:
```python
import asyncio
from httpx import AsyncClient
from redis.asyncio import Redis
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
connection=Redis.from_url("redis://localhost:6379"),
)
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:
```python
import requests
from redis import Redis
from limiters import SyncSemaphore
limiter = SyncSemaphore(
name="foo",
capacity=5,
max_sleep=30,
expiry=30,
connection=Redis.from_url("redis://localhost:6379"),
)
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:
```python
import asyncio
from httpx import AsyncClient
from redis.asyncio import Redis
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
connection=Redis.from_url("redis://localhost:6379"),
)
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:
```python
import requests
from redis import Redis
from limiters import SyncTokenBucket
limiter = SyncTokenBucket(
name="foo",
capacity=5,
refill_frequency=1,
refill_amount=1,
max_sleep=30,
connection=Redis.from_url("redis://localhost:6379"),
)
def main():
with limiter:
requests.get(...)
```
### Using them 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:
```python
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
- Install [just](https://just.systems/man/en/) and run `just setup`
If you prefer not to install just, just take a look at the justfile and
run the commands yourself.
- Make your code changes, with tests
- Commit your changes and open a PR
## Publishing a new version
To publish a new version:
- Update the package version in the `pyproject.toml`
- Open [Github releases](https://github.com/otovo/redis-rate-limiters/releases)
- Press "Draft a new release"
- Set a tag matching the new version (for example, `v0.4.2`)
- Set the title matching the tag
- Add some release notes, explaining what has changed
- Publish
Once the release is published, our [publish workflow](https://github.com/otovo/redis-rate-limiters/blob/main/.github/workflows/publish.yaml) should be triggered
to push the new version to PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/otovo/redis-rate-limiters",
"name": "redis-rate-limiters",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11,<4.0",
"maintainer_email": "",
"keywords": "async,sync,rate,limiting,limiters",
"author": "Sondre Lilleb\u00f8 Gundersen",
"author_email": "sondrelg@live.no",
"download_url": "https://files.pythonhosted.org/packages/48/6d/b09b86e3ff938a944acda72cbaaf50c4a25ed1decffcb4ab7a485dedf84d/redis_rate_limiters-0.4.3.tar.gz",
"platform": null,
"description": "# Redis rate limiters\n\nA library which regulates traffic, with respect to concurrency or time.\nIt implements sync and async context managers for a [semaphore](#semaphore)- and a [token bucket](#token-bucket)-implementation.\n\nThe rate limiters are distributed, using Redis, and leverages Lua scripts to\nimprove performance and simplify the code. Lua scripts\nrun on Redis, and make each implementation fully atomic, while\nalso reducing the number of round-trips required.\n\nUse is supported for standalone redis instances, and clusters.\nWe currently only support Python 3.11, but can add support for older versions if needed.\n\n## Installation\n\n```\npip install redis-rate-limiters\n```\n\n## Usage\n\n### Semaphore\n\nThe semaphore classes are useful when you have concurrency restrictions;\ne.g., say you're allowed 5 active requests at the time for a given API token.\n\nBeware that the client will block until the Semaphore is acquired,\nor the `max_sleep` limit is exceeded. If the `max_sleep` limit is exceeded, a `MaxSleepExceededError` is raised.\n\nHere's how you might use the async version:\n\n```python\nimport asyncio\n\nfrom httpx import AsyncClient\nfrom redis.asyncio import Redis\n\nfrom limiters import AsyncSemaphore\n\n\nlimiter = AsyncSemaphore(\n name=\"foo\", # name of the resource you are limiting traffic for\n capacity=5, # allow 5 concurrent requests\n max_sleep=30, # raise an error if it takes longer than 30 seconds to acquire the semaphore\n expiry=30, # set expiry on the semaphore keys in Redis to prevent deadlocks\n connection=Redis.from_url(\"redis://localhost:6379\"),\n)\n\nasync def get_foo():\n async with AsyncClient() as client:\n async with limiter:\n client.get(...)\n\n\nasync def main():\n await asyncio.gather(\n get_foo() for i in range(100)\n )\n```\n\nand here is how you might use the sync version:\n\n```python\nimport requests\nfrom redis import Redis\n\nfrom limiters import SyncSemaphore\n\n\nlimiter = SyncSemaphore(\n name=\"foo\",\n capacity=5,\n max_sleep=30,\n expiry=30,\n connection=Redis.from_url(\"redis://localhost:6379\"),\n)\n\ndef main():\n with limiter:\n requests.get(...)\n```\n\n### Token bucket\n\nThe `TocketBucket` classes are useful if you're working with time-based\nrate limits. Say, you are allowed 100 requests per minute, for a given API token.\n\nIf the `max_sleep` limit is exceeded, a `MaxSleepExceededError` is raised.\n\nHere's how you might use the async version:\n\n```python\nimport asyncio\n\nfrom httpx import AsyncClient\nfrom redis.asyncio import Redis\n\nfrom limiters import AsyncTokenBucket\n\n\nlimiter = AsyncTokenBucket(\n name=\"foo\", # name of the resource you are limiting traffic for\n capacity=5, # hold up to 5 tokens\n refill_frequency=1, # add tokens every second\n refill_amount=1, # add 1 token when refilling\n max_sleep=30, # raise an error there are no free tokens for 30 seconds\n connection=Redis.from_url(\"redis://localhost:6379\"),\n)\n\nasync def get_foo():\n async with AsyncClient() as client:\n async with limiter:\n client.get(...)\n\nasync def main():\n await asyncio.gather(\n get_foo() for i in range(100)\n )\n```\n\nand here is how you might use the sync version:\n\n```python\nimport requests\nfrom redis import Redis\n\nfrom limiters import SyncTokenBucket\n\n\nlimiter = SyncTokenBucket(\n name=\"foo\",\n capacity=5,\n refill_frequency=1,\n refill_amount=1,\n max_sleep=30,\n connection=Redis.from_url(\"redis://localhost:6379\"),\n)\n\ndef main():\n with limiter:\n requests.get(...)\n```\n\n### Using them as a decorator\n\nWe don't ship decorators in the package, but if you would\nlike to limit the rate at which a whole function is run,\nyou can create your own, like this:\n\n```python\nfrom limiters import AsyncSemaphore\n\n\n# Define a decorator function\ndef limit(name, capacity):\n def middle(f):\n async def inner(*args, **kwargs):\n async with AsyncSemaphore(name=name, capacity=capacity):\n return await f(*args, **kwargs)\n return inner\n return middle\n\n\n# Then pass the relevant limiter arguments like this\n@limit(name=\"foo\", capacity=5)\ndef fetch_foo(id: UUID) -> Foo:\n```\n\n## Contributing\n\nContributions are very welcome. Here's how to get started:\n\n- Set up a Python 3.11+ venv, and `pip install poetry`\n- Install dependencies with `poetry install`\n- Run `pre-commit install` to set up pre-commit\n- Install [just](https://just.systems/man/en/) and run `just setup`\n If you prefer not to install just, just take a look at the justfile and\n run the commands yourself.\n- Make your code changes, with tests\n- Commit your changes and open a PR\n\n## Publishing a new version\n\nTo publish a new version:\n\n- Update the package version in the `pyproject.toml`\n- Open [Github releases](https://github.com/otovo/redis-rate-limiters/releases)\n- Press \"Draft a new release\"\n- Set a tag matching the new version (for example, `v0.4.2`)\n- Set the title matching the tag\n- Add some release notes, explaining what has changed\n- Publish\n\nOnce the release is published, our [publish workflow](https://github.com/otovo/redis-rate-limiters/blob/main/.github/workflows/publish.yaml) should be triggered\nto push the new version to PyPI.\n",
"bugtrack_url": null,
"license": "BSD-4-Clause",
"summary": "Distributed rate limiters",
"version": "0.4.3",
"project_urls": {
"Homepage": "https://github.com/otovo/redis-rate-limiters",
"Repository": "https://github.com/otovo/redis-rate-limiters"
},
"split_keywords": [
"async",
"sync",
"rate",
"limiting",
"limiters"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c92a0c66d005f9c7ffa37f8020acfd8e51be3a24ef58a6996a7bdd55f6debf51",
"md5": "b5f7fa3120e435a81ef7980f64720efd",
"sha256": "7f923fecbb9dce27cf9ec619ddbce92807b08b39346b679adae3d53d11d63838"
},
"downloads": -1,
"filename": "redis_rate_limiters-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b5f7fa3120e435a81ef7980f64720efd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11,<4.0",
"size": 10065,
"upload_time": "2024-01-24T13:50:35",
"upload_time_iso_8601": "2024-01-24T13:50:35.786251Z",
"url": "https://files.pythonhosted.org/packages/c9/2a/0c66d005f9c7ffa37f8020acfd8e51be3a24ef58a6996a7bdd55f6debf51/redis_rate_limiters-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "486db09b86e3ff938a944acda72cbaaf50c4a25ed1decffcb4ab7a485dedf84d",
"md5": "62fbb1a984c7a4f1fd6a144550735cfd",
"sha256": "d10343cfc2a25b99d8d87171c2f53eba3563a933fb93f8728fdb70a5e1d24195"
},
"downloads": -1,
"filename": "redis_rate_limiters-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "62fbb1a984c7a4f1fd6a144550735cfd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11,<4.0",
"size": 10030,
"upload_time": "2024-01-24T13:50:37",
"upload_time_iso_8601": "2024-01-24T13:50:37.301205Z",
"url": "https://files.pythonhosted.org/packages/48/6d/b09b86e3ff938a944acda72cbaaf50c4a25ed1decffcb4ab7a485dedf84d/redis_rate_limiters-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-24 13:50:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "otovo",
"github_project": "redis-rate-limiters",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "redis-rate-limiters"
}
JSON
