{"id":592,"library":"types-requests","title":"Typing Stubs for requests","description":"types-requests provides static type annotations for the popular `requests` HTTP library. It allows type checkers like Mypy and Pyright to analyze code using `requests` for type correctness. This package, part of the larger Typeshed project, aims to provide accurate annotations for `requests~=2.33.0` and is frequently updated, often daily, from the Typeshed repository.","status":"active","version":"2.33.0.20260327","language":"python","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","type hints","requests","typeshed"],"install":[{"cmd":"pip install types-requests","lang":"bash","label":"Install only stubs"},{"cmd":"pip install requests types-requests","lang":"bash","label":"Install requests and its stubs"}],"dependencies":[{"reason":"Provides runtime functionality for which these stubs offer type hints. Must be installed alongside types-requests for type checking to be useful.","package":"requests","optional":false},{"reason":"types-requests versions >=2.31.0.7 require urllib3>=2. This can cause conflicts if the installed requests library explicitly pins an older urllib3 version.","package":"urllib3>=2","optional":false}],"imports":[{"wrong":"import requests-stubs","symbol":"requests","correct":"import requests"}],"quickstart":{"code":"import requests\nfrom typing import Dict, Any\n\ndef fetch_data(url: str, params: Dict[str, str] = {}) -> Dict[str, Any]:\n    \"\"\"Fetches JSON data from a URL with type hints provided by types-requests.\"\"\"\n    try:\n        response = requests.get(url, params=params)\n        response.raise_for_status() # Raises HTTPError for bad responses (4xx or 5xx)\n        return response.json()\n    except requests.exceptions.HTTPError as e:\n        print(f\"HTTP error occurred: {e}\")\n        raise\n    except requests.exceptions.RequestException as e:\n        print(f\"An error occurred during the request: {e}\")\n        raise\n\n# Example usage:\nif __name__ == \"__main__\":\n    base_url = \"https://httpbin.org/get\"\n    query_params = {\"key1\": \"value1\", \"key2\": \"value2\"}\n    try:\n        data = fetch_data(base_url, query_params)\n        print(\"Fetched data:\")\n        print(data)\n    except Exception:\n        print(\"Failed to fetch data.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<2.31.0.7 (compatible with urllib3<2), >=2.31.0.7 (compatible with urllib3>=2)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Always `import requests` in your code. The type checker will correctly associate this import with the installed `types-requests` stubs.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"search_vec":"'2.33.0':49 'accur':45 'aim':42 'allow':19 'analyz':27 'annot':11,46 'checker':21 'code':28 'correct':33 'daili':55 'frequent':52 'hint':63 'http':16 'larger':39 'librari':17 'like':22 'mypi':23 'often':54 'packag':35 'part':36 'popular':14 'project':41 'provid':8,44 'pyright':25 'repositori':59 'request':4,7,15,30,48,64 'static':9 'stub':2,61 'type':1,6,10,20,32,60,62 'types-request':5 'typesh':40,58,65 'updat':53 'use':29","created_at":"2026-03-28T15:20:28.200643+00:00","updated_at":"2026-04-16T23:44:30.801788+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\nModuleNotFoundError: No module named 'requests'"},"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"2.33.0.20260712","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/typeshed-internal/stub_uploader","docs":null,"changelog":"https://github.com/typeshed-internal/stub_uploader/blob/main/data/changelogs/requests.md","pypi":"https://pypi.org/project/types-requests/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-08-27","next_check":"2026-07-10","install_tag":"verified"}}