{"id":4806,"library":"token-bucket","title":"Token Bucket Rate Limiter","description":"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.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/falconry/token-bucket","tags":["rate-limiting","token-bucket","web","http","throttling"],"install":[{"cmd":"pip install token-bucket","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.5 or newer.","package":"python","optional":false}],"imports":[{"note":"The main class for creating and managing a token bucket.","symbol":"TokenBucket","correct":"from token_bucket import TokenBucket"}],"quickstart":{"code":"from token_bucket import TokenBucket\nimport time\n\n# Create a token bucket with a capacity of 10 tokens,\n# refilling at a rate of 2 tokens per second.\n# This allows for a burst of 10 requests, then 2 requests/second.\nbucket = TokenBucket(capacity=10, rate=2.0)\n\nprint(f\"Initial tokens: {bucket.tokens}\")\n\n# Try to consume 5 tokens\nif bucket.consume(5):\n    print(\"Consumed 5 tokens successfully.\")\nelse:\n    print(\"Failed to consume 5 tokens.\")\n\nprint(f\"Tokens after first consumption: {bucket.tokens}\")\n\n# Wait a bit for tokens to refill\ntime.sleep(2.0)\n\n# Try to consume 8 tokens (after 2 seconds, 4 tokens should have refilled)\nif bucket.consume(8):\n    print(\"Consumed 8 tokens successfully after refill.\")\nelse:\n    print(\"Failed to consume 8 tokens after refill.\")\n\nprint(f\"Tokens after second consumption: {bucket.tokens}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your project runs on Python 3.5+; if not, upgrade Python or pin `token-bucket` to version 0.2.x.","message":"Version 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`.","severity":"breaking","affected_versions":"<0.3.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All"},{"fix":"Upgrade to version 0.3.0 or later to ensure accurate rate limiting when `rate` is less than 1.0 token per second.","message":"Prior 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.","severity":"gotcha","affected_versions":"<0.3.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}