⏲️ Easy rate limiting for Python. Rate limiting async and thread-safe decorators and context managers that use a token bucket algorithm.
⏲️ Easy rate limiting for Python
- 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
- 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
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()
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
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
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
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
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
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
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: ...
Limiter are the same object:
assert limit is Limiter
- Python 3.10+ for versions
- Python 3.7+ for versions below
Install via PyPI
$ python3 -m pip install limiter
LICENSE. If you'd like to use this project with a different license, please get in touch.
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Hashes for limiter-0.3.1-py2.py3-none-any.whl