aiolimiter

library1.2.1pypypi✓ verified 25d ago

aiolimiter is an asyncio-compatible rate limiter library for Python, implementing a leaky bucket algorithm. It allows controlling the rate at which concurrent operations can acquire permits, preventing resource exhaustion or API overuse. The current version is 1.2.1, and it maintains a steady release cadence for bug fixes and minor enhancements.

http-networking workflow

pip install aiolimiter

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · AIOLIMITER

aiolimiter

http-networkingpythonv1.2.1

Install

1.5s avg

Import

266ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.282s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.250s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AsyncLimiter

✓ from aiolimiter import AsyncLimiter

This quickstart demonstrates how to initialize `AsyncLimiter` and use it to control the rate of operations. It shows both the `async with` context manager for single-permit acquisition and the explicit `await limiter.acquire(count)` method for multiple permits.

import asyncio from aiolimiter import AsyncLimiter async def main(): # Initialize a limiter for 5 permits per second limiter = AsyncLimiter(5, 1) print("Attempting to acquire 3 permits...") async with limiter: await limiter.acquire(2) # Acquire 2 permits within the context manager print("Acquired 3 permits (1 from 'async with', 2 from 'acquire')!") print("Attempting to acquire 1 permit without context manager...") await limiter.acquire(1) print("Acquired 1 permit!") # Demonstrate waiting if limit is reached print("Acquiring 5 permits, might wait...") for _ in range(5): await limiter.acquire(1) print(f"Permit {_+1} acquired.") asyncio.run(main())

Debug

Known issues

gotchaWhen using `limiter.acquire(count)` outside of an `async with` block, it must be `await`ed, as it is a coroutine. Forgetting `await` will result in a runtime warning about an unawaited coroutine, or the acquisition not taking effect as intended.

fix

Always use `await limiter.acquire(count)` for explicit permit acquisition.

affects: >=1.0.0

gotchaThe `rate` and `period` parameters of `AsyncLimiter(rate, period)` can be confused. `rate` is the number of permits, and `period` is the duration in seconds over which those permits are available. E.g., `AsyncLimiter(10, 1)` means 10 permits per 1 second, not 1 permit per 10 seconds.

fix

Ensure `rate` is the quantity of permits and `period` is the time window. For 'X events per Y seconds', use `AsyncLimiter(X, Y)`.

affects: >=1.0.0

gotchaBy default, `acquire()` blocks until permits are available. If you want a non-blocking attempt, pass `block=False`. In this case, if permits are not immediately available, `acquire()` will raise a `LimitReached` exception instead of waiting.

fix

Wrap `await limiter.acquire(count, block=False)` in a `try...except LimitReached` block to handle cases where permits cannot be acquired instantly.

affects: >=1.0.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'aiolimiter'

The 'aiolimiter' package is not installed in the Python environment.

fix

pip install aiolimiter

ImportError: cannot import name 'AsyncLimiter'

The 'AsyncLimiter' class is not found in the 'aiolimiter' module, possibly due to an incorrect import statement.

fix

from aiolimiter import AsyncLimiter

TypeError: 'AsyncLimiter' object is not callable

Attempting to call an 'AsyncLimiter' instance directly instead of using it as an asynchronous context manager.

fix

async with limiter:
    # your code here

TypeError: wait_for() got an unexpected keyword argument 'loop'

This error occurs when using `aiolimiter` with Python 3.10 or newer, because the `loop` parameter was deprecated in Python 3.8 and removed in Python 3.10 for `asyncio.wait_for()`, which `aiolimiter` internally used with that parameter in older versions.

fix

Upgrade your `aiolimiter` library to a version compatible with Python 3.10+ (e.g., `aiolimiter` 1.1.0 or newer). The fix involves `pip install --upgrade aiolimiter`.

No module named 'aiolimiter.compat'

The `aiolimiter.compat` module was removed in `aiolimiter` version 1.1.1 as part of a simplification, breaking older codebases that explicitly imported from it.

fix

Refactor your code to remove imports from `aiolimiter.compat`. If your application relies on specific functionality from this module, you might need to find an alternative implementation or downgrade `aiolimiter` to version `1.1.0` or older (`pip install aiolimiter==1.1.0`).

Upgrade

Version history

1.2.1latest on PyPI · released Dec 8, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

70 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mjpieters/aiolimiter ↗

packagehttps://pypi.org/project/aiolimiter/ ↗

docshttp://aiolimiter.readthedocs.org/en/stable/ ↗