0
# aioboto3
1

2
An asynchronous wrapper for the AWS SDK for Python (boto3), enabling developers to use AWS services in async/await applications. aioboto3 combines the functionality of boto3 with aiobotocore to provide high-level resource APIs that work asynchronously, supporting services like DynamoDB, S3, Kinesis, SSM Parameter Store, and Athena with proper async context management.
3

4
## Package Information
5

6
- **Package Name**: aioboto3
7
- **Language**: Python
8
- **Installation**: `pip install aioboto3`
9

10
### Optional Dependencies
11

12
- **S3 Client-Side Encryption**: `pip install aioboto3[s3cse]`
13
- **Chalice Integration**: `pip install aioboto3[chalice]`
14

15
## Core Imports
16

17
```python
18
import aioboto3
19
```
20

21
For session-based usage (recommended):
22

23
```python
24
from aioboto3 import Session
25
```
26

27
## Basic Usage
28

29
```python
30
import asyncio
31
import aioboto3
32
from boto3.dynamodb.conditions import Key
33

34
async def main():
35
    session = aioboto3.Session()
36
    
37
    # Using DynamoDB resource
38
    async with session.resource('dynamodb', region_name='us-east-1') as dynamo:
39
        table = await dynamo.Table('my-table')
40
        
41
        # Put an item
42
        await table.put_item(Item={'id': '123', 'data': 'hello'})
43
        
44
        # Query items
45
        response = await table.query(
46
            KeyConditionExpression=Key('id').eq('123')
47
        )
48
        print(response['Items'])
49
    
50
    # Using S3 client
51
    async with session.client('s3', region_name='us-east-1') as s3:
52
        # List buckets
53
        response = await s3.list_buckets()
54
        print(response['Buckets'])
55
        
56
        # Upload file
57
        await s3.upload_file('/path/to/file.txt', 'my-bucket', 'file.txt')
58

59
asyncio.run(main())
60
```
61

62
## Architecture
63

64
aioboto3 extends the boto3 architecture with async capabilities:
65

66
- **Session**: Main interface for creating async clients and resources, wraps aiobotocore session
67
- **ResourceCreatorContext**: Async context manager that returns configured service resources
68
- **AIOBoto3ResourceFactory**: Factory for creating async resource instances
69
- **Service Customizations**: Specialized async implementations for DynamoDB, S3, and EC2
70

71
The library maintains compatibility with boto3's interface while adding async context managers for proper resource management and includes async implementations for operations that aren't natively async in boto3.
72

73
## Capabilities
74

75
### Session Management
76

77
Core session functionality for creating and configuring AWS service clients and resources with async context management. The Session class provides both low-level client access and high-level resource access to AWS services.
78

79
```python { .api }
80
class Session:
81
    def __init__(
82
        self,
83
        aws_access_key_id: str = None,
84
        aws_secret_access_key: str = None,
85
        aws_session_token: str = None,
86
        region_name: str = None,
87
        botocore_session = None,
88
        profile_name: str = None,
89
        aws_account_id: str = None
90
    ): ...
91
    
92
    def client(
93
        self,
94
        service_name: str,
95
        region_name: str = None,
96
        api_version: str = None,
97
        use_ssl: bool = True,
98
        verify = None,
99
        endpoint_url: str = None,
100
        aws_access_key_id: str = None,
101
        aws_secret_access_key: str = None,
102
        aws_session_token: str = None,
103
        config = None
104
    ) -> AsyncContextManager: ...
105
    
106
    def resource(
107
        self,
108
        service_name: str,
109
        region_name: str = None,
110
        api_version: str = None,
111
        use_ssl: bool = True,
112
        verify = None,
113
        endpoint_url: str = None,
114
        aws_access_key_id: str = None,
115
        aws_secret_access_key: str = None,
116
        aws_session_token: str = None,
117
        config = None
118
    ) -> ResourceCreatorContext: ...
119
```
120

121
[Session Management](./session-management.md)
122

123
### DynamoDB Operations
124

125
Enhanced async DynamoDB operations including batch writing capabilities and async context management for table resources.
126

