0
# Boto3
1

2
The AWS SDK for Python, providing both high-level resource-oriented and low-level client-oriented interfaces to AWS services. Boto3 simplifies AWS service integration by handling authentication, request signing, error handling, retries, and pagination automatically, while offering comprehensive coverage of AWS APIs through two programming models: resources for object-oriented workflows and clients for direct service API access.
3

4
## Package Information
5

6
- **Package Name**: boto3
7
- **Language**: Python
8
- **Installation**: `pip install boto3`
9
- **Dependencies**: Requires `botocore` (automatic dependency)
10

11
## Core Imports
12

13
```python
14
import boto3
15
```
16

17
For session-based usage:
18

19
```python
20
from boto3 import Session
21
```
22

23
For exceptions:
24

25
```python
26
from boto3.exceptions import (
27
    Boto3Error, ResourceNotExistsError, UnknownAPIVersionError,
28
    S3TransferFailedError, S3UploadFailedError, DynamoDBOperationNotSupportedError,
29
    DynamoDBNeedsConditionError, DynamoDBNeedsKeyConditionError, RetriesExceededError
30
)
31
```
32

33
For utility functions:
34

35
```python
36
from boto3 import set_stream_logger
37
```
38

39
For DynamoDB conditions:
40

41
```python
42
from boto3.dynamodb.conditions import Key, Attr
43
```
44

45
## Basic Usage
46

47
```python
48
import boto3
49

50
# Create clients using default session (simplest approach)
51
s3_client = boto3.client('s3')
52
dynamodb_client = boto3.client('dynamodb')
53

54
# Create resources using default session  
55
s3_resource = boto3.resource('s3')
56
dynamodb_resource = boto3.resource('dynamodb')
57

58
# List S3 buckets
59
response = s3_client.list_buckets()
60
for bucket in response['Buckets']:
61
    print(bucket['Name'])
62

63
# Work with S3 bucket resource
64
bucket = s3_resource.Bucket('my-bucket')
65
for obj in bucket.objects.all():
66
    print(obj.key)
67

68
# Custom session for specific configuration
69
session = boto3.Session(
70
    aws_access_key_id='ACCESS_KEY',
71
    aws_secret_access_key='SECRET_KEY',
72
    region_name='us-east-1'
73
)
74
ec2 = session.client('ec2')
75
```
76

77
## Architecture
78

79
Boto3 provides a layered architecture optimizing for different use cases:
80

81
- **Session Layer**: Manages credentials, configuration, and service discovery
82
- **Client Layer**: Low-level service access with 1:1 mapping to AWS APIs
83
- **Resource Layer**: Object-oriented abstractions with automatic pagination and waiters
84
- **Service Extensions**: Specialized functionality (S3 transfer, DynamoDB conditions, EC2 tags)
85

86
The session-based design allows both simple default usage and advanced configuration scenarios, while the dual client/resource model accommodates different programming preferences and use cases within the same SDK.
87

88
## Capabilities
89

90
### Session Management
91

92
Core session functionality for managing AWS credentials, regions, and service configuration. Provides both default session convenience and custom session flexibility.
93

94
```python { .api }
95
def client(service_name: str, **kwargs) -> BaseClient: ...
96
def resource(service_name: str, **kwargs) -> ServiceResource: ...
97
def setup_default_session(**kwargs) -> None: ...
98

99
class Session:
100
    def __init__(self, aws_access_key_id: str = None, aws_secret_access_key: str = None, 
101
                 aws_session_token: str = None, region_name: str = None, 
102
                 botocore_session = None, profile_name: str = None, 
103
                 aws_account_id: str = None): ...
104
    def client(self, service_name: str, **kwargs) -> BaseClient: ...
105
    def resource(self, service_name: str, **kwargs) -> ServiceResource: ...
106
```
107

108
[Session Management](./session-management.md)
109

110
### Exception Handling  
111

