Skip to main content

⏲️ 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:

Here are some features and benefits of using limiter:


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)

async def download_image(url: str) -> bytes:
  async with ClientSession() as session, session.get(url) as response:
    return await

async def download_page(url: str) -> str:
  async with (
    ClientSession() as session,
    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 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

BURST_RATE: int = 3
MSG_BUCKET: str = 'messages'

limiter: Limiter = Limiter(rate=REFRESH_RATE, capacity=BURST_RATE)
limit_msgs: Limiter = limiter(bucket=MSG_BUCKET)

def download_page(url: str) -> bytes:

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:

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 =

# or you can simply define a new limiter
limit_downloads: Limiter = Limiter(REFRESH_RATE, BURST_RATE, consume=2)

def download_page(url: str) -> bytes:

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_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.



Install via PyPI

$ python3 -m pip install limiter


See LICENSE. If you'd like to use this project with a different license, please get in touch.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

limiter-0.3.0.tar.gz (18.2 kB view hashes)

Uploaded Source

Built Distribution

limiter-0.3.0-py2.py3-none-any.whl (18.2 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page