Typing Stubs for Ratelimit

2.2.0.20260408 · active · verified Tue Apr 14

types-ratelimit provides PEP 561 type stubs for the `ratelimit` library, enabling static type checking for projects using `tomasbasham/ratelimit`. It helps identify type-related issues before runtime by providing annotations for functions, classes, and methods. As part of the typeshed project, its releases are aligned with typeshed's update cadence and aim to match specific versions of the `ratelimit` library.

Warnings

breaking Type stubs from typeshed, including `types-ratelimit`, may introduce breaking changes to type checking even in minor updates, as they reflect evolving upstream libraries or typeshed's own typing improvements.
Fix: Pin your `types-ratelimit` version to a known good one (e.g., `types-ratelimit==X.Y.Z.YYYYMMDD`) or align it with the exact major.minor version of the `ratelimit` runtime library you are using. Regularly test type checking in your CI.
gotcha The `types-ratelimit` package provides type hints for the `ratelimit` library (specifically `tomasbasham/ratelimit`). If you are using a different rate-limiting library (e.g., `upstash-ratelimit` or `pyrate-limiter`), these stubs will not be applicable and may cause incorrect type-checking results or errors.
Fix: Ensure that the `ratelimit` library you intend to use for runtime execution is indeed `tomasbasham/ratelimit` (the one found on PyPI as `ratelimit`). If not, uninstall `types-ratelimit` and seek stubs specific to your chosen rate-limiting library, or write your own custom stubs if none exist.
gotcha Typeshed stubs, including `types-ratelimit`, are typically maintained to be compatible with a specific range of the runtime library's versions (e.g., `ratelimit==2.2.*`). Discrepancies between the stub version and your installed `ratelimit` version can lead to incorrect type checking or unannotated code.
Fix: Check the `types-ratelimit` metadata (e.g., on PyPI or typeshed's stats page) to identify the `ratelimit` versions it supports. Ensure your installed `ratelimit` package falls within this range.

Install

pip install types-ratelimit Install with pip

Imports

limits
```
from ratelimit import limits
```
sleep_and_retry
```
from ratelimit import sleep_and_retry
```

Quickstart

This quickstart demonstrates basic usage of the `ratelimit` library with `types-ratelimit` providing static type checking. The `limits` decorator restricts the number of calls within a period, and `sleep_and_retry` ensures the function waits until the rate limit resets before retrying.

import time
from ratelimit import limits, sleep_and_retry

# Define a period for rate limiting (e.g., 60 seconds)
ONE_MINUTE = 60

@sleep_and_retry
@limits(calls=5, period=ONE_MINUTE)
def call_api(attempt: int) -> str:
    """Simulates an API call with rate limiting."""
    print(f"Calling API - Attempt {attempt}")
    # Simulate some work
    # In a real scenario, this would make an external request
    return f"API response for attempt {attempt}"

print("Starting API calls...")
for i in range(1, 10):
    try:
        result = call_api(i)
        print(result)
    except Exception as e:
        print(f"Error: {e}")
    # Small delay to make output clearer, not part of ratelimit logic
    time.sleep(1)
print("Finished API calls.")

view raw JSON →