127
```python { .api }
128
class CustomTableResource:
129
    def batch_writer(
130
        self,
131
        overwrite_by_pkeys = None,
132
        flush_amount: int = 25,
133
        on_exit_loop_sleep: int = 0
134
    ): ...
135

136
class BatchWriter:
137
    async def __aenter__(self): ...
138
    async def __aexit__(self, exc_type, exc_val, exc_tb): ...
139
    async def put_item(self, Item: dict, **kwargs): ...
140
    async def delete_item(self, Key: dict, **kwargs): ...
141
```
142

143
[DynamoDB](./dynamodb.md)
144

145
### S3 Operations
146

147
Async S3 operations including file transfers, object operations, and optional client-side encryption support.
148

149
```python { .api }
150
async def upload_file(
151
    filename: str,
152
    bucket: str,
153
    key: str,
154
    callback = None,
155
    config = None
156
): ...
157

158
async def download_file(
159
    bucket: str,
160
    key: str,
161
    filename: str,
162
    callback = None,
163
    config = None
164
): ...
165

166
async def upload_fileobj(
167
    fileobj,
168
    bucket: str,
169
    key: str,
170
    callback = None,
171
    config = None
172
): ...
173

174
async def download_fileobj(
175
    bucket: str,
176
    key: str,
177
    fileobj,
178
    callback = None,
179
    config = None
180
): ...
181
```
182

183
[S3 Operations](./s3-operations.md)
184

185
### Client-Side Encryption
186

187
Advanced S3 client-side encryption capabilities for secure data storage with async support.
188

189
```python { .api }
190
class S3CSEClient:
191
    async def __aenter__(self): ...
192
    async def __aexit__(self, exc_type, exc_val, exc_tb): ...
193
    async def put_object(self, **kwargs): ...
194
    async def get_object(self, **kwargs): ...
195

196
class S3CSEBucket:
197
    async def __aenter__(self): ...
198
    async def __aexit__(self, exc_type, exc_val, exc_tb): ...
199

200
class S3CSEObject:
201
    async def __aenter__(self): ...
202
    async def __aexit__(self, exc_type, exc_val, exc_tb): ...
203
```
204

205
[Client-Side Encryption](./client-side-encryption.md)
206

207
### Experimental Features
208

209
Experimental integrations including Chalice framework support for serverless applications.
210

211
```python { .api }
212
class AsyncChalice:
213
    def __init__(
214
        self,
215
        *args,
216
        aioboto3_session: Session = None,
217
        **kwargs
218
    ): ...
219
    
220
    def __call__(self, event, context): ...
221
```
222

223
[Experimental Features](./experimental.md)
224

225
## Types
226

227
```python { .api }
228
from typing import Optional, Callable, BinaryIO, Dict, Any, Union, AsyncContextManager
229
from abc import abstractmethod
230

231
TransferCallback = Callable[[int], None]
232

233
class _AsyncBinaryIO:
234
    @abstractmethod
235
    async def seek(self, offset: int, whence: int = 0) -> int: ...
236
    
237
    @abstractmethod
238
    async def write(self, s: Union[bytes, bytearray]) -> int: ...
239

240
AnyFileObject = Union[_AsyncBinaryIO, BinaryIO]
241

242
class ResourceCreatorContext:
243
    """Async context manager that creates and manages service resources."""
244
    def __init__(
245
        self,
246
        session,
247
        service_name: str,
248
        region_name: str,
249
        api_version: str,
250
        use_ssl: bool,
251
        verify,
252
        endpoint_url: str,
253
        aws_access_key_id: str,
254
        aws_secret_access_key: str,
255
        aws_session_token: str,
256
        config,
257
        resource_model
258
    ): ...
259
    
260
    async def __aenter__(self): ...
261
    async def __aexit__(self, exc_type, exc, tb): ...
262

263
class AIOBoto3ServiceResource:
264
    """Base class for all async service resources."""
265
    async def __aenter__(self) -> 'AIOBoto3ServiceResource': ...
266
    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None: ...
267
```