Registry / http-networking / token-bucket

token-bucket

JSON →
library0.4.0pypypi✓ verified 23d ago

The `token-bucket` package provides a very fast implementation of the token bucket algorithm, suitable for rate limiting in web applications. It manages bucket state internally without requiring a separate timer thread, allowing for controlled bursts while maintaining a consistent average rate. The current version is 0.3.0, and releases appear to be infrequent, focusing on stability and core algorithm improvements.

pip install token-bucket
INSTALL
IMPORT
SIG · TOKEN-BUCKET
T
token-bucket
http-networkingpythonv0.4.0
Install
1.6s avg
Import
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.4.0 · 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.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage

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

Limiter
from token_bucket import Limiter
from token_bucket import TokenBucket

Initialize a `TokenBucket` with a `capacity` and `rate` (tokens per second). Use the `consume()` method to attempt to acquire tokens. It returns `True` if tokens are successfully acquired, `False` otherwise. The bucket automatically replenishes tokens based on the elapsed time since the last operation, up to its capacity.

from token_bucket import TokenBucket import time # Create a token bucket with a capacity of 10 tokens, # refilling at a rate of 2 tokens per second. # This allows for a burst of 10 requests, then 2 requests/second. bucket = TokenBucket(capacity=10, rate=2.0) print(f"Initial tokens: {bucket.tokens}") # Try to consume 5 tokens if bucket.consume(5): print("Consumed 5 tokens successfully.") else: print("Failed to consume 5 tokens.") print(f"Tokens after first consumption: {bucket.tokens}") # Wait a bit for tokens to refill time.sleep(2.0) # Try to consume 8 tokens (after 2 seconds, 4 tokens should have refilled) if bucket.consume(8): print("Consumed 8 tokens successfully after refill.") else: print("Failed to consume 8 tokens after refill.") print(f"Tokens after second consumption: {bucket.tokens}")
Debug
Known issues
breakingVersion 0.3.0 dropped support for Python 2.x and now requires Python 3.5 or newer. Users on older Python versions must upgrade their environment or stick to `token-bucket<0.3.0`.
fix
Ensure your project runs on Python 3.5+; if not, upgrade Python or pin `token-bucket` to version 0.2.x.
affects: <0.3.0
gotchaThe `token-bucket` library primarily provides an in-memory, single-process token bucket implementation. For distributed rate limiting across multiple application instances (e.g., in a microservices architecture), you will need to implement a shared state mechanism (e.g., using Redis) or use a different library designed for distributed rate limiting.
fix
For distributed systems, consider integrating with an external store like Redis or exploring libraries like `token-throttler` or `bucketflow` that offer distributed backend support.
affects: All
gotchaPrior to version 0.3.0, rates less than 1.0 token per second might not have been handled correctly. Version 0.3.0 explicitly added support for fractional rates, allowing for finer-grained control over low-frequency limits.
fix
Upgrade to version 0.3.0 or later to ensure accurate rate limiting when `rate` is less than 1.0 token per second.
affects: <0.3.0
Upgrade
Version history
0.4.0latest on PyPI · released Jun 12, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.5 or newer.
Agent activity
29 hits · last 30 days
node
26
OpenAI (training)
1
Resources
token-bucket — pip install token-bucket · libregistry