112
Comprehensive exception hierarchy for handling AWS service errors, resource issues, and SDK-specific problems. Includes base exceptions and service-specific error types.
113

114
```python { .api }
115
class Boto3Error(Exception): ...
116
class ResourceNotExistsError(Boto3Error): ...
117
class UnknownAPIVersionError(Boto3Error): ...
118
class S3TransferFailedError(Boto3Error): ...
119
class S3UploadFailedError(Boto3Error): ...
120
class DynamoDBOperationNotSupportedError(Boto3Error): ...
121
class DynamoDBNeedsConditionError(Boto3Error): ...
122
class DynamoDBNeedsKeyConditionError(Boto3Error): ...
123
class RetriesExceededError(Boto3Error): ...
124
```
125

126
[Exception Handling](./exception-handling.md)
127

128
### DynamoDB Operations
129

130
High-level DynamoDB functionality including condition expressions, type serialization, and table operations. Provides pythonic interfaces for DynamoDB's attribute-value model.
131

132
```python { .api }
133
from boto3.dynamodb.conditions import Key, Attr
134
from boto3.dynamodb.types import Binary, TypeSerializer, TypeDeserializer
135

136
class Key:
137
    def __init__(self, name: str): ...
138
    def eq(self, value) -> ConditionBase: ...
139
    def between(self, low_value, high_value) -> ConditionBase: ...
140

141
class Binary:
142
    def __init__(self, value: bytes): ...
143
```
144

145
[DynamoDB Operations](./dynamodb-operations.md)
146

147
### S3 Transfer Operations
148

149
High-level S3 transfer functionality with automatic multipart handling, progress callbacks, and retry logic. Includes upload/download methods and transfer configuration.
150

151
```python { .api }
152
from boto3.s3.transfer import TransferConfig
153

154
class TransferConfig:
155
    def __init__(self, multipart_threshold: int = 8*1024*1024, 
156
                 max_concurrency: int = 10, **kwargs): ...
157

158
# Methods automatically injected into S3 clients and resources
159
def upload_file(filename: str, bucket: str, key: str, **kwargs) -> None: ...
160
def download_file(bucket: str, key: str, filename: str, **kwargs) -> None: ...
161
```
162

163
[S3 Transfer Operations](./s3-transfer-operations.md)
164

165
### EC2 Operations
166

167
EC2-specific functionality including tag management operations. These methods are automatically injected into EC2 service resources and instances.
168

169
```python { .api }
170
# Methods automatically injected into EC2 service resource and instance resources
171
def create_tags(resources: List[str], tags: List[Dict[str, str]]) -> List: ...
172
def delete_tags(tags: List[Dict[str, str]] = None) -> None: ...
173
```
174

175
[EC2 Operations](./ec2-operations.md)
176

177
### Utility Functions
178

179
SDK utility functions for logging, module imports, and internal functionality. Includes debugging helpers and service context management.
180

181
```python { .api }
182
def set_stream_logger(name: str = 'boto3', level: int = logging.DEBUG, 
183
                     format_string: str = None) -> None: ...
184

185
class ServiceContext:
186
    def __init__(self, service_name: str, service_model, 
187
                 service_waiter_model, resource_json_definitions: dict): ...
188
```
189

190
[Utility Functions](./utility-functions.md)
191

192
## Types
193

194
```python { .api }
195
# Core type aliases
196
from typing import Dict, List, Any, Optional, Union
197
from botocore.client import BaseClient
198
from boto3.resources.base import ServiceResource
199

200
# Configuration types  
201
class Config:
202
    def __init__(self, region_name: str = None, signature_version: str = None,
203
                 s3: Dict[str, Any] = None, retries: Dict[str, Any] = None,
204
                 user_agent_extra: str = None, **kwargs): ...
205

206
# Common response structures
207
ResponseMetadata = Dict[str, Any]  # Contains RequestId, HTTPStatusCode, etc.
208
```