0
# Aliyun Python SDK Core
1

2
The core module of Aliyun Python SDK providing authentication, request handling, and API communication for Alibaba Cloud services. This package serves as the foundation for all other Alibaba Cloud Python SDK service modules, offering standardized client initialization, credential management, request/response processing, and error handling.
3

4
## Package Information
5

6
- **Package Name**: aliyun-python-sdk-core
7
- **Language**: Python
8
- **Installation**: `pip install aliyun-python-sdk-core`
9
- **Python Requirements**: >= 3.7
10

11
## Core Imports
12

13
```python
14
from aliyunsdkcore.client import AcsClient
15
from aliyunsdkcore.request import RpcRequest, RoaRequest, CommonRequest
16
from aliyunsdkcore.auth.credentials import AccessKeyCredential, StsTokenCredential, RamRoleArnCredential, EcsRamRoleCredential, RsaKeyPairCredential
17
from aliyunsdkcore.acs_exception.exceptions import ClientException, ServerException
18
```
19

20
## Basic Usage
21

22
```python
23
from aliyunsdkcore.client import AcsClient
24
from aliyunsdkcore.auth.credentials import AccessKeyCredential
25
from aliyunsdkcore.request import CommonRequest
26

27
# Initialize client with credentials
28
credential = AccessKeyCredential("your-access-key-id", "your-access-key-secret")
29
client = AcsClient(credential=credential, region_id="cn-hangzhou")
30

31
# Create a request
32
request = CommonRequest()
33
request.set_method("POST")
34
request.set_domain("ecs.cn-hangzhou.aliyuncs.com")
35
request.set_version("2014-05-26")
36
request.set_action_name("DescribeInstances")
37

38
# Execute request
39
response = client.do_action_with_exception(request)
40
print(response.decode('utf-8'))
41
```
42

43
## Architecture
44

45
The SDK follows a layered architecture:
46

47
- **Client Layer**: `AcsClient` manages API communication, authentication, and retry logic
48
- **Request Layer**: `AcsRequest` and subclasses (`RpcRequest`, `RoaRequest`, `CommonRequest`) define API request structure
49
- **Authentication Layer**: Multiple credential types and signature methods for secure API access
50
- **Transport Layer**: HTTP request/response handling with connection pooling and timeout management
51
- **Exception Layer**: Structured error handling for client and server-side issues
52
- **Utility Layer**: Parameter validation, encoding, and helper functions
53

54
## Capabilities
55

56
### Client Management
57

58
Core client functionality for API communication with Alibaba Cloud services, including authentication, request execution, retry logic, and response handling.
59

60
```python { .api }
61
class AcsClient:
62
    def __init__(
63
        self,
64
        ak=None,
65
        secret=None,
66
        region_id="cn-hangzhou",
67
        credential=None,
68
        **kwargs
69
    ): ...
70
    
71
    def do_action(self, acs_request): ...
72
    def do_action_with_exception(self, acs_request): ...
73
```
74

75
[Client Management](./client-management.md)
76

77
### Request Types
78

79
Different request types for various Alibaba Cloud API styles, including RPC-style requests, RESTful ROA requests, and flexible common requests.
80

81
```python { .api }
82
class AcsRequest:
83
    def __init__(self, product, version=None, action_name=None, **kwargs): ...
84
    def set_query_params(self, params): ...
85
    def set_content(self, content): ...
86

87
class RpcRequest(AcsRequest): ...
88
class RoaRequest(AcsRequest): ...
89
class CommonRequest(AcsRequest): ...
90
```
91

92
[Request Types](./request-types.md)
93

94
### Authentication & Credentials
95

96
Multiple authentication methods supporting various credential types including access keys, STS tokens, RAM roles, and RSA key pairs.
97

98
```python { .api }
99
class AccessKeyCredential:
100
    def __init__(self, access_key_id, access_key_secret): ...
101

102
class StsTokenCredential:
103
    def __init__(self, sts_access_key_id, sts_access_key_secret, sts_token): ...
104

105
class RamRoleArnCredential:
106
    def __init__(self, sts_access_key_id, sts_access_key_secret, role_arn, session_role_name): ...
107
```
108

109
[Authentication & Credentials](./authentication.md)
110

111
### Exception Handling
112

113
Comprehensive exception classes for handling both client-side and server-side errors with detailed error information and debugging capabilities.
114

115
```python { .api }
116
class ClientException(Exception):
117
    def __init__(self, code, msg): ...
118
    
119
class ServerException(Exception):
120
    def __init__(self, code, msg, http_status, request_id): ...
121
```
122

123
[Exception Handling](./exception-handling.md)
124

125
### Retry & Backoff
126

127
Flexible retry mechanisms with configurable retry conditions and backoff strategies for handling transient failures and rate limiting.
128

129
```python { .api }
130
class RetryPolicy(RetryCondition, BackoffStrategy): ...
131
class MaxRetryTimesCondition(RetryCondition): ...
132
class ExponentialBackoffStrategy(BackoffStrategy): ...
133
```
134

135
[Retry & Backoff](./retry-backoff.md)
136

137
## Types
138

139
### Core Types
140

141
```python { .api }
142
from typing import Dict, Any, Optional, Union
143

144
# HTTP method types
145
class MethodType:
146
    GET: str
147
    POST: str
148
    PUT: str
149
    DELETE: str
150
    HEAD: str
151
    OPTIONS: str
152

153
# Protocol types
154
class ProtocolType:
155
    HTTP: str
156
    HTTPS: str
157

158
# Format types  
159
class FormatType:
160
    JSON: str
161
    XML: str
162
    RAW: str
163
    APPLICATION_FORM: str
164
    APPLICATION_XML: str
165
    APPLICATION_JSON: str
166
    APPLICATION_OCTET_STREAM: str
167
    TEXT_XML: str
168

169
# Request styles
170
STYLE_RPC: str
171
STYLE_ROA: str
172
```