{"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":"python","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":[{"wrong":"from token_bucket import TokenBucket","symbol":"Limiter","correct":"from token_bucket import Limiter"}],"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,"search_vec":"'0.3.0':52 'algorithm':19,64 'allow':38 'appear':55 'applic':26 'averag':46 'bucket':2,8,18,29,71 'burst':41 'consist':45 'control':40 'core':63 'current':49 'fast':13 'focus':59 'http':73 'implement':14 'improv':65 'infrequ':58 'intern':31 'limit':4,23,68 'maintain':43 'manag':28 'packag':9 'provid':10 'rate':3,22,47,67 'rate-limit':66 'releas':54 'requir':33 'separ':35 'stabil':61 'state':30 'suitabl':20 'thread':37 'throttl':74 'timer':36 'token':1,7,17,70 'token-bucket':6,69 'version':50 'web':25,72 'without':32","created_at":"2026-04-12T14:08:23.805480+00:00","updated_at":"2026-04-16T23:00:11.626741+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.4.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/falconry/token-bucket","docs":null,"changelog":null,"pypi":"https://pypi.org/project/token-bucket/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","web-framework","auth-security","observability","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-08-30","next_check":"2026-07-30","install_tag":null}}