0
# Botocore
1

2
Botocore is the foundational Python library that provides low-level, data-driven access to Amazon Web Services (AWS). It serves as the core foundation for both the AWS CLI and boto3, offering direct access to AWS service APIs through a comprehensive client interface. The library handles authentication, request signing, retry logic, and error handling for AWS services, while providing data-driven service models that automatically stay current with AWS API changes.
3

4
## Package Information
5

6
- **Package Name**: botocore
7
- **Language**: Python
8
- **Installation**: `pip install botocore`
9
- **Requirements**: Python >= 3.9
10

11
## Core Imports
12

13
```python
14
import botocore
15
```
16

17
For session-based usage (most common):
18

19
```python
20
from botocore.session import get_session
21
```
22

23
For direct client creation:
24

25
```python
26
from botocore.session import get_session
27
session = get_session()
28
client = session.create_client('s3', region_name='us-east-1')
29
```
30

31
## Basic Usage
32

33
```python
34
from botocore.session import get_session
35

36
# Create a session
37
session = get_session()
38

39
# Create a client for an AWS service
40
s3_client = session.create_client('s3', region_name='us-east-1')
41

42
# Make an API call
43
response = s3_client.list_buckets()
44
print(response['Buckets'])
45

46
# Handle service-specific operations
47
ec2_client = session.create_client('ec2', region_name='us-west-2')
48
instances = ec2_client.describe_instances()
49
```
50

51
## Architecture
52

53
Botocore follows a layered architecture designed for maximum flexibility and extensibility:
54

55
- **Session Layer**: Central configuration and credential management
56
- **Client Layer**: Service-specific API interfaces with method generation from service models
57
- **Model Layer**: Data-driven service definitions that auto-update with AWS API changes
58
- **Transport Layer**: HTTP handling, request signing, and retry logic
59
- **Event System**: Extensible hooks for customizing request/response processing
60

61
This design enables botocore to serve as the foundation for higher-level AWS SDKs while maintaining direct access to all AWS service capabilities.
62

63
## Package-Level API
64

65
```python { .api }
66
def register_initializer(callback: callable) -> None
67
def unregister_initializer(callback: callable) -> None
68
def xform_name(name: str, sep: str = '_') -> str
69

70
# Constants
71
__version__: str
72
UNSIGNED: object
73
ScalarTypes: tuple
74
BOTOCORE_ROOT: str
75
```
76

77
## Capabilities
78

79
### Session Management
80

81
Central session management providing configuration, credentials, and service client creation. Sessions serve as the primary entry point and handle AWS profile management, credential resolution, and service discovery.
82

83
```python { .api }
84
class Session:
85
    def create_client(self, service_name: str, **kwargs) -> BaseClient
86
    def get_credentials(self) -> Credentials
87
    def get_config_variable(self, logical_name: str, methods=None)
88
    def get_available_services(self) -> List[str]
89

90
def get_session(env_vars=None) -> Session
91
```
92

93
[Session Management](./session.md)
94

95
### Client API
96

97
Service clients provide direct access to AWS APIs with dynamically generated methods based on service models. Clients handle request construction, response parsing, and service-specific logic.
98

99
```python { .api }
100
class BaseClient:
101
    def generate_presigned_url(
102
        self, 
103
        ClientMethod: str, 
104
        Params: dict = None, 
105
        ExpiresIn: int = 3600, 
106
        HttpMethod: str = None
107
    ) -> str
108
    def get_paginator(self, operation_name: str) -> Paginator
109
    def get_waiter(self, waiter_name: str) -> Waiter
110
    def can_paginate(self, operation_name: str) -> bool
111

112
class ClientMeta:
113
    service_model: ServiceModel
114
    region_name: str
115
    config: Config
116
```
117

118
[Client API](./client.md)
119

120
### Configuration
121

122
Advanced configuration system for customizing client behavior, timeouts, retry logic, and AWS-specific settings like S3 configuration and proxy handling.
123

124
```python { .api }
125
class Config:
126
    def __init__(
127
        self,
128
        region_name: str = None,
129
        signature_version: str = None,
130
        user_agent: str = None,
131
        connect_timeout: Union[int, float] = 60,
132
        read_timeout: Union[int, float] = 60,
133
        retries: dict = None,
134
        **kwargs
135
    )
136
```
137

