0
# Tencent Cloud SDK Python Common
1

2
Common utilities and core components for Tencent Cloud SDK for Python, providing credential management, HTTP clients, authentication, error handling, and foundational classes required by all Tencent Cloud service SDKs. This package serves as the foundational layer for the entire Tencent Cloud SDK ecosystem, enabling developers to build applications that integrate with Tencent Cloud services through a consistent, well-architected foundation.
3

4
## Package Information
5

6
- **Package Name**: tencentcloud-sdk-python-common
7
- **Type**: Library
8
- **Language**: Python
9
- **Installation**: `pip install tencentcloud-sdk-python-common`
10

11
## Core Imports
12

13
```python
14
# Import specific credential classes
15
from tencentcloud.common.credential import Credential, CVMRoleCredential, STSAssumeRoleCredential
16

17
# Import client base classes
18
from tencentcloud.common.abstract_client import AbstractClient
19
from tencentcloud.common.common_client import CommonClient
20

21
# Import profile configuration
22
from tencentcloud.common.profile.client_profile import ClientProfile
23
from tencentcloud.common.profile.http_profile import HttpProfile
24

25
# Import exception handling
26
from tencentcloud.common.exception.tencent_cloud_sdk_exception import TencentCloudSDKException
27
```
28

29
## Basic Usage
30

31
```python
32
from tencentcloud.common.credential import Credential
33
from tencentcloud.common.profile.client_profile import ClientProfile
34
from tencentcloud.common.profile.http_profile import HttpProfile
35
from tencentcloud.common.common_client import CommonClient
36

37
# Create credentials
38
cred = Credential("your-secret-id", "your-secret-key")
39

40
# Configure HTTP profile
41
http_profile = HttpProfile()
42
http_profile.endpoint = "cvm.tencentcloudapi.com"
43

44
# Configure client profile
45
client_profile = ClientProfile()
46
client_profile.httpProfile = http_profile
47

48
# Create common client
49
client = CommonClient("cvm", "2017-03-12", cred, "ap-guangzhou", client_profile)
50

51
# Make API call
52
response = client.call_json("DescribeInstances", {})
53
print(response)
54
```
55

56
## Architecture
57

58
The package follows a layered architecture with clear separation of concerns:
59

60
- **Credential Layer**: Multiple credential providers with automatic fallback chain
61
- **Transport Layer**: HTTP connection management with pooling, proxies, and resilience features
62
- **Client Layer**: Abstract base classes that service-specific clients inherit from
63
- **Configuration Layer**: Flexible profile system for HTTP settings, signatures, and regional failover
64
- **Resilience Layer**: Circuit breakers, retry mechanisms, and error handling
65
- **Security Layer**: Multiple signature methods and authentication strategies
66

67
This design enables consistent behavior across all Tencent Cloud service SDKs while providing flexibility for different deployment scenarios and authentication methods.
68

69
## Capabilities
70

71
### Credential Management
72

73
Multiple credential providers supporting environment variables, configuration files, instance roles, STS temporary credentials, and OIDC tokens. Includes automatic credential chain resolution for flexible deployment scenarios.
74

75
```python { .api }
76
class Credential:
77
    def __init__(self, secret_id: str, secret_key: str, token: str = None): ...
78
    def get_credential_info(self) -> tuple[str, str, str]: ...
79

80
class DefaultCredentialProvider:
81
    def __init__(self): ...
82
    def get_credentials(self): ...
83
```
84

85
[Credential Management](./credential-management.md)
86

87
### HTTP Infrastructure
88

89
Comprehensive HTTP client implementation with connection pooling, proxy support, pre-connected pools for performance, and custom certificate handling. Supports both HTTP and HTTPS with configurable timeouts and keep-alive.
90

91
```python { .api }
92
class ApiRequest:
93
    def __init__(self, host: str, req_timeout: int = 60, debug: bool = False, 
94
                 proxy: str = None, is_http: bool = False, certification = None,
95
                 pre_conn_pool_size: int = 0): ...
96
    def send_request(self, req_inter: RequestInternal): ...
97
```
98

99
[HTTP Infrastructure](./http-infrastructure.md)
100

101
### Client Foundation
102

103
Abstract base classes providing the foundation for all Tencent Cloud service clients. Handles request building, signature generation, response processing, and error handling with support for multiple signature methods.
104

105
```python { .api }
106
class AbstractClient:
107
    def __init__(self, credential, region: str, profile: ClientProfile = None): ...
108
    def call_json(self, action: str, params: dict, headers: dict = None, 
109
                  options: dict = None) -> dict: ...
110
    def call_sse(self, action: str, params: dict, headers: dict = None,
111
                 options: dict = None): ...
112
```
113

114
[Client Foundation](./client-foundation.md)
115

116
### Configuration Profiles
117

118
Flexible configuration system for HTTP settings, signature methods, language preferences, and regional failover. Supports customization of endpoints, timeouts, retry policies, and circuit breaker settings.
119

120
```python { .api }
121
class ClientProfile:
122
    def __init__(self, signMethod: str = None, httpProfile: HttpProfile = None,
123
                 language: str = "zh-CN", disable_region_breaker: bool = True,
124
                 region_breaker_profile = None, request_client: str = None,
125
                 retryer = None): ...
126

127
class HttpProfile:
128
    def __init__(self, protocol: str = None, endpoint: str = None,
129
                 reqMethod: str = "POST", reqTimeout: int = 60,
130
                 keepAlive: bool = False, proxy: str = None,
131
                 rootDomain: str = None, certification = None): ...
132
```
133

134
[Configuration Profiles](./configuration-profiles.md)
135

136
### Resilience and Reliability
137

138
Circuit breaker implementation for regional failover and retry mechanisms with configurable backoff strategies. Provides automatic failure detection and recovery for improved reliability.
139

140
```python { .api }
141
class CircuitBreaker:
142
    def __init__(self, breaker_setting): ...
143
    def before_requests(self) -> tuple[int, bool]: ...
144
    def after_requests(self, before: int, success: bool): ...
145

146
class StandardRetryer:
147
    def __init__(self, max_attempts: int = 3, backoff_fn = None, logger = None): ...
148
    def send_request(self, fn): ...
149
```
150

151
[Resilience and Reliability](./resilience-reliability.md)
152

153
### Security and Authentication
154

155
Digital signature utilities supporting multiple signature methods (HmacSHA1, HmacSHA256, TC3-HMAC-SHA256) and comprehensive exception handling for authentication and API errors.
156

157
```python { .api }
158
class Sign:
159
    @staticmethod
160
    def sign(secret_key: str, sign_str: str, sign_method: str) -> str: ...
161
    @staticmethod
162
    def sign_tc3(secret_key: str, date: str, service: str, str2sign: str) -> str: ...
163

164
class TencentCloudSDKException(Exception):
165
    def __init__(self, code: str = None, message: str = None, 
166
                 requestId: str = None): ...
167
```
168

169
[Security and Authentication](./security-authentication.md)
170

171
## Error Handling
172

173
All operations may raise `TencentCloudSDKException` with specific error codes:
174

175
- **ClientError**: Configuration or parameter errors
176
- **ClientNetworkError**: Network connectivity issues  
177
- **ServerNetworkError**: Server-side network problems
178
- **InvalidCredential**: Authentication failures
179
- **RequestLimitExceeded**: Rate limiting errors
180

181
## Dependencies
182

183
- **requests**: HTTP library (>=2.16.0)
184
- **certifi**: Certificate management
185
- **urllib3**: HTTP connection pooling
186
- **configparser**: Configuration file parsing (Python 2/3 compatibility)