A rate limiting library backed by DynamoDB using the token bucket algorithm.
Installation
pip install zae-limiter
# or
conda install -c conda-forge zae-limiter
Usage
from zae_limiter import Repository, RateLimiter, SyncRepository, SyncRateLimiter, Limit
# Auto-provisions infrastructure if needed
repo = await Repository.open()
limiter = RateLimiter(repository=repo)
# Sync
sync_repo = SyncRepository.open()
sync_limiter = SyncRateLimiter(repository=sync_repo)
# Define default limits (can be overridden per-entity)
default_limits = [
Limit.per_minute("rpm", 100),
Limit.per_minute("tpm", 10_000),
]
async with limiter.acquire(
entity_id="api-key-123",
resource="gpt-4",
limits=default_limits, # Multiple limits in a single atomic transaction
consume={"rpm": 1, "tpm": 500}, # Estimate tokens upfront
) as lease:
response = await call_llm()
# Reconcile actual usage (can go negative for post-hoc adjustment)
await lease.adjust(tpm=response.usage.total_tokens - 500)
# Tokens written to DynamoDB on enter | Rolled back on exception
# Hierarchical entities: create project with stored limits, then API key under it
await limiter.create_entity(entity_id="proj-1", name="Production")
await limiter.set_limits("proj-1", [Limit.per_minute("tpm", 100_000)]) # Project-level
await limiter.create_entity(entity_id="api-key-456", parent_id="proj-1", cascade=True)
# cascade is an entity property — acquire() auto-cascades to parent
with sync_limiter.acquire(
entity_id="api-key-456",
resource="gpt-4",
limits=default_limits,
consume={"rpm": 1, "tpm": 500},
):
call_api()
# Multi-tenant: each tenant gets an isolated namespace
tenant_repo = await Repository.open("tenant-alpha")
tenant_limiter = RateLimiter(repository=tenant_repo)
# Cleanup (removes all data)
await repo.delete_stack()
Documentation
| Guide | Description |
|---|---|
| Getting Started | Installation, first deployment |
| Basic Usage | Rate limiting patterns, error handling |
| Hierarchical Limits | Parent/child entities, cascade mode |
| LLM Integration | Token estimation and reconciliation |
| CLI Reference | Deploy, status, delete commands |
| Multi-Tenant Guide | Namespace isolation, per-tenant IAM |
| Production Guide | Security, monitoring, cost |
Production Deployment
The default deployment includes CloudWatch alarms and usage aggregation. For production, add data recovery and alert routing:
zae-limiter deploy --name my-app --region us-east-1 \
--pitr-recovery-days 7 \
--alarm-sns-topic arn:aws:sns:us-east-1:123456789012:alerts
For security best practices, multi-region considerations, and cost estimation, see the Production Guide.
Contributing
git clone https://github.com/zeroae/zae-limiter.git && cd zae-limiter
uv sync --all-extras
pytest
See the Contributing Guide for development setup, testing, and architecture details.
License
MIT
Metadata
Release files for zae-limiter 0.16.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| zae_limiter-0.16.0.tar.gz | 2.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| zae_limiter-0.16.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.1 MB
Release files / zae_limiter-0.16.0.tar.gz
| Download URL | zae_limiter-0.16.0.tar.gz |
|---|---|
| Size | 2.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4926d7e2bef6fc4e1a655c74a934a76a5b650bb456e47a6501494d26b84f9b14
|
|
BLAKE2b-256 checksum How to use checksums |
63479f365c9b26e41027e790ae19563a469dedf130bd03a33516665f6835ec8f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.
Transparency logRelease files / zae_limiter-0.16.0-py3-none-any.whl
| Download URL | zae_limiter-0.16.0-py3-none-any.whl |
|---|---|
| Size | 596.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
226126b0d246d517f8a85dd72ac8e9aff72cff83a133bffee3a1c25b0f0ab9b4
|
|
BLAKE2b-256 checksum How to use checksums |
68a621298e3f602f4a714e43d0c1fc21e343d231ecf60946533d395e2eb60da6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.
Transparency log
