0
# urllib3
1

2
A powerful, user-friendly HTTP client for Python that brings many critical features missing from the Python standard libraries. urllib3 provides thread-safe connection pooling, client-side SSL/TLS verification, file uploads with multipart encoding, helpers for retrying requests and dealing with HTTP redirects, support for gzip/deflate/brotli/zstd encoding, and proxy support for HTTP and SOCKS.
3

4
## Package Information
5

6
- **Package Name**: urllib3
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install urllib3`
10

11
## Core Imports
12

13
```python
14
import urllib3
15
```
16

17
Common usage patterns:
18

19
```python
20
# Basic request functionality
21
from urllib3 import request
22

23
# Pool management
24
from urllib3 import PoolManager, ProxyManager
25

26
# Connection pools
27
from urllib3 import HTTPConnectionPool, HTTPSConnectionPool
28

29
# Configuration objects
30
from urllib3 import Retry, Timeout
31

32
# Response handling
33
from urllib3 import HTTPResponse, BaseHTTPResponse
34

35
# Header management
36
from urllib3 import HTTPHeaderDict
37

38
# Utility functions
39
from urllib3 import make_headers, encode_multipart_formdata
40

41
# Form field handling
42
from urllib3.fields import RequestField
43
```
44

45
## Basic Usage
46

47
```python
48
import urllib3
49

50
# Simple GET request using module-level function
51
resp = urllib3.request('GET', 'https://httpbin.org/json')
52
print(resp.status)  # 200
53
print(resp.data.decode('utf-8'))  # JSON response
54

55
# Using PoolManager for better performance and connection reuse
56
http = urllib3.PoolManager()
57
resp = http.request('GET', 'https://httpbin.org/json')
58
print(resp.status)  # 200
59
print(resp.data.decode('utf-8'))  # JSON response
60

61
# POST request with data
62
resp = http.request('POST', 'https://httpbin.org/post',
63
                   fields={'key': 'value'})
64

65
# Request with custom headers
66
resp = http.request('GET', 'https://httpbin.org/headers',
67
                   headers={'User-Agent': 'urllib3/2.0'})
68

69
# Request with JSON data
70
import json
71
resp = http.request('POST', 'https://httpbin.org/post',
72
                   body=json.dumps({'key': 'value'}),
73
                   headers={'Content-Type': 'application/json'})
74
```
75

76
## Architecture
77

78
urllib3 uses a layered architecture that provides both simple interfaces and fine-grained control:
79

80
- **PoolManager**: High-level interface that automatically manages connection pools across different hosts and protocols
81
- **Connection Pools**: Per-host connection management with thread-safe connection reuse (HTTPConnectionPool, HTTPSConnectionPool)
82
- **Connections**: Individual HTTP/HTTPS connections with SSL/TLS support
83
- **Response Objects**: Comprehensive response handling with automatic content decoding and streaming support
84
- **Retry Logic**: Configurable retry behavior with exponential backoff for various failure scenarios
85
- **Proxy Support**: Built-in support for HTTP and SOCKS proxies with authentication
86

87
This design enables urllib3 to serve as the foundation HTTP library for many Python packages including requests, and provides the performance and reliability needed for production applications.
88

89
## Capabilities
90

91
### High-Level Request Interface
92

93
Simple, convenient functions for making HTTP requests without managing connection pools directly.
94

95
```python { .api }
96
def request(method: str, url: str, *, body=None, fields=None, headers=None, 
97
           preload_content=True, decode_content=True, redirect=True, 
98
           retries=None, timeout=3, json=None) -> BaseHTTPResponse: ...
99
```
100

101
[Simple Requests](./simple-requests.md)
102

103
### Pool Management
104

105
Sophisticated connection pool management for high-performance HTTP clients with automatic host-based pooling and connection reuse.
106

107
```python { .api }
108
class PoolManager:
109
    def __init__(self, num_pools=10, headers=None, **connection_pool_kw): ...
