token-throttler

What it is and what it does

Token throttler is a rate-limiting library that enforces request quotas using a token bucket algorithm. It allows you to define buckets with a maximum token count and replenishment time, then consume tokens before allowing actions to proceed. The library supports both blocking (synchronous) and non-blocking (asynchronous) modes, and can be used either manually by calling consume() or via decorators applied to functions and FastAPI routes.

The package is designed to be extensible: it ships with in-memory (RuntimeStorage) and Redis storage backends, and you can implement custom storage by extending the base storage classes. Configuration can be set globally or per-instance, with options to enable thread locking for race-condition safety and fail-safe behavior for missing identifiers. It officially supports Python 3.8 and later.

Use it for:

• Protect API endpoints from abuse by limiting requests per user or IP address using FastAPI middleware
• Rate-limit background job processing by throttling function calls across multiple workers with Redis storage
• Enforce quota limits on internal service calls to prevent cascading failures or resource exhaustion
• Implement sliding-window rate limits on database queries or external API calls within a single application
• Decorate expensive functions to prevent them from being called more than N times per time window

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Token throttler implements rate limiting using a token bucket algorithm, supporting both synchronous and asynchronous code with pluggable storage backends and decorator-based or manual usage patterns.

Yes, if you need straightforward token-bucket rate limiting and can accept the project's dormant maintenance status. The library is simple to integrate, has no runtime dependencies, and works with modern Python versions. However, if you require active maintenance, frequent updates, or are building mission-critical systems, consider whether the 860-day gap since the last release poses a risk for your use case.

Install

token-throttler on PyPI

pip install token-throttler

uv add token-throttler

poetry add token-throttler

Installing token-throttler

Before you install

Low install friction with no runtime dependencies. Marked dormant (860 days since last release), though classifiers indicate Production/Stable status and support for Python 3.8 through 3.12.

License in practice

MIT license (permissive) places no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart

from token_throttler import TokenThrottler, TokenBucket
from token_throttler.storage import RuntimeStorage

throttler = TokenThrottler(1, RuntimeStorage())
throttler.add_bucket("endpoint", TokenBucket(10, 10))
if throttler.consume("endpoint"):
    print("Request allowed")
else:
    print(f"Retry in {throttler.wait_time('endpoint')} seconds")

Verify before relying

• Whether dormant status (no recent commits visible) affects reliability for new deployments or bug fixes
• Performance characteristics under high concurrency or with large numbers of buckets
• Whether Redis storage extra is actively maintained given the project's maintenance status

Package facts

Evidence: token_throttler-1.5.1-py3-none-any.whl

Tags

More Libraries packages