⏲️ Easy rate limiting for Python. Rate limiting async and thread-safe decorators and context managers that use a token bucket algorithm.
Project description
⏲️ Easy rate limiting for Python
limiter
makes it easy to add rate limiting to Python projects, using a token bucket algorithm. limiter
can provide Python projects and scripts with:
- Rate limiting thread-safe decorators
- Rate limiting async decorators
- Rate limiting thread-safe context managers
- Rate limiting async context managers
Here are some features and benefits of using limiter
:
- Easily control burst and average request rates
- It is thread-safe, with no need for a timer thread
- It adds jitter to help with contention
- It has a simple API that takes advantage of Python's features, idioms and type hinting
Example
Here's an example of using a limiter as a decorator and context manager:
from aiohttp import ClientSession
from limiter import Limiter
limit_downloads = Limiter(rate=2, capacity=5, consume=2)
@limit_downloads
async def download_image(url: str) -> bytes:
async with ClientSession() as session, session.get(url) as response:
return await response.read()
async def download_page(url: str) -> str:
async with (
ClientSession() as session,
limit_downloads,
session.get(url) as response
):
return await response.text()
Usage
You can define limiters and use them dynamically across your project.
Note: If you're using Python version 3.9.x
or below, check out the documentation for version 0.2.0
of limiter
here.
Limiting blocks of code
limiter
can rate limit all Python callables, and limiters can be used as context managers.
You can define a limiter with a set refresh rate
and total token capacity
. You can set the amount of tokens to consume dynamically with consume
, and the bucket
parameter sets the bucket to consume tokens from:
from limiter import Limiter
REFRESH_RATE: int = 2
BURST_RATE: int = 3
MSG_BUCKET: str = 'messages'
limiter: Limiter = Limiter(rate=REFRESH_RATE, capacity=BURST_RATE)
limit_msgs: Limiter = limiter(bucket=MSG_BUCKET)
@limiter
def download_page(url: str) -> bytes:
...
@limiter(consume=2)
async def download_page(url: str) -> bytes:
...
def send_page(page: bytes):
with limiter(consume=1.5, bucket=MSG_BUCKET):
...
async def send_page(page: bytes):
async with limit_msgs:
...
@limit_msgs(consume=3)
def send_email(to: str):
...
async def send_email(to: str):
async with limiter(bucket=MSG_BUCKET):
...
In the example above, both limiter
and limit_msgs
share the same limiter. The only difference is that limit_msgs
will take tokens from the MSG_BUCKET
bucket by default.
assert limiter.limiter is limit_msgs.limiter
assert limiter.bucket != limit_msgs.bucket
assert limiter != limit_msgs
Creating new limiters
You can reuse existing limiters in your code, and you can create new limiters from the parameters of an existing limiter using the new()
method.
Or, you can define a new limiter entirely:
# you can reuse existing limiters
limit_downloads: Limiter = limiter(consume=2)
# you can use the settings from an existing limiter in a new limiter
limit_downloads: Limiter = limiter.new(consume=2)
# or you can simply define a new limiter
limit_downloads: Limiter = Limiter(REFRESH_RATE, BURST_RATE, consume=2)
@limit_downloads
def download_page(url: str) -> bytes:
...
@limit_downloads
async def download_page(url: str) -> bytes:
...
def download_image(url: str) -> bytes:
with limit_downloads:
...
async def download_image(url: str) -> bytes:
async with limit_downloads:
...
Let's look at the difference between reusing an existing limiter, and creating new limiters with the new()
method:
limiter_a: Limiter = limiter(consume=2)
limiter_b: Limiter = limiter.new(consume=2)
limiter_c: Limiter = Limiter(REFRESH_RATE, BURST_RATE, consume=2)
assert limiter_a != limiter
assert limiter_a != limiter_b != limiter_c
assert limiter_a != limiter_b
assert limiter_a.limiter is limiter.limiter
assert limiter_a.limiter is not limiter_b.limiter
assert limiter_a.attrs == limiter_b.attrs == limiter_c.attrs
The only things that are equivalent between the three new limiters above are the limiters' attributes, like the rate
, capacity
, and consume
attributes.
Creating anonymous, or single-use, limiters
You don't have to assign Limiter
objects to variables. Anonymous limiters don't share a token bucket like named limiters can. They work well when you don't have a reason to share a limiter between two or more blocks of code, and when a limiter has a single or independent purpose.
limiter
, after version v0.3.0
, ships with a limit
type alias for Limiter
:
from limiter import limit
@limit(capacity=2, consume=2)
async def send_message():
...
async def upload_image():
async with limit(capacity=3) as limiter:
...
The above is equivalent to the below:
from limiter import Limiter
@Limiter(capacity=2, consume=2)
async def send_message():
...
async def upload_image():
async with Limiter(capacity=3) as limiter:
...
Both limit
and Limiter
are the same object:
assert limit is Limiter
Installation
Requirements
- Python 3.10+ for versions
0.3.0
and up - Python 3.7+ for versions below
0.3.0
Install via PyPI
$ python3 -m pip install limiter
License
See LICENSE
. If you'd like to use this project with a different license, please get in touch.
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 limiter-0.3.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4851837b2e5c236b1c07f2d61c2ce09612a41549b8229c799862fed3ffc1d07f |
|
MD5 | 5f51b211933f2f9eb7370d6749d5dd65 |
|
BLAKE2b-256 | bf4fb1f9045d95183ce250ce91e9ae09c382cb40adf9a31d5a1e01fce0d1d648 |