Typing Stubs for requests

Warnings

• breaking Version incompatibility with `urllib3` prior to types-requests 2.31.0.7. Versions of `types-requests` from `2.31.0.7` onwards require `urllib3>=2`. If your `requests` installation depends on an older `urllib3<2`, installing a newer `types-requests` will cause type checking issues due to conflicting stub dependencies.
  Fix: For projects that *must* use `urllib3<2`, pin `types-requests<2.31.0.7`. For `urllib3>=2` environments, use `types-requests>=2.31.0.7`. Consider aligning your `requests` and `types-requests` version bounds for compatibility.
• gotcha Installing `types-requests` does not install `requests` itself. This package only provides type annotations for the `requests` library. The `requests` library must be installed separately for your code to run at runtime.
  Fix: Ensure you have both `pip install requests` and `pip install types-requests` if you want both runtime functionality and type checking in your environment.
• gotcha Stub package versioning does not always directly mirror the runtime package version. While the first three parts of `types-requests`'s version generally align with `requests` (e.g., `types-requests==2.33.0.YYYYMMDD` is for `requests~=2.33.0`), the final part is a daily release date from the Typeshed repository. Minor stub updates can introduce new type-checking errors even if the runtime `requests` package has not changed.
  Fix: Pinning `types-requests` to an exact version (e.g., `types-requests==2.33.0.20260327`) in your `requirements.txt` can prevent unexpected type-checking failures, though it means you might miss beneficial stub bug fixes. Alternatively, use version ranges for both `requests` and `types-requests` to manage compatibility.
• gotcha Do not attempt to import `types_requests` directly in your Python code. Stub packages are automatically discovered by type checkers and are not meant for direct runtime import. Attempting to import it will result in a `ModuleNotFoundError` during program execution.
  Fix: Always `import requests` in your code. The type checker will correctly associate this import with the installed `types-requests` stubs.

Install

• pip install types-requests Install only stubs
• pip install requests types-requests Install requests and its stubs

Imports

• requests

  import requests

  types-requests is a stub package for the 'requests' library. You install it separately for your type checker, but you import 'requests' in your code. The type checker automatically discovers the installed stubs. Do not attempt to import 'types_requests' directly; it will result in a ModuleNotFoundError.
• requests.Session

  import requests
  session: requests.Session = requests.Session()

  Similar to the main 'requests' import, the types for Session and other sub-modules are provided by the installed stubs.

Quickstart

This quickstart demonstrates a basic `requests.get` call with type hints. When `types-requests` is installed, a type checker (like Mypy or Pyright) will use the stub files to validate the types of `url`, `params`, and the return values from `requests.get` and `response.json()` without needing explicit annotations for the `requests` library itself.

import requests
from typing import Dict, Any

def fetch_data(url: str, params: Dict[str, str] = {}) -> Dict[str, Any]:
    """Fetches JSON data from a URL with type hints provided by types-requests."""
    try:
        response = requests.get(url, params=params)
        response.raise_for_status() # Raises HTTPError for bad responses (4xx or 5xx)
        return response.json()
    except requests.exceptions.HTTPError as e:
        print(f"HTTP error occurred: {e}")
        raise
    except requests.exceptions.RequestException as e:
        print(f"An error occurred during the request: {e}")
        raise

# Example usage:
if __name__ == "__main__":
    base_url = "https://httpbin.org/get"
    query_params = {"key1": "value1", "key2": "value2"}
    try:
        data = fetch_data(base_url, query_params)
        print("Fetched data:")
        print(data)
    except Exception:
        print("Failed to fetch data.")