0
# Session Management
1

2
Core session functionality for managing AWS credentials, regions, and service configuration. Sessions provide both simple default usage patterns and advanced configuration scenarios, serving as the foundation for all AWS service interactions in boto3.
3

4
## Capabilities
5

6
### Default Session Functions
7

8
Convenience functions that operate on the global default session, providing the simplest way to create AWS service clients and resources.
9

10
```python { .api }
11
def client(service_name: str, region_name: str = None, api_version: str = None,
12
           use_ssl: bool = True, verify: Union[bool, str] = None, 
13
           endpoint_url: str = None, aws_access_key_id: str = None,
14
           aws_secret_access_key: str = None, aws_session_token: str = None,
15
           config = None, aws_account_id: str = None) -> BaseClient:
16
    """
17
    Create a low-level service client by name using the default session.
18
    
19
    Parameters:
20
    - service_name: AWS service name (e.g., 's3', 'ec2', 'dynamodb')
21
    - region_name: AWS region name (e.g., 'us-east-1')  
22
    - api_version: Specific API version to use
23
    - use_ssl: Whether to use SSL/TLS
24
    - verify: SSL certificate verification (True/False or path to CA bundle)
25
    - endpoint_url: Custom endpoint URL
26
    - aws_access_key_id: Override access key ID
27
    - aws_secret_access_key: Override secret access key
28
    - aws_session_token: Override session token
29
    - config: Advanced client configuration (botocore.client.Config)
30
    - aws_account_id: AWS account ID
31
    
32
    Returns:
33
    Low-level service client instance
34
    """
35

36
def resource(service_name: str, region_name: str = None, api_version: str = None,
37
             use_ssl: bool = True, verify: Union[bool, str] = None,
38
             endpoint_url: str = None, aws_access_key_id: str = None,
39
             aws_secret_access_key: str = None, aws_session_token: str = None,
40
             config = None) -> ServiceResource:
41
    """
42
    Create a resource service client by name using the default session.
43
    
44
    Parameters:
45
    - service_name: AWS service name (e.g., 's3', 'ec2', 'dynamodb')
46
    - region_name: AWS region name
47
    - api_version: Specific API version to use
48
    - use_ssl: Whether to use SSL/TLS
49
    - verify: SSL certificate verification
50
    - endpoint_url: Custom endpoint URL
51
    - aws_access_key_id: Override access key ID
52
    - aws_secret_access_key: Override secret access key
53
    - aws_session_token: Override session token
54
    - config: Advanced client configuration
55
    
56
    Returns:
57
    High-level service resource instance
58
    """
59

60
def setup_default_session(aws_access_key_id: str = None, 
61
                         aws_secret_access_key: str = None,
62
                         aws_session_token: str = None, region_name: str = None,
63
                         botocore_session = None, profile_name: str = None,
64
                         aws_account_id: str = None) -> None:
65
    """
66
    Set up a default session with custom parameters.
67
    
68
    Parameters:
69
    - aws_access_key_id: AWS access key ID
70
    - aws_secret_access_key: AWS secret access key  
71
    - aws_session_token: AWS session token for temporary credentials
72
    - region_name: Default AWS region
73
    - botocore_session: Existing botocore session to use
74
    - profile_name: AWS credentials profile name
75
    - aws_account_id: AWS account ID
76
    """
77
```
78

79
### Session Class
80

81
The Session class provides explicit credential and configuration management, allowing multiple sessions with different settings within the same application.
82

