Typing stubs for urllib3

1.26.25.14 · maintenance · verified Sat Mar 28

This is a PEP 561 type stub package providing type annotations for the `urllib3` library. It enables type-checking tools like Mypy, Pyright, and PyCharm to statically analyze code that uses `urllib3`. The package version is 1.26.25.14, and it is released as needed to align with updates from the `typeshed` repository. Users of `urllib3` version 2.0.0 or newer should *not* install this package, as `urllib3` now includes inline type annotations.

Warnings

breaking Do not install `types-urllib3` if you are using `urllib3` version 2.0.0 or newer. `urllib3>=2.0.0` includes its own inline type annotations. Installing `types-urllib3` alongside `urllib3>=2.0.0` will cause type checkers (like Mypy) to ignore the accurate inline types of `urllib3` in favor of the potentially outdated stubs from `types-urllib3`, leading to incorrect type-checking results.
Fix: Uninstall `types-urllib3` if `urllib3` is version 2.0.0 or higher: `pip uninstall types-urllib3`.
gotcha `types-urllib3` is a stub-only package and does not provide any runtime code or functionality. You must explicitly install the `urllib3` library itself to use its features in your application. `types-urllib3` only provides the type definitions for `urllib3`.
Fix: Ensure `urllib3` is installed alongside `types-urllib3`: `pip install urllib3 types-urllib3`.
gotcha When using `types-requests`, be aware of potential dependency conflicts with `urllib3` versions. Earlier versions of `types-requests` might have implicitly depended on `types-urllib3`, which expected `urllib3<2`. This could lead to type-checking issues if your project uses `urllib3>=2.0.0` with a `types-requests` version that expects the older stub package.
Fix: Pin `types-requests` to a compatible version (e.g., `<2.31.0.7` for `urllib3<2`) or upgrade `types-requests` and `urllib3` to compatible versions that use `urllib3`'s inline types directly.

Install

pip install 'urllib3<2' types-urllib3 Install for urllib3 < 2.0
pip install mypy Install a type checker

Imports

PoolManager
```
from urllib3 import PoolManager
```

HTTPResponse

from urllib3.response import HTTPResponse

urllib3
```
import urllib3
```
types-urllib3 is a stub-only package and is not imported directly at runtime; it provides type information for the `urllib3` library.

Quickstart

This example demonstrates how to use `urllib3` with the `types-urllib3` stubs for static type checking. After installing `urllib3<2`, `types-urllib3`, and `mypy`, save the code as `mypy_example.py`. Running `mypy mypy_example.py` will verify type correctness using the provided stubs. This setup is crucial for older `urllib3` versions that lack inline type hints.

# mypy_example.py
import urllib3

# Ensure urllib3 < 2.0 is installed for types-urllib3 to be effective
# For urllib3 >= 2.0, its own inline types should be used.
http = urllib3.PoolManager()

def fetch_url(url: str) -> str:
    try:
        resp = http.request('GET', url)
        return resp.data.decode('utf-8')
    except urllib3.exceptions.MaxRetryError as e:
        return f"Error fetching URL: {e}"

if __name__ == '__main__':
    # Example usage - replace with a real URL or use a test server
    result = fetch_url('http://httpbin.org/status/200')
    print(result)
    # Run with mypy: mypy mypy_example.py

view raw JSON →