0
# Session Management
1
2
Central session management providing configuration, credentials, and service client creation. Sessions serve as the primary entry point to botocore and handle AWS profile management, credential resolution, and service discovery.
3
4
## Capabilities
5
6
### Session Creation
7
8
Create and configure botocore sessions for AWS service access.
9
10
```python { .api }
11
def get_session(env_vars: dict = None) -> Session:
12
"""
13
Create a new botocore session.
14
15
Args:
16
env_vars: Custom environment variables mapping
17
18
Returns:
19
Session: Configured botocore session
20
"""
21
```
22
23
### Core Session Class
24
25
Primary interface for botocore functionality, managing configuration and service clients.
26
27
```python { .api }
28
class Session:
29
def __init__(
30
self,
31
session_vars: dict = None,
32
event_hooks: HierarchicalEmitter = None,
33
include_builtin_handlers: bool = True,
34
profile: str = None
35
):
36
"""
37
Initialize a botocore session.
38
39
Args:
40
session_vars: Session variable overrides
41
event_hooks: Custom event emitter
42
include_builtin_handlers: Include default event handlers
43
profile: AWS profile name to use
44
"""
45
```
46
47
### Profile and Configuration Management
48
49
Manage AWS profiles and configuration settings.
50
51
```python { .api }
52
class Session:
53
@property
54
def available_profiles(self) -> List[str]:
55
"""List of available AWS configuration profiles."""
56
57
@property
58
def profile(self) -> str:
59
"""Current AWS profile name."""
60
61
def get_config_variable(
62
self,
63
logical_name: str,
64
methods: List[str] = None
65
) -> Any:
66
"""
67
Retrieve configuration variable value.
68
69
Args:
70
logical_name: Configuration variable name
71
methods: Configuration methods to check
72
73
Returns:
74
Configuration value or None
75
"""
76
77
def set_config_variable(self, logical_name: str, value: Any) -> None:
78
"""
79
Set configuration variable value.
80
81
Args:
82
logical_name: Configuration variable name
83
value: Value to set
84
"""
85
86
def instance_variables(self) -> dict:
87
"""Get mapping of instance variables."""
88
89
def get_scoped_config(self) -> dict:
90
"""Get profile-specific configuration."""
91
92
def full_config(self) -> dict:
93
"""Get complete configuration dictionary."""
94
```
95
96
### Client Configuration
97
98
Manage default client configuration settings.
99
100
```python { .api }
101
class Session:
102
def get_default_client_config(self) -> Config:
103
"""Get default client configuration."""
104
105
def set_default_client_config(self, client_config: Config) -> None:
106
"""
107
Set default client configuration.
108
109
Args:
110
client_config: Configuration to use as default
111
"""
112
```
113
114
### Credential Management
115
116
Access and manage AWS credentials through the session.
117
118
```python { .api }
119
class Session:
120
def get_credentials(self) -> Credentials:
121
"""
122
Get current AWS credentials.
123
124
Returns:
125
Credentials: Current AWS credentials or None
126
"""
127
128
def get_auth_token(self, **kwargs) -> str:
129
"""
130
Get authentication token for services requiring token-based auth.
131
132
Returns:
133
Authentication token string
134
"""
135
```
136
137
### Service Discovery
138
139
Discover and access AWS service information.
140
141
```python { .api }
142
class Session:
143
def get_available_services(self) -> List[str]:
144
"""List of available AWS service names."""
145
146
def get_service_model(
147
self,
148
service_name: str,
149
api_version: str = None
150
) -> ServiceModel:
151
"""
152
Get service model for AWS service.
153
154
Args:
155
service_name: AWS service name (e.g., 's3', 'ec2')
156
api_version: Specific API version
157
158
Returns:
159
ServiceModel: Service model object
160
"""
161
162
def get_waiter_model(
163
self,
164
service_name: str,
165
api_version: str = None
166
) -> WaiterModel:
167
"""
168
Get waiter model for AWS service.
169
170
Args:
171
service_name: AWS service name
172
api_version: Specific API version
173
174
Returns:
175
WaiterModel: Waiter model object
176
"""
177
178
def get_paginator_model(
179
self,
180
service_name: str,
181
api_version: str = None
182
) -> PaginatorModel:
183
"""
184
Get paginator model for AWS service.
185
186
Args:
187
service_name: AWS service name
188
api_version: Specific API version
189
190
Returns:
191
PaginatorModel: Paginator model object
192
"""
193
194
def get_service_data(
195
self,
196
service_name: str,
197
api_version: str = None
198
) -> dict:
199
"""
200
Get raw service data dictionary.
201
202
Args:
203
service_name: AWS service name
204
api_version: Specific API version
205
206
Returns:
207
dict: Raw service definition data
208
"""
209
210
def get_data(self, data_path: str) -> Any:
211
"""
212
Get data from service definitions.
213
214
Args:
215
data_path: Path to data (e.g., 'endpoints', 'partitions')
216
217
Returns:
218
Data from service definitions
219
"""
220
```
221
222
### Client Creation
223
224
Create service-specific clients for AWS API access.
225
226
```python { .api }
227
class Session:
228
def create_client(
229
self,
230
service_name: str,
231
region_name: str = None,
232
api_version: str = None,
233
use_ssl: bool = True,
234
verify: Union[bool, str] = None,
235
endpoint_url: str = None,
236
aws_access_key_id: str = None,
237
aws_secret_access_key: str = None,
238
aws_session_token: str = None,
239
config: Config = None
240
) -> BaseClient:
241
"""
242
Create AWS service client.
243
244
Args:
245
service_name: AWS service name (e.g., 's3', 'ec2')
246
region_name: AWS region name
247
api_version: Specific API version
248
use_ssl: Use SSL/TLS for requests
249
verify: SSL certificate verification
250
endpoint_url: Custom service endpoint URL
251
aws_access_key_id: AWS access key ID
252
aws_secret_access_key: AWS secret access key
253
aws_session_token: AWS session token
254
config: Advanced client configuration
255
256
Returns:
257
BaseClient: AWS service client
258
"""
259
```
260
261
### Logging Configuration
262
263
Configure logging for debugging and monitoring.
264
265
```python { .api }
266
class Session:
267
@property
268
def user_agent(self) -> str:
269
"""User agent string for requests."""
270
271
def set_debug_logger(self, logger_name: str = 'botocore') -> None:
272
"""
273
Configure debug logging.
274
275
Args:
276
logger_name: Logger name to configure
277
"""
278
279
def set_file_logger(
280
self,
281
log_level: int,
282
path: str,
283
logger_name: str = 'botocore'
284
) -> None:
285
"""
286
Configure file-based logging.
287
288
Args:
289
log_level: Logging level (e.g., logging.DEBUG)
290
path: Log file path
291
logger_name: Logger name to configure
292
"""
293
```
294
295
### Event System Integration
296
297
Access and manage the session's event system.
298
299
```python { .api }
300
class Session:
301
def emit(self, event_name: str, **kwargs) -> List:
302
"""
303
Emit event to registered handlers.
304
305
Args:
306
event_name: Event name to emit
307
**kwargs: Event data
308
309
Returns:
310
List of handler responses
311
"""
312
313
def emit_first_non_none_response(
314
self,
315
event_name: str,
316
**kwargs
317
) -> Any:
318
"""
319
Emit event and return first non-None response.
320
321
Args:
322
event_name: Event name to emit
323
**kwargs: Event data
324
325
Returns:
326
First non-None handler response
327
"""
328
```
329
330
### Component Management
331
332
Register and retrieve session components.
333
334
```python { .api }
335
class Session:
336
def get_component(self, name: str) -> Any:
337
"""
338
Get registered component by name.
339
340
Args:
341
name: Component name
342
343
Returns:
344
Registered component
345
"""
346
347
def register_component(self, name: str, component: Any) -> None:
348
"""
349
Register session component.
350
351
Args:
352
name: Component name
353
component: Component to register
354
"""
355
356
def lazy_register_component(
357
self,
358
name: str,
359
component: Any
360
) -> None:
361
"""
362
Register component with lazy initialization.
363
364
Args:
365
name: Component name
366
component: Component factory or instance
367
"""
368
```
369
370
### Region and Partition Management
371
372
Access AWS region and partition information.
373
374
```python { .api }
375
class Session:
376
def get_available_partitions(self) -> List[str]:
377
"""List of available AWS partitions."""
378
379
def get_partition_for_region(self, region_name: str) -> str:
380
"""
381
Get AWS partition for region.
382
383
Args:
384
region_name: AWS region name
385
386
Returns:
387
str: AWS partition name
388
"""
389
```
390
391
## Usage Examples
392
393
### Basic Session Usage
394
395
```python
396
from botocore.session import get_session
397
398
# Create session with default configuration
399
session = get_session()
400
401
# Create session with specific profile
402
session = get_session()
403
session.profile = 'myprofile'
404
405
# Create clients for different services
406
s3 = session.create_client('s3', region_name='us-east-1')
407
ec2 = session.create_client('ec2', region_name='us-west-2')
408
```
409
410
### Configuration Management
411
412
```python
413
# Get configuration values
414
region = session.get_config_variable('region')
415
profile = session.profile
416
417
# Set configuration
418
session.set_config_variable('region', 'us-west-1')
419
420
# Access complete configuration
421
config = session.full_config()
422
```
423
424
### Service Discovery
425
426
```python
427
# List available services
428
services = session.get_available_services()
429
print(f"Available services: {len(services)}")
430
431
# Get service model
432
s3_model = session.get_service_model('s3')
433
operations = s3_model.operation_names
434
```