{"id":6289,"library":"types-ratelimit","title":"Typing Stubs for Ratelimit","description":"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.","status":"active","version":"2.2.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","type-checking","ratelimit","typeshed"],"install":[{"cmd":"pip install types-ratelimit","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Provides runtime functionality; these are typing stubs for that library.","package":"ratelimit","optional":false}],"imports":[{"symbol":"limits","correct":"from ratelimit import limits"},{"symbol":"sleep_and_retry","correct":"from ratelimit import sleep_and_retry"}],"quickstart":{"code":"import time\nfrom ratelimit import limits, sleep_and_retry\n\n# Define a period for rate limiting (e.g., 60 seconds)\nONE_MINUTE = 60\n\n@sleep_and_retry\n@limits(calls=5, period=ONE_MINUTE)\ndef call_api(attempt: int) -> str:\n    \"\"\"Simulates an API call with rate limiting.\"\"\"\n    print(f\"Calling API - Attempt {attempt}\")\n    # Simulate some work\n    # In a real scenario, this would make an external request\n    return f\"API response for attempt {attempt}\"\n\nprint(\"Starting API calls...\")\nfor i in range(1, 10):\n    try:\n        result = call_api(i)\n        print(result)\n    except Exception as e:\n        print(f\"Error: {e}\")\n    # Small delay to make output clearer, not part of ratelimit logic\n    time.sleep(1)\nprint(\"Finished API calls.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}