Typing Stubs for requests

Common errors

import requests

response = requests.get('https://api.example.com/data')
data = response.json()

if data is not None:
    value = data.get('key')
    print(value)
else:
    print('No JSON data or invalid JSON.')

# Or, provide a default empty dict:
safe_data = response.json() or {}
value = safe_data.get('key')
print(value)

Warnings

Install

Install compatibility verified last tested: 2026-05-12

Imports

• requests
  wrong

  import types_requests

  correct

  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 stale last tested: 2026-04-23

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.")