138
[Configuration](./config.md)
139

140
### Credentials and Authentication
141

142
Comprehensive credential management supporting multiple AWS authentication methods including environment variables, shared credentials, IAM roles, SSO, and external credential providers.
143

144
```python { .api }
145
class Credentials:
146
    access_key: str
147
    secret_key: str
148
    token: str
149

150
class RefreshableCredentials(Credentials):
151
    def get_frozen_credentials(self) -> Credentials
152
    def refresh_needed(self) -> bool
153

154
class CredentialResolver:
155
    def load_credentials(self) -> Credentials
156
```
157

158
[Credentials](./credentials.md)
159

160
### Exception Handling
161

162
Structured exception hierarchy for handling AWS service errors, connection issues, credential problems, and validation failures with specific exception types for different error categories.
163

164
```python { .api }
165
class BotoCoreError(Exception): pass
166
class ClientError(BotoCoreError): pass
167
class NoCredentialsError(BotoCoreError): pass
168
class ConnectionError(BotoCoreError): pass
169
class ParamValidationError(BotoCoreError): pass
170
```
171

172
[Exception Handling](./exceptions.md)
173

174
### Service Models and Data Types
175

176
Data-driven service models that define AWS service APIs, operations, and data structures. Models automatically update with AWS API changes and provide type definitions for request/response handling.
177

178
```python { .api }
179
class ServiceModel:
180
    @property
181
    def service_name(self) -> str
182
    @property
183
    def operation_names(self) -> List[str]
184
    def operation_model(self, operation_name: str) -> OperationModel
185

186
class OperationModel:
187
    @property
188
    def input_shape(self) -> Shape
189
    @property
190
    def output_shape(self) -> Shape
191
```
192

193
[Service Models](./models.md)
194

195
### Pagination
196

197
Automatic pagination for AWS operations that return large result sets, with built-in iterator support and result aggregation capabilities.
198

199
```python { .api }
200
class Paginator:
201
    def paginate(self, **kwargs) -> PageIterator
202
    @property
203
    def can_paginate(self) -> bool
204

205
class PageIterator:
206
    def build_full_result(self) -> dict
207
    def search(self, expression: str) -> Iterator
208
```
209

210
[Pagination](./pagination.md)
211

212
### Waiters
213

214
Resource state waiters that poll AWS services until resources reach desired states, with configurable polling intervals and timeout handling.
215

216
```python { .api }
217
class Waiter:
218
    def wait(self, **kwargs) -> None
219
    @property
220
    def name(self) -> str
221
```
222

223
[Waiters](./waiters.md)
224

225
### Response Handling
226

227
Streaming response handling for large payloads with support for chunked reading, line iteration, and automatic resource cleanup.
228

229
```python { .api }
230
class StreamingBody:
231
    def read(self, amt: int = None) -> bytes
232
    def iter_lines(self, chunk_size: int = 1024) -> Iterator[bytes]
233
    def iter_chunks(self, chunk_size: int = 1024) -> Iterator[bytes]
234
    def close(self) -> None
235
```
236

237
[Response Handling](./response.md)
238

239
### Event System
240

241
Extensible event system for hooking into request/response lifecycle, enabling custom authentication, logging, monitoring, and request modification.
242

243
```python { .api }
244
class HierarchicalEmitter:
245
    def emit(self, event_name: str, **kwargs) -> List
246
    def register(self, event_name: str, handler: callable, **kwargs) -> None
247
    def unregister(self, event_name: str, handler: callable) -> None
248
```
249

250
[Event System](./events.md)
251

252
### Testing Support
253

254
Built-in stubbing capabilities for testing AWS service interactions with mock responses and error simulation.
255

256
```python { .api }
257
class Stubber:
258
    def add_response(self, method: str, service_response: dict, expected_params=None) -> None
259
    def add_client_error(self, method: str, service_error_code: str, service_message: str) -> None
260
    def activate(self) -> None
261
    def deactivate(self) -> None
262
```
263

264
[Testing Support](./testing.md)