110
    def request(self, method: str, url: str, **kw) -> BaseHTTPResponse: ...
111
    def urlopen(self, method: str, url: str, **kw) -> BaseHTTPResponse: ...
112

113
class ProxyManager(PoolManager):
114
    def __init__(self, proxy_url, num_pools=10, headers=None, **connection_pool_kw): ...
115
```
116

117
[Pool Management](./pool-management.md)
118

119
### Connection Pools
120

121
Direct connection pool management for specific hosts with fine-grained control over connection behavior and SSL/TLS settings.
122

123
```python { .api }
124
class HTTPConnectionPool:
125
    def __init__(self, host: str, port=None, timeout=None, maxsize=1, 
126
                block=False, headers=None, retries=None, **conn_kw): ...
127
    def urlopen(self, method: str, url: str, **kw) -> BaseHTTPResponse: ...
128

129
class HTTPSConnectionPool(HTTPConnectionPool):
130
    def __init__(self, host: str, port=None, timeout=None, maxsize=1,
131
                block=False, headers=None, retries=None, **conn_kw): ...
132
```
133

134
[Connection Pools](./connection-pools.md)
135

136
### Response Handling
137

138
Comprehensive HTTP response objects with content decoding, streaming support, and metadata access.
139

140
```python { .api }
141
class HTTPResponse(BaseHTTPResponse):
142
    @property
143
    def status(self) -> int: ...
144
    @property
145
    def headers(self) -> HTTPHeaderDict: ...
146
    @property
147
    def data(self) -> bytes: ...
148
    
149
    def read(self, amt=None, decode_content=None) -> bytes: ...
150
    def stream(self, amt=None, decode_content=None): ...
151
    def json(self) -> any: ...
152
```
153

154
[Response Handling](./response-handling.md)
155

156
### Configuration Objects
157

158
Configuration classes for retry behavior, timeouts, and request customization.
159

160
```python { .api }
161
class Retry:
162
    def __init__(self, total=10, connect=None, read=None, redirect=None,
163
                status=None, other=None, allowed_methods=None,
164
                status_forcelist=None, backoff_factor=0,
165
                backoff_max=120, raise_on_redirect=True,
166
                raise_on_status=True, history=None, **kw): ...
167

168
class Timeout:
169
    def __init__(self, total=None, connect=None, read=None): ...
170
```
171

172
[Configuration](./configuration.md)
173

174
### Utility Functions
175

176
Helper functions for header generation, multipart encoding, URL parsing, logging, and advanced field operations.
177

178
```python { .api }
179
def make_headers(basic_auth=None, proxy_basic_auth=None, user_agent=None,
180
                keep_alive=None, accept_encoding=None) -> dict: ...
181

182
def encode_multipart_formdata(fields, boundary=None) -> tuple[bytes, str]: ...
183

184
def connection_from_url(url: str, **kw) -> HTTPConnectionPool: ...
185

186
def proxy_from_url(url: str, **kw) -> ProxyManager: ...
187

188
def add_stderr_logger(level: int = logging.DEBUG) -> logging.StreamHandler: ...
189

190
def disable_warnings(category: type[Warning] = exceptions.HTTPWarning) -> None: ...
191

192
def is_fp_closed(obj) -> bool: ...
193

194
def format_multipart_header_param(name: str, value: str | bytes) -> str: ...
195
```
196

197
[Utilities](./utilities.md)
198

199
### Exception Handling
200

201
Comprehensive exception hierarchy for handling various HTTP and network errors.
202

203
```python { .api }
204
class HTTPError(Exception): ...
205
class PoolError(HTTPError): ...
206
class RequestError(PoolError): ...
207
class MaxRetryError(RequestError): ...
208
class TimeoutError(HTTPError): ...
209
class SSLError(HTTPError): ...
210
class ProxyError(HTTPError): ...
211
```
212

213
[Exception Handling](./exceptions.md)