0
# Configuration
1
2
Configuration classes for retry behavior, timeouts, and request customization. These objects provide fine-grained control over urllib3's behavior and error handling strategies.
3
4
## Capabilities
5
6
### Retry Configuration
7
8
Controls retry behavior for various types of failures including connection errors, read timeouts, HTTP status codes, and redirects.
9
10
```python { .api }
11
class Retry:
12
def __init__(self, total=10, connect=None, read=None, redirect=None,
13
status=None, other=None, allowed_methods=None,
14
status_forcelist=None, backoff_factor=0, backoff_max=120,
15
raise_on_redirect=True, raise_on_status=True, history=None, **kw):
16
"""
17
Retry configuration for handling various failure types.
18
19
Parameters:
20
- total: Total number of retry attempts across all failure types
21
- connect: Number of connection-related retry attempts
22
- read: Number of read timeout retry attempts
23
- redirect: Number of redirect retry attempts
24
- status: Number of HTTP status code retry attempts
25
- other: Number of other error retry attempts
26
- allowed_methods: HTTP methods that allow retries (None for default set)
27
- status_forcelist: HTTP status codes that force retries
28
- backoff_factor: Exponential backoff factor between retries
29
- backoff_max: Maximum backoff time in seconds
30
- raise_on_redirect: Whether to raise MaxRetryError on redirect failures
31
- raise_on_status: Whether to raise MaxRetryError on status failures
32
- history: List of previous retry attempts (internal use)
33
"""
34
35
@classmethod
36
def from_int(cls, retries: int) -> 'Retry':
37
"""Create Retry object from integer (backwards compatibility)"""
38
39
def new(self, **kw) -> 'Retry':
40
"""Create new Retry object with updated parameters"""
41
42
def increment(self, method: str = None, url: str = None,
43
response=None, error=None, _pool=None, _stacktrace=None) -> 'Retry':
44
"""
45
Increment retry counter and return new Retry object.
46
47
Raises MaxRetryError if retries exhausted.
48
"""
49
50
def is_retry(self, method: str, status_code: int, has_retry_after: bool = False) -> bool:
51
"""Check if request should be retried based on method and status"""
52
53
def get_backoff_time(self) -> float:
54
"""Calculate backoff time for next retry attempt"""
55
56
def sleep(self, response=None):
57
"""Sleep for calculated backoff time"""
58
```
59
60
### Timeout Configuration
61
62
Controls connection and read timeouts with support for different timeout values for different phases of the request.
63
64
```python { .api }
65
class Timeout:
66
def __init__(self, total=None, connect=None, read=None):
67
"""
68
Timeout configuration for requests.
69
70
Parameters:
71
- total: Total timeout for entire request (float or None)
72
- connect: Timeout for initial connection (float or None)
73
- read: Timeout for reading response data (float or None)
74
"""
75
76
@classmethod
77
def from_float(cls, timeout: float) -> 'Timeout':
78
"""Create Timeout object from float (backwards compatibility)"""
79
80
def clone(self) -> 'Timeout':
81
"""Create copy of timeout configuration"""
82
83
@property
84
def connect_timeout(self) -> float:
85
"""Get effective connect timeout"""
86
87
@property
88
def read_timeout(self) -> float:
89
"""Get effective read timeout"""
90
```
91
92
### Default Configurations
93
94
```python { .api }
95
# Default retry configuration
96
DEFAULT_RETRY = Retry(total=3, redirect=3, connect=3, read=3, status=3)
97
98
# Default timeout (infinite)
99
DEFAULT_TIMEOUT = Timeout(total=None, connect=None, read=None)
100
```
101
102
## Usage Examples
103
104
### Basic Retry Configuration
105
106
```python
107
import urllib3
108
109
# Simple retry configuration
110
retry = urllib3.Retry(total=5)
111
112
http = urllib3.PoolManager(retries=retry)
113
resp = http.request('GET', 'https://httpbin.org/status/500')
114
```
115
116
### Advanced Retry Configuration
117
118
```python
119
import urllib3
120
121
# Comprehensive retry configuration
122
retry = urllib3.Retry(
123
total=5, # Maximum 5 retry attempts total
124
connect=3, # Maximum 3 connection retries
125
read=3, # Maximum 3 read timeout retries
126
redirect=2, # Maximum 2 redirect retries
127
status=3, # Maximum 3 status code retries
128
backoff_factor=0.3, # Exponential backoff: 0.6, 1.2, 2.4, ...
129
backoff_max=120, # Maximum 2 minutes between retries
130
status_forcelist=[429, 500, 502, 503, 504], # Always retry these status codes
131
allowed_methods=['GET', 'PUT', 'DELETE'] # Only retry these methods
132
)
133
134
http = urllib3.PoolManager(retries=retry)
135
resp = http.request('GET', 'https://httpbin.org/status/503')
136
```
137
138
### Timeout Configuration
139
140
```python
141
import urllib3
142
143
# Basic timeout configuration
144
timeout = urllib3.Timeout(total=30.0) # 30 second total timeout
145
146
http = urllib3.PoolManager(timeout=timeout)
147
resp = http.request('GET', 'https://httpbin.org/delay/5')
148
```
149
150
### Granular Timeout Configuration
151
152
```python
153
import urllib3
154
155
# Separate timeouts for different phases
156
timeout = urllib3.Timeout(
157
connect=5.0, # 5 seconds to establish connection
158
read=30.0 # 30 seconds to read response
159
)
160
161
http = urllib3.PoolManager(timeout=timeout)
162
resp = http.request('GET', 'https://httpbin.org/delay/10')
163
```
164
165
### Per-Request Configuration Override
166
167
```python
168
import urllib3
169
170
# Default configuration
171
http = urllib3.PoolManager(
172
retries=urllib3.Retry(total=3),
173
timeout=urllib3.Timeout(total=10.0)
174
)
175
176
# Override for specific request
177
custom_retry = urllib3.Retry(total=10, backoff_factor=1.0)
178
custom_timeout = urllib3.Timeout(total=60.0)
179
180
resp = http.request('GET', 'https://httpbin.org/delay/5',
181
retries=custom_retry,
182
timeout=custom_timeout)
183
```
184
185
### Retry with Custom Status Codes
186
187
```python
188
import urllib3
189
190
# Retry on rate limiting and server errors
191
retry = urllib3.Retry(
192
total=10,
193
status_forcelist=[429, 500, 502, 503, 504],
194
backoff_factor=1.0, # 1 second, 2 seconds, 4 seconds, ...
195
respect_retry_after_header=True # Honor Retry-After header
196
)
197
198
http = urllib3.PoolManager(retries=retry)
199
200
# This will retry on 429 Too Many Requests
201
resp = http.request('GET', 'https://httpbin.org/status/429')
202
```
203
204
### Method-Specific Retry Configuration
205
206
```python
207
import urllib3
208
209
# Only retry safe methods (idempotent operations)
210
retry = urllib3.Retry(
211
total=5,
212
allowed_methods=['GET', 'HEAD', 'PUT', 'DELETE', 'OPTIONS', 'TRACE']
213
)
214
215
http = urllib3.PoolManager(retries=retry)
216
217
# GET request will be retried on failure
218
get_resp = http.request('GET', 'https://httpbin.org/status/500')
219
220
# POST request will NOT be retried (not in allowed_methods)
221
post_resp = http.request('POST', 'https://httpbin.org/status/500',
222
fields={'data': 'value'})
223
```
224
225
### Timeout Edge Cases
226
227
```python
228
import urllib3
229
230
# Very short timeouts for fast failure
231
fast_timeout = urllib3.Timeout(
232
connect=0.5, # 500ms to connect
233
read=1.0 # 1 second to read response
234
)
235
236
# Long timeouts for slow operations
237
slow_timeout = urllib3.Timeout(
238
connect=10.0, # 10 seconds to connect
239
read=300.0 # 5 minutes to read response
240
)
241
242
http = urllib3.PoolManager()
243
244
# Fast timeout for health check
245
try:
246
health_resp = http.request('GET', 'https://api.example.com/health',
247
timeout=fast_timeout)
248
except urllib3.exceptions.TimeoutError:
249
print("Service unhealthy - fast timeout")
250
251
# Slow timeout for data processing endpoint
252
data_resp = http.request('POST', 'https://api.example.com/process-data',
253
json={'large': 'dataset'},
254
timeout=slow_timeout)
255
```
256
257
### Combining Retry and Timeout
258
259
```python
260
import urllib3
261
262
# Aggressive retry with reasonable timeouts
263
retry_config = urllib3.Retry(
264
total=10,
265
connect=5,
266
read=5,
267
backoff_factor=0.5,
268
status_forcelist=[429, 500, 502, 503, 504]
269
)
270
271
timeout_config = urllib3.Timeout(
272
connect=3.0,
273
read=10.0
274
)
275
276
http = urllib3.PoolManager(
277
retries=retry_config,
278
timeout=timeout_config
279
)
280
281
# Will retry up to 10 times with exponential backoff
282
# Each attempt has 3s connect + 10s read timeout
283
resp = http.request('GET', 'https://unreliable-api.example.com/data')
284
```
285
286
### Disabling Retries
287
288
```python
289
import urllib3
290
291
# Disable all retries
292
no_retry = urllib3.Retry(total=False)
293
294
# Or use integer 0
295
no_retry = urllib3.Retry(0)
296
297
http = urllib3.PoolManager(retries=no_retry)
298
299
# Request will fail immediately on any error
300
try:
301
resp = http.request('GET', 'https://httpbin.org/status/500')
302
except urllib3.exceptions.MaxRetryError as e:
303
print(f"Request failed: {e}")
304
```
305
306
## Configuration Best Practices
307
308
### Production Settings
309
310
```python
311
import urllib3
312
313
# Robust production configuration
314
production_retry = urllib3.Retry(
315
total=5, # Reasonable retry limit
316
connect=3, # Network issues are common
317
read=3, # Server processing issues
318
redirect=3, # Handle redirects
319
backoff_factor=0.3, # Exponential backoff
320
status_forcelist=[429, 502, 503, 504], # Temporary server issues
321
allowed_methods=['GET', 'HEAD', 'PUT', 'DELETE'] # Safe methods only
322
)
323
324
production_timeout = urllib3.Timeout(
325
connect=5.0, # Reasonable connection time
326
read=30.0 # Allow time for processing
327
)
328
329
http = urllib3.PoolManager(
330
retries=production_retry,
331
timeout=production_timeout
332
)
333
```
334
335
### Development/Testing Settings
336
337
```python
338
import urllib3
339
340
# Fast-fail configuration for development
341
dev_retry = urllib3.Retry(total=1) # Minimal retries
342
dev_timeout = urllib3.Timeout(total=5.0) # Short timeout
343
344
http = urllib3.PoolManager(
345
retries=dev_retry,
346
timeout=dev_timeout
347
)
348
```