### Run a local Redis server with Docker Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/getting-started.md Starts a Redis 7 container for local development. Use this to test the limiter. ```bash docker run --rm -p 6379:6379 redis:7 ``` -------------------------------- ### Clone and set up the development environment with uv Source: https://github.com/bagowix/ratelimit-io/blob/main/CONTRIBUTING.md Clones the repository, installs dependencies, and sets up git hooks. Requires uv to be installed. ```bash git clone https://github.com/bagowix/ratelimit-io cd ratelimit-io uv sync # creates the venv and installs the dev dependencies uv run prek install # one-time: installs the git hooks ``` -------------------------------- ### Development Commands Source: https://github.com/bagowix/ratelimit-io/blob/main/AGENTS.md Common commands for setup, testing, linting, type checking, and documentation builds. `uv sync` installs the virtual environment and dev dependencies; `uv run prek install` sets up git hooks once. Tests run on fakeredis by default, but setting `RATELIMIT_IO_TEST_REDIS_URL` adds concurrency tests against a real Redis server. `mypy` runs bare because its file list is defined in `[tool.mypy] files`. ```bash uv sync # venv + dev dependencies uv run prek install # one-time: git hooks uv run pytest --cov # tests on fakeredis, 100% coverage RATELIMIT_IO_TEST_REDIS_URL=redis://localhost:6379/0 uv run pytest # real server, adds the concurrency tests uv run pytest tests/test_limiter.py::test__acquire_sync__over_limit__raises_with_retry_after -n 0 uv run ruff format --check && uv run ruff check uv run mypy && uv run pyright && uv run pyrefly check uv run zizmor .github/ uv run zensical build --strict && uv run python scripts/mirror_markdown.py uv run python scripts/build_llms_full.py # after editing any page in docs/ ``` -------------------------------- ### Build Retry-After header from retry_after Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/getting-started.md Converts the float retry_after to whole seconds for the Retry-After header, rounding up with math.ceil. ```python import math headers = {'Retry-After': str(math.ceil(error.retry_after))} ``` -------------------------------- ### Async RateLimiter with acquire() Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/getting-started.md Creates an async limiter with a limit of 5 requests per second. acquire() raises RateLimitExceededError when the limit is exceeded; the error provides retry_after seconds. ```python from redis.asyncio import Redis from ratelimit_io import Limit, RateLimiter, RateLimitExceededError limiter = RateLimiter(Redis(), limit=Limit(5, seconds=1)) async def handle(user_id: int) -> None: try: await limiter.acquire(f'user:{user_id}') except RateLimitExceededError as error: print(f'slow down, retry in {error.retry_after:.1f}s') return ... # the request is within the limit ``` -------------------------------- ### Run tests against a real Redis or Valkey server Source: https://github.com/bagowix/ratelimit-io/blob/main/CONTRIBUTING.md Starts a Redis 7 (or Valkey 8) container and runs the full test suite against it. The tests never flush the server; each test uses its own key prefix and deletes its keys afterwards. ```bash docker run --rm -p 6379:6379 redis:7 # or valkey/valkey:8 RATELIMIT_IO_TEST_REDIS_URL=redis://localhost:6379/0 uv run pytest ``` -------------------------------- ### Create a RateLimiter with a sliding window algorithm Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt Use this to instantiate a rate limiter with the sliding window algorithm. The example shows importing Algorithm, Limit, and RateLimiter, and passing a client and a limit of 100 requests per minute. The algorithm is set explicitly to Algorithm.SLIDING_WINDOW. ```python from ratelimit_io import Algorithm, Limit, RateLimiter limiter = RateLimiter(client, limit=Limit(100, minutes=1), algorithm=Algorithm.SLIDING_WINDOW) ``` -------------------------------- ### VERSION / __version__ Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/reference.md The installed version of the library, as a string. ```APIDOC ## VERSION / __version__ ### Description The installed version, as a string. ``` -------------------------------- ### Sync RateLimiter with acquire_sync() Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/getting-started.md Uses a sync redis.Redis client and acquire_sync() for synchronous code. The client type determines which method works; the other raises TypeError. ```python from redis import Redis from ratelimit_io import Limit, RateLimiter sync_limiter = RateLimiter(Redis(), limit=Limit(5, seconds=1)) sync_limiter.acquire_sync('user:42') ``` -------------------------------- ### Install ratelimit-io with pip Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/index.md Install the package via pip. The only dependency is redis-py 5.0.1 or newer; any Redis 5.0+ or Valkey server works, Sentinel included. Redis Cluster is not supported yet. ```bash pip install ratelimit-io ``` -------------------------------- ### Waiting for a slot with max_wait Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/getting-started.md Sets max_wait=30 so acquire() sleeps until a slot frees up, up to 30 seconds. The limiter reserves the next free slot in the same round trip and never polls Redis. ```python github = RateLimiter(Redis(), limit=Limit(5000, hours=1), key='github', max_wait=30) async def fetch_repo(name: str) -> None: await github.acquire() # sleeps until a slot frees up, up to 30 s ... ``` -------------------------------- ### Decorator usage with and without key Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/getting-started.md The limiter can be used as a decorator. Without a key, the bucket is named after the function's module and qualified name. With a Key template, each argument fills the bucket key. ```python from ratelimit_io import Key @limiter async def export_report() -> bytes: ... @limiter(key=Key('user:{user_id}'), limit=Limit(10, minutes=1)) async def search(user_id: int, query: str) -> list[str]: ... ``` -------------------------------- ### FastAPI dependency and exception handler for rate limiting Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/frameworks.md Use this FastAPI setup to apply a rate limit to every route that declares the dependency and convert refusals into 429 responses with a Retry-After header. The exception handler rounds retry_after up to whole seconds. When request.client is None, the dependency raises HTTPException 500; key on the address your proxy forwards instead of using a placeholder like 'unknown'. ```python import math from fastapi import Depends, FastAPI, HTTPException, Request from fastapi.responses import JSONResponse from redis.asyncio import Redis from ratelimit_io import Limit, RateLimiter, RateLimitExceededError app = FastAPI() limiter = RateLimiter(Redis(), limit=Limit(100, minutes=1)) @app.exception_handler(RateLimitExceededError) async def too_many_requests(request: Request, error: RateLimitExceededError) -> JSONResponse: return JSONResponse( {'detail': 'Too many requests'}, status_code=429, headers={'Retry-After': str(math.ceil(error.retry_after))}, ) async def rate_limit(request: Request) -> None: if request.client is None: raise HTTPException(500, 'no client address to rate limit by') await limiter.acquire(f'{request.url.path}:{request.client.host}') @app.get('/items', dependencies=[Depends(rate_limit)]) async def list_items() -> list[str]: return [] ``` -------------------------------- ### Set max_wait on limiter and override per call or per decorated function Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/guides/waiting.md Shows how to set max_wait on the RateLimiter and override it per acquire() call or per decorated function. The example waits up to 5 seconds, fails immediately with max_wait=0, and allows 30 seconds for the decorated function. ```python limiter = RateLimiter(client, limit=Limit(10, seconds=1), max_wait=5) await limiter.acquire('reports') # waits up to 5 s await limiter.acquire('reports', max_wait=0) # fails at once @limiter(max_wait=30) async def nightly_export() -> None: ... ``` -------------------------------- ### Create a RateLimiter with a specific algorithm Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/guides/algorithms.md Shows how to instantiate a RateLimiter with a chosen algorithm, here SLIDING_WINDOW. The algorithm can also be read from configuration by converting a string: Algorithm(settings.rate_limit_algorithm) accepts 'fixed_window', 'sliding_window', and 'gcra'. FIXED_WINDOW is the default. ```python from ratelimit_io import Algorithm, Limit, RateLimiter limiter = RateLimiter(client, limit=Limit(100, minutes=1), algorithm=Algorithm.SLIDING_WINDOW) ``` -------------------------------- ### Key template Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt A template for generating bucket keys from function arguments. Uses str.format syntax with argument names. ```APIDOC ## Key(template) ### Description A template for generating bucket keys from function arguments. Uses str.format syntax with argument names. ### Parameters - **template** (str) - Required - The format string, e.g., 'user:{user_id}'. ### Behavior - Fields can access attributes and items: `Key('search:{request.client.host}')` - Arguments are bound by name, defaults included. - `*args` and `**kwargs` are available as tuple and dict. - Raises TypeError if a field names no parameter. - Raises ValueError for positional fields, unknown conversions, or fields inside format specs. - Doubled braces are literal. - A field that is None or empty string raises ValueError on call. ### Example ```python Key('user:{user_id}') Key('search:{request.client.host}') Key('{headers[x-api-key]}') ``` ``` -------------------------------- ### Decorator with default and Key template Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt The decorator uses the function's module.qualname by default, or a Key template to create per-user buckets. Key templates fill from call arguments. ```python from ratelimit_io import Key limiter = RateLimiter(client, limit=Limit(10, seconds=1)) @limiter # bucket: 'shop.views.checkout' async def checkout(order_id: int) -> None: ... @limiter(key=Key('user:{user_id}')) # one bucket per user async def search(user_id: int, query: str) -> list[str]: ... ``` -------------------------------- ### RateLimiter constructor Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms.txt Create a RateLimiter instance with the given Redis client and configuration. ```APIDOC ## RateLimiter constructor ### Description Create a RateLimiter instance with the given Redis client and configuration. ### Signature `RateLimiter(client, *, limit=None, key=None, algorithm=Algorithm.FIXED_WINDOW, max_wait=0, key_prefix='ratelimit_io')` ### Parameters - **client** (redis.Redis or redis.asyncio.Redis) - Required - The Redis client to use. - **limit** (Limit) - Optional - The default rate limit. - **key** (string, Key, or function) - Optional - The default key. - **algorithm** (Algorithm) - Optional - The rate limiting algorithm. Defaults to Algorithm.FIXED_WINDOW. - **max_wait** (float) - Optional - Maximum time to wait for a slot. Defaults to 0. - **key_prefix** (string) - Optional - Prefix for keys. Defaults to 'ratelimit_io'. ### Returns - A RateLimiter instance. ``` -------------------------------- ### Tag and push a release Source: https://github.com/bagowix/ratelimit-io/blob/main/CONTRIBUTING.md Tags the merge commit with the version and pushes the tag. The release workflow then builds and publishes to PyPI. ```bash git tag vX.Y.Z && git push origin vX.Y.Z ``` -------------------------------- ### Regenerate docs/llms-full.txt Source: https://github.com/bagowix/ratelimit-io/blob/main/CONTRIBUTING.md Regenerates the full documentation file after user-facing changes. ```bash uv run python scripts/build_llms_full.py ``` -------------------------------- ### acquire_sync(key=None, *, limit=None, max_wait=None) Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt The blocking twin of `acquire()`, through a sync client. ```APIDOC ## acquire_sync(key=None, *, limit=None, max_wait=None) ### Description The blocking twin of `acquire()`, through a sync client. ### Parameters - **key** (str) - Optional - The bucket key. If not provided, uses the limiter's default key. - **limit** (Limit) - Optional - The limit to apply. If not provided, uses the limiter's default limit. - **max_wait** (float) - Optional - Maximum seconds to wait for a slot. Overrides the limiter's default. ### Errors Raises `TypeError` on an async client or for an argument of the wrong type, and `ValueError` when no key or no limit is given and the limiter has none. ``` -------------------------------- ### Acquire with explicit key Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt Use the key argument to select a bucket for acquire(). Without a key, the limiter's own key is used; with neither, acquire() raises ValueError. ```python github = RateLimiter(client, limit=Limit(5000, hours=1), key='github') await github.acquire() # the 'github' bucket await github.acquire('search') # the 'search' bucket ``` -------------------------------- ### Key function for dynamic bucket selection Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt Use a key function when logic beyond a template is needed. It receives bound parameters and must return a non-empty string; empty strings raise ValueError, non-strings raise TypeError. ```python def account_key(user: User) -> str: if user.organization_id is not None: return f'org:{user.organization_id}' return f'user:{user.id}' @limiter(key=account_key) # members of an organization share its bucket async def search(user: User, query: str) -> list[str]: ... ``` -------------------------------- ### Outgoing httpx client with sliding window rate limiter Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt Creates an async RateLimiter for outgoing API calls, using a limiter-wide key 'github' and a sliding window algorithm with a max wait of 30 seconds. The decorated fetch_repo function sends an authenticated request to the GitHub API and raises for status. ```python import httpx from redis.asyncio import Redis from ratelimit_io import Algorithm, Limit, RateLimiter github = RateLimiter( Redis(), limit=Limit(5000, hours=1), key='github', algorithm=Algorithm.SLIDING_WINDOW, max_wait=30, ) @github async def fetch_repo(client: httpx.AsyncClient, name: str) -> dict[str, object]: response = await client.get(f'https://api.github.com/repos/{name}') response.raise_for_status() return response.json() ``` -------------------------------- ### httpx async client with limiter-wide key and wait budget Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/frameworks.md For outgoing API calls, uses a limiter-wide key and max_wait to stay under quota. GitHub allows 5000 requests/hour for authenticated clients; the client sends a token. Sliding window prevents boundary violations. ```python import httpx from redis.asyncio import Redis from ratelimit_io import Algorithm, Limit, RateLimiter github = RateLimiter( Redis(), limit=Limit(5000, hours=1), key='github', algorithm=Algorithm.SLIDING_WINDOW, max_wait=30, ) @github async def fetch_repo(client: httpx.AsyncClient, name: str) -> dict[str, object]: response = await client.get(f'https://api.github.com/repos/{name}') response.raise_for_status() return response.json() ``` -------------------------------- ### Run griffe check locally for API compatibility Source: https://github.com/bagowix/ratelimit-io/blob/main/CONTRIBUTING.md Diffs the public API against the latest release tag. Used by the api-compatibility workflow on every pull request. ```bash uv run griffe check ratelimit_io --search . ``` -------------------------------- ### RateLimiter.acquire(key=None) Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt Acquires a permit from the bucket identified by the given key. If no key is provided, the limiter's own key is used. Raises ValueError if no key is available. ```APIDOC ## acquire(key=None) ### Description Acquires a permit from the bucket identified by the given key. If no key is provided, the limiter's own key is used. Raises ValueError if no key is available. ### Method acquire ### Parameters - **key** (str) - Optional - The key identifying the bucket. If omitted, the limiter's own key is used. ### Request Example ```python await limiter.acquire() await limiter.acquire('search') ``` ### Response #### Success Response - No return value (None) #### Error Responses - **ValueError** - If no key is provided and the limiter has no key. ``` -------------------------------- ### Key template Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/guides/keys.md A `Key` object fills a `str.format` template from the arguments of each call. Fields can reference parameters, attributes, and items. ```APIDOC ## `Key(template)` ### Description A `Key` object fills a `str.format` template from the arguments of each call. Fields can reference parameters, attributes, and items. ### Parameters - **template** (str) - The format template. Fields start with a parameter name and may include attributes and items. ### Examples ```python Key('search:{request.client.host}') Key('{headers[x-api-key]}') Key('account:{self.account_id}') Key('user:{kwargs[user_id]}') Key('{{tag}}:{user_id}') ``` ### Behavior - Arguments are bound by name, including defaults. - `*args` and `**kwargs` are filled under their own names as a tuple and a dict. - Doubled braces stay literal. ### Errors - `TypeError` - If a field names no parameter of the function (raised at import time). - `ValueError` - If a positional field (`{}` or `{0}`), unknown conversion, or field inside a format spec is used (raised when the `Key` is created). - `ValueError` - If a field is `None` or an empty string on a call. ``` -------------------------------- ### Django synchronous middleware for rate limiting Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/frameworks.md The middleware is synchronous, so the limiter takes a redis.Redis client and calls acquire_sync(). Django runs this sync middleware under WSGI and ASGI alike, in front of sync and async views, covering every view. Behind a proxy, key on the client address your proxy forwards rather than on REMOTE_ADDR. ```python import math from django.http import HttpRequest, HttpResponse from redis import Redis from ratelimit_io import Limit, RateLimiter, RateLimitExceededError limiter = RateLimiter(Redis(), limit=Limit(100, minutes=1)) class RateLimitMiddleware: def __init__(self, get_response): self.get_response = get_response def __call__(self, request: HttpRequest) -> HttpResponse: try: limiter.acquire_sync(request.META['REMOTE_ADDR']) except RateLimitExceededError as error: response = HttpResponse('Too many requests', status=429) response['Retry-After'] = str(math.ceil(error.retry_after)) return response return self.get_response(request) ``` -------------------------------- ### await acquire(key=None, *, limit=None, max_wait=None) Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt Takes one slot from the bucket of `key` through an async client. When the bucket is full and its next free slot is at most `max_wait` seconds away, the request reserves that slot and sleeps until it; otherwise it raises `RateLimitExceededError` at once. ```APIDOC ## await acquire(key=None, *, limit=None, max_wait=None) ### Description Takes one slot from the bucket of `key` through an async client. When the bucket is full and its next free slot is at most `max_wait` seconds away, the request reserves that slot and sleeps until it; otherwise it raises `RateLimitExceededError` at once. Waiting requests are served in arrival order across processes. ### Parameters - **key** (str) - Optional - The bucket key. If not provided, uses the limiter's default key. - **limit** (Limit) - Optional - The limit to apply. If not provided, uses the limiter's default limit. - **max_wait** (float) - Optional - Maximum seconds to wait for a slot. Overrides the limiter's default. ### Errors Raises `TypeError` on a sync client or for an argument of the wrong type, and `ValueError` when no key or no limit is given and the limiter has none. ``` -------------------------------- ### Key(template) Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/reference.md Creates a decorator key that formats a template string from the arguments of each call. The template can reference function parameters and their attributes or items, and supports literal braces via doubling. ```APIDOC ## Key(template) ### Description Creates a decorator key that formats a template string from the arguments of each call. The template can reference function parameters and their attributes or items, and supports literal braces via doubling. ### Constructor `Key(template)` ### Parameters - **template** (str) - Required - The template string to format. Must be a non-empty string without positional fields, unknown conversions, or fields inside format specs. ### Behavior - The template is formatted using `str.format` with the arguments of the decorated call. - A plain `str` key is never formatted. - Doubled braces (`{{` and `}}`) are treated as literal braces. ### Exceptions - Raises `TypeError` if `template` is not a string. - Raises `ValueError` if `template` is empty, malformed, contains a positional field (e.g., `{}` or `{0}`), has an unknown conversion, or has a field inside a format spec. ### Example ```python @limiter(key=Key('user:{user_id}')) ``` ``` -------------------------------- ### await acquire(key=None, *, limit=None, max_wait=None) Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/reference.md Takes one slot from the bucket of the given key through an async client. If the bucket is full and the next free slot is within max_wait, it reserves and waits; otherwise it raises RateLimitExceededError. ```APIDOC ## await acquire(key=None, *, limit=None, max_wait=None) ### Description Takes one slot from the bucket of `key` through an async client. When the bucket is full and its next free slot is at most `max_wait` seconds away, the request reserves that slot and sleeps until it; otherwise it raises `RateLimitExceededError` at once. Waiting requests are served in arrival order across processes. ### Method Async method ### Parameters - **key** (str) - Optional - The bucket key. If not provided, uses the limiter's default key. - **limit** (Limit) - Optional - The limit to apply. If not provided, uses the limiter's default limit. - **max_wait** (float) - Optional - Maximum seconds to wait for a slot. Overrides the limiter's default. ### Exceptions Raises `TypeError` on a sync client or for an argument of the wrong type, and `ValueError` when no key or no limit is given and the limiter has none. ``` -------------------------------- ### Key function Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt A function that receives the call's arguments and returns the bucket key string. ```APIDOC ## Key function ### Description A function that receives the call's arguments and returns the bucket key string. ### Parameters - The function receives the parameters it names, bound to the decorated function's arguments. - A parameter the decorated function lacks must have a default. - `**kwargs` receives every argument. ### Return Value - Must return a non-empty string. ### Errors - Raises ValueError if the function returns an empty string. - Raises TypeError if the function returns a non-string. ### Example ```python def account_key(user: User) -> str: if user.organization_id is not None: return f'org:{user.organization_id}' return f'user:{user.id}' @limiter(key=account_key) async def search(user: User, query: str) -> list[str]: ... ``` ``` -------------------------------- ### Several functions, one bucket Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt Use the same key for multiple functions to share a single bucket. A limiter-wide key applies to every function it decorates, which is what an outgoing client wants. ```python payments = RateLimiter(client, limit=Limit(100, seconds=1), key='payments-api', max_wait=5) @payments async def charge(card: str, amount: int) -> None: ... @payments async def refund(charge_id: str) -> None: ... ``` -------------------------------- ### Run all CI checks locally Source: https://github.com/bagowix/ratelimit-io/blob/main/CONTRIBUTING.md Runs the exact checks CI performs on Python 3.11 to 3.15. Includes formatting, linting, type checking (strict), tests with 100% coverage, GitHub Actions audit, and docs build. ```bash uv run ruff format --check # formatting uv run ruff check # linting uv run mypy # type checking (strict) uv run pyright # type checking (strict, second checker) uv run pyrefly check # type checking (strict, third opinion) uv run pytest --cov # tests, 100% coverage required uv run zizmor .github/ # GitHub Actions and Dependabot audit uv run zensical build --strict # docs, including broken links ``` -------------------------------- ### acquire_sync(key=None, *, limit=None, max_wait=None) Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/reference.md The blocking twin of `acquire()`, through a sync client. It takes one slot from the bucket of the given key, waiting if necessary. ```APIDOC ## acquire_sync(key=None, *, limit=None, max_wait=None) ### Description The blocking twin of `acquire()`, through a sync client. It takes one slot from the bucket of the given key, waiting if necessary. ### Method Sync method ### Parameters - **key** (str) - Optional - The bucket key. If not provided, uses the limiter's default key. - **limit** (Limit) - Optional - The limit to apply. If not provided, uses the limiter's default limit. - **max_wait** (float) - Optional - Maximum seconds to wait for a slot. Overrides the limiter's default. ### Exceptions Raises `TypeError` on an async client or for an argument of the wrong type, and `ValueError` when no key or no limit is given and the limiter has none. ``` -------------------------------- ### Key Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt Frozen dataclass that creates a decorator key template for rate limiting, filled from the arguments of each call. Use it with the limiter decorator to define dynamic keys based on function parameters. ```APIDOC ## Key ### Description Frozen dataclass that creates a decorator key template for rate limiting, filled from the arguments of each call. Use it with the limiter decorator to define dynamic keys based on function parameters. ### Constructor `Key(template)` ### Parameters - **template** (str) - Required - The template string to format from call arguments. Fields start with parameter names and may access attributes/items (e.g., `{user_id}`, `{request.client.host}`). Doubled braces stay literal. ### Behavior - A plain `str` key is never formatted. - Raises `TypeError` if `template` is not a string. - Raises `ValueError` if `template` is empty, malformed, has a positional field (e.g., `{}` or `{0}`), an unknown conversion, or a field inside a format spec. ### Example ```python @limiter(key=Key('user:{user_id}')) def get_user(user_id): ... ``` ``` -------------------------------- ### Algorithm Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt Enumeration of the counting algorithms supported by ratelimit-io. Use these values to select the algorithm when creating a rate limit. ```APIDOC ## Algorithm ### Description Enumeration of the counting algorithms supported by ratelimit-io. ### Values - `FIXED_WINDOW = 'fixed_window'` (default) - `SLIDING_WINDOW = 'sliding_window'` - `GCRA = 'gcra'` ``` -------------------------------- ### Flask error handler and decorator with Key template Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/frameworks.md Use with Flask views. The Key template reads view parameters; request.remote_addr is None when no peer address, and the function aborts with 500 for such requests. The error handler returns 429 with Retry-After header. ```python import math from flask import Flask, abort, request from redis import Redis from ratelimit_io import Limit, RateLimiter, RateLimitExceededError app = Flask(__name__) limiter = RateLimiter(Redis(), limit=Limit(100, minutes=1)) @app.errorhandler(RateLimitExceededError) def too_many_requests(error: RateLimitExceededError): return 'Too many requests', 429, {'Retry-After': str(math.ceil(error.retry_after))} def items_key() -> str: if request.remote_addr is None: abort(500, 'no client address to rate limit by') return f'items:{request.remote_addr}' @app.get('/items/') @limiter(key=items_key) def get_item(item_id: int) -> str: return str(item_id) ``` -------------------------------- ### FastAPI decorator with Key template for rate limiting Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/frameworks.md Use this decorator on a FastAPI route to rate limit based on a Key template that fills the bucket key from request parameters. The decorator preserves the endpoint's signature so FastAPI still sees the parameters. Put @app.get above the limiter so the route registers the limited function; when request.client is None, the template raises AttributeError and the request fails with a 500. ```python from ratelimit_io import Key @app.get('/search') @limiter(key=Key('search:{request.client.host}')) async def search(request: Request, q: str) -> list[str]: return [] ``` -------------------------------- ### Algorithm Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/reference.md Enumeration of supported rate limiting algorithms. Use these values to configure the algorithm for a rate limiter. ```APIDOC ## Algorithm ### Description Enumeration of supported rate limiting algorithms. ### Members - `FIXED_WINDOW` = `'fixed_window'` (default) - `SLIDING_WINDOW` = `'sliding_window'` - `GCRA` = `'gcra'` ``` -------------------------------- ### RateLimiter as decorator Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms.txt Use the RateLimiter as a decorator to apply rate limiting to functions. Supports both async and sync functions. ```APIDOC ## RateLimiter as decorator ### Description Use the RateLimiter as a decorator to apply rate limiting to functions. Supports both async and sync functions. ### Usage - `@limiter` - Apply the limiter's default settings. - `@limiter(key=..., limit=..., max_wait=...)` - Apply with custom settings. - `limiter(func, key=...)` - Apply as a plain call. ### Parameters - **key** (string, Key, or function) - Optional - The key for the rate limit bucket. If not provided, uses the limiter's key or the function's module.qualname. - **limit** (Limit) - Optional - The rate limit to apply. If not provided, uses the limiter's limit. - **max_wait** (float) - Optional - Maximum time to wait for a slot. If not provided, uses the limiter's max_wait. ### Notes - Coroutine functions need an async client, plain functions a sync one. - Key precedence: decorator key, then limiter's key, then function's module.qualname. - A plain string key is never formatted; a decorator string that reads as a template raises ValueError. - Key templates must name parameters; fields that are None or empty raise ValueError. ``` -------------------------------- ### key_prefix Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt Set different key_prefix values to keep buckets separate for applications sharing a Redis server. Buckets expire on their own once nothing counts any more. ```python RateLimiter(client, limit=..., key_prefix='billing') RateLimiter(client, limit=..., key_prefix='search') ``` -------------------------------- ### Limit(requests, *, seconds=0, minutes=0, hours=0) Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/reference.md Creates a rate limit with a number of requests per a time period. The period is the sum of seconds, minutes, and hours, and can be fractional down to milliseconds. ```APIDOC ## Limit(requests, *, seconds=0, minutes=0, hours=0) ### Description Creates a rate limit with a number of requests per a time period. The period is the sum of seconds, minutes, and hours, and can be fractional down to milliseconds. ### Constructor `Limit(requests, *, seconds=0, minutes=0, hours=0)` ### Parameters - **requests** (int) - Required - The maximum number of requests allowed in the period. Must be a positive integer (any integer type, including numpy integers). - **seconds** (number) - Optional - The seconds component of the period. Must be a non-negative finite number (not a bool). - **minutes** (number) - Optional - The minutes component of the period. Must be a non-negative finite number (not a bool). - **hours** (number) - Optional - The hours component of the period. Must be a non-negative finite number (not a bool). ### Methods - **`total_seconds() -> float`** - Returns the period in seconds. - **`period_ms() -> int`** - Returns the period in whole milliseconds. ### String Representation - `str(limit)` returns a string like `'100/60s'`, with the period as enforced. ### Equality and Hashing - Limits that allow the same requests per the same period are equal and hash alike. For example, `Limit(1, minutes=1) == Limit(1, seconds=60)`. ### Exceptions - Raises `TypeError` if `requests` is not an integer or a period part is not a number (a bool is neither). - Raises `ValueError` if `requests` is not positive, a period part is negative or not finite, or the period is shorter than a millisecond. ### Example ```python limit = Limit(100, minutes=1) ``` ``` -------------------------------- ### Sync rate limiting for incoming and outgoing requests Source: https://github.com/bagowix/ratelimit-io/blob/main/README.md Shows two RateLimiter usages: one for incoming requests that refuses at once (max_wait=0) and prints a 429 response with retry_after, and one for outgoing requests that waits up to 30 seconds for a slot and never exceeds 5000 requests per hour using the sliding window algorithm. ```python from redis import Redis from ratelimit_io import Algorithm, Limit, RateLimiter, RateLimitExceededError # Incoming requests: refuse at once. api = RateLimiter(Redis(), limit=Limit(10, seconds=1)) try: api.acquire_sync('203.0.113.7') except RateLimitExceededError as error: print(f'429, retry after {error.retry_after:.1f}s') # Outgoing requests: wait up to 30 s for a slot, never exceed 5000 an hour. github = RateLimiter( Redis(), limit=Limit(5000, hours=1), key='github', algorithm=Algorithm.SLIDING_WINDOW, max_wait=30, ) github.acquire_sync() ``` -------------------------------- ### Litestar guard and exception handler for rate limiting Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/frameworks.md A guard runs before the handler and an exception handler answers the refusal. The guard raises InternalServerException if no client address is available, otherwise it acquires a rate limit keyed by URL path and client host. The exception handler returns a 429 response with a Retry-After header. ```python import math from litestar import Litestar, Request, Response, get from litestar.connection import ASGIConnection from litestar.exceptions import InternalServerException from litestar.handlers.base import BaseRouteHandler from redis.asyncio import Redis from ratelimit_io import Limit, RateLimiter, RateLimitExceededError limiter = RateLimiter(Redis(), limit=Limit(100, minutes=1)) async def rate_limit(connection: ASGIConnection, _: BaseRouteHandler) -> None: if connection.client is None: raise InternalServerException('no client address to rate limit by') await limiter.acquire(f'{connection.url.path}:{connection.client.host}') def too_many_requests(request: Request, error: RateLimitExceededError) -> Response[dict[str, str]]: return Response( {'detail': 'Too many requests'}, status_code=429, headers={'Retry-After': str(math.ceil(error.retry_after))}, ) @get('/items', guards=[rate_limit]) async def list_items() -> list[str]: return [] app = Litestar( route_handlers=[list_items], exception_handlers={RateLimitExceededError: too_many_requests}, ) ``` -------------------------------- ### Run a single test Source: https://github.com/bagowix/ratelimit-io/blob/main/CONTRIBUTING.md Runs a specific test by its full path. The suite runs in parallel via pytest-xdist; add -n 0 to run serially, e.g., under --pdb. ```bash uv run pytest tests/test_limiter.py::test__acquire_sync__over_limit__raises_with_retry_after ``` -------------------------------- ### RateLimitExceededError Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt Exception raised when a request is refused because the next free slot is further away than the request may wait. Contains the limit that refused the request and the retry-after duration. ```APIDOC ## RateLimitExceededError ### Description Raised when a request is refused: the next free slot is further away than the request may wait. ### Constructor `RateLimitExceededError(limit, retry_after)` ### Parameters - **limit** (`Limit`) - The limit that refused the request. - **retry_after** (`float`) - Seconds until a request on the same key can pass. Round it up for an HTTP `Retry-After` header. ### Inheritance Subclass of `RateLimitError`. It survives pickling, so it can cross process boundaries. ``` -------------------------------- ### Flask error handler and rate-limited view with items_key Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt Sets up a Flask app with a RateLimiter using a Redis backend and a limit of 100 requests per minute. The error handler returns a 429 response with a Retry-After header. The items_key function aborts with 500 if request.remote_addr is None, and the view is rate-limited by that key. ```python import math from flask import Flask, abort, request from redis import Redis from ratelimit_io import Limit, RateLimiter, RateLimitExceededError app = Flask(__name__) limiter = RateLimiter(Redis(), limit=Limit(100, minutes=1)) @app.errorhandler(RateLimitExceededError) def too_many_requests(error: RateLimitExceededError): return 'Too many requests', 429, {'Retry-After': str(math.ceil(error.retry_after))} def items_key() -> str: if request.remote_addr is None: abort(500, 'no client address to rate limit by') return f'items:{request.remote_addr}' @app.get('/items/') @limiter(key=items_key) def get_item(item_id: int) -> str: return str(item_id) ``` -------------------------------- ### Basic usage: RateLimiter with async decorator Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/index.md Shows the core usage of ratelimit-io: create a RateLimiter with a Redis client and a Limit, then decorate an async function with @limiter(key=Key(...)). The 101st call within a minute for one user raises RateLimitExceededError, whose retry_after attribute gives seconds to wait (round up for an HTTP Retry-After header). ```python from redis.asyncio import Redis from ratelimit_io import Key, Limit, RateLimiter limiter = RateLimiter(Redis(), limit=Limit(100, minutes=1)) @limiter(key=Key('user:{user_id}')) async def search(user_id: int, query: str) -> list[str]: ... ``` -------------------------------- ### RateLimiter.acquire_sync Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms.txt Synchronously acquire a rate limit slot. This method is used for sync code and requires a redis.Redis client. ```APIDOC ## acquire_sync ### Description Synchronously acquire a rate limit slot. This method is used for sync code and requires a redis.Redis client. ### Method acquire_sync ### Signature `limiter.acquire_sync(key=None, *, limit=None, max_wait=None)` ### Parameters - **key** (string, Key, or function) - Optional - The key for the rate limit bucket. If not provided, uses the limiter's key or the function's module.qualname. - **limit** (Limit) - Optional - The rate limit to apply. If not provided, uses the limiter's limit. - **max_wait** (float) - Optional - Maximum time to wait for a slot. If not provided, uses the limiter's max_wait. ### Returns - None on success, or raises RateLimitExceededError if the limit is exceeded and max_wait is 0 or the wait exceeds the budget. ### Errors - **TypeError** - If the client is not a redis.Redis client. - **RateLimitExceededError** - If the rate limit is exceeded and no slot is available within max_wait. ``` -------------------------------- ### RateLimiter.acquire Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms.txt Asynchronously acquire a rate limit slot. This method is used for async code and requires a redis.asyncio.Redis client. ```APIDOC ## acquire ### Description Asynchronously acquire a rate limit slot. This method is used for async code and requires a redis.asyncio.Redis client. ### Method acquire ### Signature `await limiter.acquire(key=None, *, limit=None, max_wait=None)` ### Parameters - **key** (string, Key, or function) - Optional - The key for the rate limit bucket. If not provided, uses the limiter's key or the function's module.qualname. - **limit** (Limit) - Optional - The rate limit to apply. If not provided, uses the limiter's limit. - **max_wait** (float) - Optional - Maximum time to wait for a slot. If not provided, uses the limiter's max_wait. ### Returns - None on success, or raises RateLimitExceededError if the limit is exceeded and max_wait is 0 or the wait exceeds the budget. ### Errors - **TypeError** - If the client is not a redis.asyncio.Redis client. - **RateLimitExceededError** - If the rate limit is exceeded and no slot is available within max_wait. ``` -------------------------------- ### @limiter decorator Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt Decorator that applies rate limiting to a function. The bucket key is determined by the decorator's key, the limiter's key, or the function's module.qualname. ```APIDOC ## @limiter(key=None) ### Description Decorator that applies rate limiting to a function. The bucket key is determined by the decorator's key, the limiter's key, or the function's module.qualname. ### Parameters - **key** (str, Key, or callable) - Optional - The key for the bucket. Can be a string, a Key template, or a key function. ### Usage ```python @limiter async def checkout(order_id: int) -> None: ... @limiter(key=Key('user:{user_id}')) async def search(user_id: int, query: str) -> list[str]: ... ``` ### Key Resolution Order 1. The decorator's `key` 2. The limiter's `key` 3. The function's `module.qualname` ``` -------------------------------- ### Fix GitHub Actions workflow pins with zizmor Source: https://github.com/bagowix/ratelimit-io/blob/main/CONTRIBUTING.md Rewrites action pins to commit SHAs with version comments. Requires a GitHub token; use GH_TOKEN=$(gh auth token). ```bash GH_TOKEN=$(gh auth token) uv run zizmor --fix=all .github/ ``` -------------------------------- ### RateLimiter Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt A distributed rate limiter on Redis. It takes a Redis client and configuration options, and provides methods to acquire slots and decorate functions. ```APIDOC ## RateLimiter ### Description A distributed rate limiter on Redis. It takes a Redis client and configuration options, and provides methods to acquire slots and decorate functions. ### Constructor `RateLimiter(client, *, limit=None, key=None, algorithm=Algorithm.FIXED_WINDOW, max_wait=0, key_prefix='ratelimit_io')` ### Parameters - **client** (redis.asyncio.Redis or redis.Redis) - Required - The Redis client. Use `redis.asyncio.Redis` for `acquire()` and coroutine functions, or `redis.Redis` for `acquire_sync()` and plain functions. Anything else raises `TypeError`. - **limit** (Limit) - Optional - The default `Limit` of calls that name none. - **key** (str) - Optional - The default bucket key of calls that name none. - **algorithm** (Algorithm) - Optional - The rate limiting algorithm. See `Algorithm`. - **max_wait** (float) - Optional - Seconds a request may wait for a slot. `0` fails at once; `math.inf` waits as long as it takes. - **key_prefix** (str) - Optional - The namespace of every bucket in Redis. ### Errors Raises `TypeError` for an option of the wrong type, and `ValueError` for an empty `key` or `key_prefix`, a negative or NaN `max_wait`, or an unknown algorithm. ``` -------------------------------- ### RateLimitError Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms.txt Base class for rate limit errors. ```APIDOC ## RateLimitError ### Description Base class for rate limit errors. ``` -------------------------------- ### Layered limits Source: https://github.com/bagowix/ratelimit-io/blob/main/docs/llms-full.txt Acquire slots from separate limits for short bursts and long-term volume. The two limits count separately even on the same key, and the calls are independent. ```python await limiter.acquire(user_key, limit=Limit(10, seconds=1)) await limiter.acquire(user_key, limit=Limit(1000, hours=1)) ```