Registry / http-networking / throttled-py

throttled-py

JSON →
library3.4.1pypypi✓ verified 25d ago

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.

pip install throttled-py
INSTALL
IMPORT
SIG · THROTTLED-PY
T
throttled-py
http-networkingpythonv3.4.1
Install
1.7s avg
Import
357ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.4.1 · 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.915 runs
installs and imports cleanly · install 0.0s · import 0.378s · 22.4MB
glibc
py 3.103.915 runs
installs and imports cleanly · install 1.7s · import 0.337s · 23MB
20MB installed
● package 20MB
Code
Verified usage

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

Throttled
from throttled import Throttled
Use for synchronous applications.
RateLimiterType
from throttled import RateLimiterType
Enum for specifying rate limiting algorithms.
Throttled (async)
from throttled.asyncio import Throttled
from throttled import Throttled
For asynchronous (async/await) applications, explicitly import from `throttled.asyncio`. Using the sync import in an async context will lead to errors.
RedisStore
from throttled.store import RedisStore
Used for configuring a Redis storage backend.

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.

import os import time from throttled import Throttled, RateLimiterType # Configure Redis connection via URL for example, falling back to localhost REDIS_URL = os.environ.get('REDIS_URL', 'redis://localhost:6379/0') # Example with RedisStore # Note: Requires 'throttled-py[redis]' to be installed. # If Redis is not available, this example will use In-MemoryStore as a fallback implicitly # or explicitly set store=MemoryStore() for local testing without redis. # Create a throttler instance with Token Bucket algorithm, 1 request per second, burst 1. # Key is dynamically generated from the function name. @Throttled(using=RateLimiterType.TOKEN_BUCKET.value, quota="1/s burst 1", store_url=REDIS_URL) def process_request(request_id): print(f"Processing request {request_id} at {time.time()}") return f"Processed {request_id}" print("Starting throttled requests...") for i in range(5): try: result = process_request(i) print(f"Success: {result}") except Exception as e: print(f"Failed to process request {i}: {e}") time.sleep(0.5) # Simulate some interval between calls print("\nTrying with async Throttled (requires `throttled-py[redis]` and a running Redis for distributed behavior):") import asyncio from throttled.asyncio import Throttled as AsyncThrottled from throttled.asyncio import RateLimiterType as AsyncRateLimiterType @AsyncThrottled(using=AsyncRateLimiterType.SLIDING_WINDOW.value, quota="2/m", store_url=REDIS_URL) async def async_process_request(request_id): print(f"Async processing request {request_id} at {time.time()}") await asyncio.sleep(0.1) # Simulate async work return f"Async processed {request_id}" async def main(): for i in range(5): try: result = await async_process_request(i) print(f"Async Success: {result}") except Exception as e: print(f"Async Failed to process request {i}: {e}") await asyncio.sleep(1) # Simulate some interval if __name__ == '__main__': # Note: If redis-py is not installed or Redis is not running, # the store_url might implicitly fallback to in-memory behavior # or raise connection errors. Ensure Redis is accessible for full distributed functionality. try: asyncio.run(main()) except ImportError: print("\nSkipping async example: throttled-py[redis] might not be installed or redis-py is missing.") except Exception as e: print(f"\nError during async execution: {e}")
Debug
Known issues
breakingVersion 3.0.0 dropped support for Python 3.8 and 3.9. The minimum required Python version is now 3.10.
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'`).
affects: >=3.0.0
gotchaThrottled-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.
fix
For `async` functions, always import `Throttled` (and other related symbols) from `throttled.asyncio`. For synchronous functions, import from `throttled`.
affects: >=2.1.0
gotchaBy 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.
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.
affects: All
breakingVersion 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.
fix
Refer to the project's contribution guidelines for the new build and development setup using Hatch and uv.
affects: >=3.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'throttled'
This error occurs when the 'throttled' package is not installed in the Python environment.
fix
Install the package using pip: 'pip install throttled-py'.
ImportError: cannot import name 'Throttled' from 'throttled'
This error occurs when the 'throttled' package is installed but the import statement is incorrect.
fix
Ensure the import statement is correct: 'from throttled import Throttled'.
AttributeError: module 'throttled' has no attribute 'Throttled'
This error occurs when the 'throttled' package is installed but the import statement is incorrect.
fix
Ensure the import statement is correct: 'from throttled import Throttled'.
TypeError: Throttled() missing 1 required positional argument: 'key'
This error occurs when instantiating the 'Throttled' class without providing the required 'key' argument.
fix
Provide the 'key' argument when creating an instance: 'throttle = Throttled(key="/api/v1/resource")'.
LimitedError: Rate limit exceeded: remaining=0, reset_after=60, retry_after=60
This error occurs when the rate limit has been exceeded for a given key.
fix
Adjust the rate limit settings or implement a retry mechanism after the specified 'retry_after' duration.
Upgrade
Version history
3.4.1latest on PyPI · released Aug 1, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer since v3.0.0.
redisoptionalRequired for Redis-based storage backends for distributed rate limiting. Installed via the `[redis]` extra.
Agent activity
19 hits · last 30 days
node
16
Meta
1
OpenAI (training)
1
Resources
throttled-py — pip install throttled-py · libregistry