0
# Configuration
1
2
Advanced configuration system for customizing client behavior, timeouts, retry logic, and AWS-specific settings. The Config class provides fine-grained control over how botocore clients interact with AWS services.
3
4
## Capabilities
5
6
### Configuration Class
7
8
Primary configuration class for customizing client behavior.
9
10
```python { .api }
11
class Config:
12
def __init__(
13
self,
14
region_name: str = None,
15
signature_version: str = None,
16
user_agent: str = None,
17
user_agent_extra: str = None,
18
user_agent_appid: str = None,
19
connect_timeout: Union[int, float] = 60,
20
read_timeout: Union[int, float] = 60,
21
parameter_validation: bool = True,
22
max_pool_connections: int = 10,
23
proxies: dict = None,
24
proxies_config: dict = None,
25
s3: dict = None,
26
retries: dict = None,
27
tcp_keepalive: bool = False,
28
inject_host_prefix: bool = True,
29
disable_request_compression: bool = False,
30
request_min_compression_size_bytes: int = 10240,
31
**kwargs
32
):
33
"""
34
Initialize client configuration.
35
36
Args:
37
region_name: AWS region name override
38
signature_version: AWS signature version ('v2', 'v4', 's3v4')
39
user_agent: Custom user agent string
40
user_agent_extra: Additional user agent information
41
user_agent_appid: Application ID for user agent
42
connect_timeout: Connection timeout in seconds (default: 60)
43
read_timeout: Read timeout in seconds (default: 60)
44
parameter_validation: Enable parameter validation (default: True)
45
max_pool_connections: Maximum HTTP connection pool size (default: 10)
46
proxies: Proxy configuration dictionary
47
proxies_config: Advanced proxy configuration
48
s3: S3-specific configuration options
49
retries: Retry configuration dictionary
50
tcp_keepalive: Enable TCP keepalive (default: False)
51
inject_host_prefix: Enable host prefix injection (default: True)
52
disable_request_compression: Disable request compression
53
request_min_compression_size_bytes: Minimum size for compression
54
"""
55
```
56
57
### Configuration Properties
58
59
Access configuration values after initialization.
60
61
```python { .api }
62
class Config:
63
@property
64
def region_name(self) -> str:
65
"""AWS region name."""
66
67
@property
68
def signature_version(self) -> str:
69
"""AWS signature version."""
70
71
@property
72
def user_agent(self) -> str:
73
"""User agent string."""
74
75
@property
76
def connect_timeout(self) -> Union[int, float]:
77
"""Connection timeout in seconds."""
78
79
@property
80
def read_timeout(self) -> Union[int, float]:
81
"""Read timeout in seconds."""
82
83
@property
84
def max_pool_connections(self) -> int:
85
"""Maximum connection pool size."""
86
87
@property
88
def parameter_validation(self) -> bool:
89
"""Parameter validation enabled status."""
90
```
91
92
### Configuration Merging
93
94
Merge configuration objects for inheritance and override behavior.
95
96
```python { .api }
97
class Config:
98
def merge(self, other_config: 'Config') -> 'Config':
99
"""
100
Merge with another configuration.
101
102
Args:
103
other_config: Configuration to merge with
104
105
Returns:
106
Config: New merged configuration
107
"""
108
```
109
110
## Configuration Options
111
112
### Network Configuration
113
114
Configure network-related settings for HTTP requests.
115
116
```python
117
# Connection and read timeouts
118
config = Config(
119
connect_timeout=30, # 30 seconds to connect
120
read_timeout=60, # 60 seconds to read response
121
)
122
123
# Connection pooling
124
config = Config(
125
max_pool_connections=20, # Allow up to 20 concurrent connections
126
tcp_keepalive=True # Enable TCP keepalive
127
)
128
```
129
130
### Proxy Configuration
131
132
Configure proxy settings for HTTP requests.
133
134
```python
135
# Basic proxy configuration
136
config = Config(
137
proxies={
138
'http': 'http://proxy.example.com:8080',
139
'https': 'https://proxy.example.com:8080'
140
}
141
)
142
143
# Advanced proxy configuration with authentication
144
config = Config(
145
proxies={
146
'http': 'http://user:pass@proxy.example.com:8080',
147
'https': 'https://user:pass@proxy.example.com:8080'
148
},
149
proxies_config={
150
'proxy_ca_bundle': '/path/to/ca-bundle.pem',
151
'proxy_client_cert': '/path/to/client.pem',
152
'proxy_use_forwarding_for_https': True
153
}
154
)
155
```
156
157
### Retry Configuration
158
159
Configure automatic retry behavior for failed requests.
160
161
```python
162
# Standard retry configuration
163
config = Config(
164
retries={
165
'max_attempts': 5, # Maximum retry attempts
166
'mode': 'standard' # Use standard retry mode
167
}
168
)
169
170
# Adaptive retry configuration
171
config = Config(
172
retries={
173
'max_attempts': 10,
174
'mode': 'adaptive' # Use adaptive retry mode
175
}
176
)
177
178
# Legacy retry configuration
179
config = Config(
180
retries={
181
'max_attempts': 3,
182
'mode': 'legacy'
183
}
184
)
185
```
186
187
### S3-Specific Configuration
188
189
Configure S3-specific client behavior.
190
191
```python
192
config = Config(
193
s3={
194
'addressing_style': 'virtual', # Use virtual-hosted-style URLs
195
'signature_version': 's3v4', # Use S3 Signature Version 4
196
'use_accelerate_endpoint': True, # Use S3 Transfer Acceleration
197
'use_dualstack_endpoint': True, # Use dual-stack endpoints
198
'payload_signing_enabled': False, # Disable payload signing
199
'chunked_encoding': True, # Enable chunked encoding
200
'us_east_1_regional_endpoint': 'regional' # Use regional endpoint
201
}
202
)
203
```
204
205
### User Agent Configuration
206
207
Customize user agent strings for request identification.
208
209
```python
210
# Custom user agent
211
config = Config(
212
user_agent='MyApplication/1.0',
213
user_agent_extra='Additional/Info',
214
user_agent_appid='my-app-id'
215
)
216
```
217
218
### Validation and Compression
219
220
Configure parameter validation and request compression.
221
222
```python
223
config = Config(
224
parameter_validation=False, # Disable parameter validation
225
disable_request_compression=True, # Disable compression
226
request_min_compression_size_bytes=5120 # Set compression threshold
227
)
228
```
229
230
### Security Configuration
231
232
Configure authentication and signature settings.
233
234
```python
235
# Signature version configuration
236
config = Config(
237
signature_version='v4' # Use AWS Signature Version 4
238
)
239
240
# Service-specific signature configuration
241
config = Config(
242
signature_version='s3v4' # Use S3-specific signature version
243
)
244
```
245
246
## Usage Examples
247
248
### Basic Configuration
249
250
```python
251
from botocore.config import Config
252
from botocore.session import get_session
253
254
# Create configuration
255
config = Config(
256
region_name='us-west-2',
257
connect_timeout=30,
258
read_timeout=30,
259
max_pool_connections=20
260
)
261
262
# Apply to client
263
session = get_session()
264
client = session.create_client('s3', config=config)
265
```
266
267
### Production Configuration
268
269
```python
270
# Production-ready configuration
271
production_config = Config(
272
# Network settings
273
connect_timeout=10,
274
read_timeout=60,
275
max_pool_connections=50,
276
tcp_keepalive=True,
277
278
# Retry settings
279
retries={
280
'max_attempts': 5,
281
'mode': 'adaptive'
282
},
283
284
# User agent
285
user_agent_appid='myapp-production',
286
287
# Validation
288
parameter_validation=True
289
)
290
```
291
292
### Service-Specific Configuration
293
294
```python
295
# S3-optimized configuration
296
s3_config = Config(
297
s3={
298
'addressing_style': 'virtual',
299
'signature_version': 's3v4',
300
'use_accelerate_endpoint': True,
301
'payload_signing_enabled': False
302
},
303
connect_timeout=60,
304
read_timeout=300, # Longer timeout for large uploads
305
max_pool_connections=25
306
)
307
308
s3_client = session.create_client('s3', config=s3_config)
309
```
310
311
### Development Configuration
312
313
```python
314
# Development configuration with debugging
315
dev_config = Config(
316
# Shorter timeouts for faster feedback
317
connect_timeout=5,
318
read_timeout=30,
319
320
# More aggressive retries
321
retries={
322
'max_attempts': 2,
323
'mode': 'standard'
324
},
325
326
# Enable validation for development
327
parameter_validation=True,
328
329
# Custom user agent for development
330
user_agent_extra='Development/Testing'
331
)
332
```
333
334
### Configuration Merging
335
336
```python
337
# Base configuration
338
base_config = Config(
339
connect_timeout=30,
340
read_timeout=60,
341
parameter_validation=True
342
)
343
344
# Service-specific overrides
345
s3_overrides = Config(
346
read_timeout=300, # Longer timeout for S3
347
s3={'addressing_style': 'virtual'}
348
)
349
350
# Merge configurations
351
final_config = base_config.merge(s3_overrides)
352
```
353
354
### Environment-Specific Configuration
355
356
```python
357
import os
358
359
# Configuration based on environment
360
def get_config():
361
if os.environ.get('ENVIRONMENT') == 'production':
362
return Config(
363
retries={'max_attempts': 5, 'mode': 'adaptive'},
364
connect_timeout=10,
365
max_pool_connections=50
366
)
367
else:
368
return Config(
369
retries={'max_attempts': 2, 'mode': 'standard'},
370
connect_timeout=5,
371
max_pool_connections=10
372
)
373
374
config = get_config()
375
client = session.create_client('dynamodb', config=config)
376
```