83
```python { .api }
84
class Session:
85
    def __init__(self, aws_access_key_id: str = None, 
86
                 aws_secret_access_key: str = None,
87
                 aws_session_token: str = None, region_name: str = None,
88
                 botocore_session = None, profile_name: str = None,
89
                 aws_account_id: str = None):
90
        """
91
        Initialize a new session with AWS credentials and configuration.
92
        
93
        Parameters:
94
        - aws_access_key_id: AWS access key ID
95
        - aws_secret_access_key: AWS secret access key
96
        - aws_session_token: AWS session token for temporary credentials
97
        - region_name: Default AWS region for this session
98
        - botocore_session: Use existing botocore session instead of creating new one
99
        - profile_name: AWS credentials profile name to use
100
        - aws_account_id: AWS account ID
101
        """
102
    
103
    @property
104
    def profile_name(self) -> str:
105
        """The read-only profile name (returns 'default' if none specified)."""
106
    
107
    @property  
108
    def region_name(self) -> str:
109
        """The read-only region name for this session."""
110
    
111
    @property
112
    def events(self):
113
        """The event emitter for this session."""
114
    
115
    @property
116
    def available_profiles(self) -> List[str]:
117
        """List of available AWS credential profiles."""
118
    
119
    def client(self, service_name: str, region_name: str = None, 
120
               api_version: str = None, use_ssl: bool = True,
121
               verify: Union[bool, str] = None, endpoint_url: str = None,
122
               aws_access_key_id: str = None, aws_secret_access_key: str = None,
123
               aws_session_token: str = None, config = None,
124
               aws_account_id: str = None) -> BaseClient:
125
        """Create a low-level service client using this session."""
126
    
127
    def resource(self, service_name: str, region_name: str = None,
128
                 api_version: str = None, use_ssl: bool = True,
129
                 verify: Union[bool, str] = None, endpoint_url: str = None,
130
                 aws_access_key_id: str = None, aws_secret_access_key: str = None,
131
                 aws_session_token: str = None, config = None) -> ServiceResource:
132
        """Create a resource service client using this session."""
133
```
134

135
### Service Discovery Methods
136

137
Methods for discovering available AWS services, regions, and API versions supported by the current boto3 installation.
138

139
```python { .api }
140
class Session:
141
    def get_available_services(self) -> List[str]:
142
        """
143
        Get list of AWS services available for low-level client creation.
144
        
145
        Returns:
146
        List of service names (e.g., ['s3', 'ec2', 'dynamodb', ...])
147
        """
148
    
149
    def get_available_resources(self) -> List[str]:
150
        """
151
        Get list of AWS services available for resource creation.
152
        
153
        Returns:
154
        List of service names that support resource interfaces
155
        """
156
    
157
    def get_available_partitions(self) -> List[str]:
158
        """
159
        Get list of available AWS partitions.
160
        
161
        Returns:
162
        List of partition names (e.g., ['aws', 'aws-cn', 'aws-us-gov'])
163
        """
164
    
165
    def get_available_regions(self, service_name: str, partition_name: str = 'aws',
166
                             allow_non_regional: bool = False) -> List[str]:
167
        """
168
        Get list of regions where a service is available.
169
        
170
        Parameters:
171
        - service_name: AWS service name (e.g., 's3')
172
        - partition_name: AWS partition name
173
        - allow_non_regional: Include non-regional endpoints
174
        
175
        Returns:
176
        List of region names (e.g., ['us-east-1', 'us-west-2', ...])
177
        """
178
    
179
    def get_partition_for_region(self, region_name: str) -> str:
180
        """
181
        Get the partition name for a specific region.
182
        
183
        Parameters:
184
        - region_name: AWS region name
185
        
186
        Returns:
187
        Partition name (e.g., 'aws')
188
        """
189
```
190

191
### Credential Management
192

193
Methods for accessing and managing AWS credentials within a session.
194

195
```python { .api }
196
class Session:
197
    def get_credentials(self):
198
        """
199
        Get the credentials object for this session.
200
        
201
        Returns:
202
        botocore.credentials.Credentials object with access keys and tokens
203
        """
204
```
205

206
## Usage Examples
207

208
### Basic Default Session Usage
209

210
```python
211
import boto3
212

213
# Create clients using the default session
214
s3 = boto3.client('s3')
215
dynamodb = boto3.resource('dynamodb', region_name='us-west-2')
216

217
# List S3 buckets
218
buckets = s3.list_buckets()
219
```
220

221
### Custom Session Configuration
222

223
```python
224
from boto3 import Session
225

226
# Create session with specific credentials and region
227
session = Session(
228
    aws_access_key_id='AKIAEXAMPLE',
229
    aws_secret_access_key='secret',
230
    region_name='eu-west-1'
231
)
232

233
# Create services using the custom session
234
s3 = session.client('s3')
235
ec2 = session.resource('ec2')
236
```
237

238
### Profile-based Session
239

240
```python
241
from boto3 import Session
242

243
# Use a specific AWS credentials profile
244
session = Session(profile_name='production')
245
dynamodb = session.resource('dynamodb')
246
```
247

248
### Service Discovery
249

250
```python
251
import boto3
252

253
session = boto3.Session()
254

255
# Discover available services
256
services = session.get_available_services()
257
print(f"Available services: {services[:5]}...")  # First 5 services
258

259
# Find regions for S3
260
s3_regions = session.get_available_regions('s3')
261
print(f"S3 regions: {s3_regions[:3]}...")  # First 3 regions
262
```