{"id":4400,"library":"throttled-py","title":"Throttled-py","description":"Throttled-py is a high-performance Python rate limiting library, currently at version 3.2.0, providing various algorithms like Fixed Window, Sliding Window, Token Bucket, Leaky Bucket, and GCRA. It supports both in-memory and Redis storage backends, and offers synchronous and asynchronous APIs. The project maintains an active release cadence, with updates typically occurring every 1-3 months.","status":"active","version":"3.2.0","language":"en","source_language":"en","source_url":"https://github.com/ZhuoZhuoCrayon/throttled-py","tags":["rate limiting","throttling","async","redis","in-memory","performance","decorator","context manager"],"install":[{"cmd":"pip install throttled-py","lang":"bash","label":"Core library"},{"cmd":"pip install \"throttled-py[redis]\"","lang":"bash","label":"With Redis support"},{"cmd":"pip install \"throttled-py[all]\"","lang":"bash","label":"With all optional dependencies"}],"dependencies":[{"reason":"Requires Python 3.10 or newer since v3.0.0.","package":"python","optional":false},{"reason":"Required for Redis-based storage backends for distributed rate limiting. Installed via the `[redis]` extra.","package":"redis","optional":true}],"imports":[{"note":"Use for synchronous applications.","symbol":"Throttled","correct":"from throttled import Throttled"},{"note":"Enum for specifying rate limiting algorithms.","symbol":"RateLimiterType","correct":"from throttled import RateLimiterType"},{"note":"For asynchronous (async/await) applications, explicitly import from `throttled.asyncio`. Using the sync import in an async context will lead to errors.","wrong":"from throttled import Throttled","symbol":"Throttled (async)","correct":"from throttled.asyncio import Throttled"},{"note":"Used for configuring a Redis storage backend.","symbol":"RedisStore","correct":"from throttled.store import RedisStore"}],"quickstart":{"code":"import os\nimport time\nfrom throttled import Throttled, RateLimiterType\n\n# Configure Redis connection via URL for example, falling back to localhost\nREDIS_URL = os.environ.get('REDIS_URL', 'redis://localhost:6379/0')\n\n# Example with RedisStore\n# Note: Requires 'throttled-py[redis]' to be installed.\n# If Redis is not available, this example will use In-MemoryStore as a fallback implicitly\n# or explicitly set store=MemoryStore() for local testing without redis.\n\n# Create a throttler instance with Token Bucket algorithm, 1 request per second, burst 1.\n# Key is dynamically generated from the function name.\n@Throttled(using=RateLimiterType.TOKEN_BUCKET.value, quota=\"1/s burst 1\", store_url=REDIS_URL)\ndef process_request(request_id):\n    print(f\"Processing request {request_id} at {time.time()}\")\n    return f\"Processed {request_id}\"\n\nprint(\"Starting throttled requests...\")\nfor i in range(5):\n    try:\n        result = process_request(i)\n        print(f\"Success: {result}\")\n    except Exception as e:\n        print(f\"Failed to process request {i}: {e}\")\n    time.sleep(0.5) # Simulate some interval between calls\n\nprint(\"\\nTrying with async Throttled (requires `throttled-py[redis]` and a running Redis for distributed behavior):\")\n\nimport asyncio\nfrom throttled.asyncio import Throttled as AsyncThrottled\nfrom throttled.asyncio import RateLimiterType as AsyncRateLimiterType\n\n@AsyncThrottled(using=AsyncRateLimiterType.SLIDING_WINDOW.value, quota=\"2/m\", store_url=REDIS_URL)\nasync def async_process_request(request_id):\n    print(f\"Async processing request {request_id} at {time.time()}\")\n    await asyncio.sleep(0.1) # Simulate async work\n    return f\"Async processed {request_id}\"\n\nasync def main():\n    for i in range(5):\n        try:\n            result = await async_process_request(i)\n            print(f\"Async Success: {result}\")\n        except Exception as e:\n            print(f\"Async Failed to process request {i}: {e}\")\n        await asyncio.sleep(1) # Simulate some interval\n\nif __name__ == '__main__':\n    # Note: If redis-py is not installed or Redis is not running, \n    # the store_url might implicitly fallback to in-memory behavior \n    # or raise connection errors. Ensure Redis is accessible for full distributed functionality.\n    try:\n        asyncio.run(main())\n    except ImportError:\n        print(\"\\nSkipping async example: throttled-py[redis] might not be installed or redis-py is missing.\")\n    except Exception as e:\n        print(f\"\\nError during async execution: {e}\")\n","lang":"python","description":"This quickstart demonstrates both synchronous and asynchronous usage of `throttled-py` as a decorator. It uses the `TOKEN_BUCKET` algorithm for the synchronous example and `SLIDING_WINDOW` for the asynchronous one, with an optional Redis backend configured via `REDIS_URL` for distributed rate limiting. Ensure `throttled-py[redis]` is installed and a Redis instance is accessible for distributed storage."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer, or install a version of `throttled-py` less than 3.0.0 (e.g., `pip install 'throttled-py<3.0.0'`).","message":"Version 3.0.0 dropped support for Python 3.8 and 3.9. The minimum required Python version is now 3.10.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"For `async` functions, always import `Throttled` (and other related symbols) from `throttled.asyncio`. For synchronous functions, import from `throttled`.","message":"Throttled-py provides separate modules for synchronous (`throttled`) and asynchronous (`throttled.asyncio`) APIs. Using the wrong import for your application type (e.g., `from throttled import Throttled` in an `async` function) will lead to runtime errors.","severity":"gotcha","affected_versions":">=2.1.0"},{"fix":"Install with `pip install \"throttled-py[redis]\"` and pass `store_url='redis://...'` or an instance of `RedisStore` to your `Throttled` decorator or function call.","message":"By default, `Throttled` uses an in-memory store. For distributed rate limiting across multiple application instances, you *must* explicitly configure and install `RedisStore` via `pip install \"throttled-py[redis]\"` and pass a `store_url` or `store` instance.","severity":"gotcha","affected_versions":"All"},{"fix":"Refer to the project's contribution guidelines for the new build and development setup using Hatch and uv.","message":"Version 3.0.0 migrated the build system from Poetry to Hatch and uv. While this primarily affects contributors, users who relied on the Poetry-based project structure for certain tasks might need to adjust their workflows.","severity":"breaking","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}