0
# TencentCloud SDK for Python
1

2
A comprehensive Software Development Kit (SDK) for integrating with Tencent Cloud services, enabling Python developers to programmatically access and manage over 240 cloud services including CVM (Cloud Virtual Machine), CBS (Cloud Block Storage), and numerous other Tencent Cloud products. The SDK offers a unified API interface with automatic request signing, authentication handling, and error management.
3

4
## Package Information
5

6
- **Package Name**: tencentcloud-sdk-python
7
- **Language**: Python
8
- **Installation**: `pip install tencentcloud-sdk-python`
9
- **Supported Python Versions**: 2.7, 3.7-3.12
10
- **Dependencies**: `requests>=2.16.0`
11

12
## Core Imports
13

14
```python
15
# Core authentication and client infrastructure
16
from tencentcloud.common import credential
17
from tencentcloud.common.exception.tencent_cloud_sdk_exception import TencentCloudSDKException
18
from tencentcloud.common.profile.client_profile import ClientProfile
19
from tencentcloud.common.profile.http_profile import HttpProfile
20

21
# Service-specific imports (example with CVM)
22
from tencentcloud.cvm.v20170312 import cvm_client, models
23

24
# Generic client for any service
25
from tencentcloud.common.common_client import CommonClient
26
```
27

28
## Basic Usage
29

30
```python
31
import os
32
from tencentcloud.common import credential
33
from tencentcloud.common.exception.tencent_cloud_sdk_exception import TencentCloudSDKException
34
from tencentcloud.cvm.v20170312 import cvm_client, models
35

36
try:
37
    # Initialize credentials (recommended: use environment variables)
38
    cred = credential.Credential(
39
        os.environ.get("TENCENTCLOUD_SECRET_ID"),
40
        os.environ.get("TENCENTCLOUD_SECRET_KEY")
41
    )
42
    
43
    # Create service client
44
    client = cvm_client.CvmClient(cred, "ap-shanghai")
45
    
46
    # Create request object
47
    req = models.DescribeInstancesRequest()
48
    
49
    # Call API
50
    resp = client.DescribeInstances(req)
51
    
52
    # Handle response
53
    print(resp.to_json_string())
54
    
55
except TencentCloudSDKException as err:
56
    print(f"Error: {err.get_code()} - {err.get_message()}")
57
```
58

59
## Architecture
60

61
The TencentCloud SDK follows a consistent, hierarchical structure across all 242 cloud services:
62

63
- **Common Module**: Core authentication, client infrastructure, and utilities shared across all services
64
- **Service Modules**: Individual service packages (cvm, cbs, vpc, etc.) with versioned APIs
65
- **Abstract Classes**: Base classes (`AbstractClient`, `AbstractModel`) providing common functionality
66
- **Credential Providers**: Multiple authentication methods for different deployment scenarios
67
- **Configuration Profiles**: Customizable HTTP, retry, and circuit breaker settings
68

69
Each service follows the pattern: `tencentcloud.{service}.{version}.{service}_client` and `tencentcloud.{service}.{version}.models`.
70

71
## Capabilities
72

73
### Authentication and Credentials
74

75
Multiple authentication methods supporting various deployment scenarios including development, production, container environments, and cross-account access.
76

77
```python { .api }
78
class Credential:
79
    def __init__(self, secret_id: str, secret_key: str, token: str = None): ...
80

81
class CVMRoleCredential:
82
    def __init__(self, role_name: str = None): ...
83

84
class STSAssumeRoleCredential:
85
    def __init__(self, secret_id: str, secret_key: str, role_arn: str, role_session_name: str, duration_seconds: int = 7200): ...
86

87
class EnvironmentVariableCredential:
88
    def __init__(self): ...
89

90
class ProfileCredential:
91
    def __init__(self, profile_name: str = None, profile_path: str = None): ...
92

93
class DefaultCredentialProvider:
94
    def __init__(self): ...
95
```
96

97
[Authentication and Credentials](./authentication.md)
98

99
### Client Infrastructure
100

101
Core client classes providing HTTP communication, request signing, error handling, and logging capabilities for all Tencent Cloud services.
102

103
```python { .api }
104
class AbstractClient:
105
    def __init__(self, credential, region: str, profile = None): ...
106
    def set_stream_logger(self, stream, level): ...
107
    def set_file_logger(self, file_path: str, level): ...
108

109
class CommonClient(AbstractClient):
110
    def __init__(self, service: str, version: str, credential, region: str, profile = None): ...
111
    def call_json(self, action: str, params: dict, headers: dict = None): ...
112
```
113

114
[Client Infrastructure](./client-infrastructure.md)
115

116
### Configuration and Profiles
117

118
Comprehensive configuration system for HTTP settings, retry behavior, circuit breakers, and request customization.
119

120
```python { .api }
121
class ClientProfile:
122
    def __init__(self, signMethod: str = "TC3-HMAC-SHA256", httpProfile = None, language: str = "zh-CN", debug: bool = False): ...
123

124
class HttpProfile:
125
    def __init__(self, protocol: str = "https", endpoint: str = None, reqMethod: str = "POST", reqTimeout: int = 60): ...
126

127
class RegionBreakerProfile:
128
    def __init__(self, backup_endpoint: str, max_fail_num: int = 5, max_fail_percent: float = 0.75): ...
129
```
130

131
[Configuration and Profiles](./configuration.md)
132

133
### Error Handling and Retry
134

135
Unified exception handling and configurable retry mechanisms with exponential backoff for robust cloud service integration.
136

137
```python { .api }
138
class TencentCloudSDKException(Exception):
139
    def __init__(self, code: str = None, message: str = None, requestId: str = None): ...
140
    def get_code(self) -> str: ...
141
    def get_message(self) -> str: ...
142
    def get_request_id(self) -> str: ...
143

144
class StandardRetryer:
145
    def __init__(self, max_attempts: int = 3, backoff_fn = None, logger = None): ...
146

147
class NoopRetryer:
148
    def __init__(self): ...
149
```
150

151
[Error Handling and Retry](./error-handling.md)
152

153
### Service Clients
154

155
Service-specific client classes for accessing Tencent Cloud APIs. All service clients follow a consistent pattern and inherit from `AbstractClient`.
156

157
**Core Compute Services:**
158
- **CVM (Cloud Virtual Machine)**: EC2-equivalent compute instances, images, snapshots
159
- **SCF (Serverless Cloud Function)**: Function-as-a-service execution environment
160
- **THPC (Tencent High Performance Computing)**: High-performance computing clusters
161

162
**Storage Services:**
163
- **CBS (Cloud Block Storage)**: Block storage volumes for CVM instances
164
- **CFS (Cloud File Storage)**: Managed NFS file systems
165
- **COS (Cloud Object Storage)**: S3-compatible object storage
166

167
**Networking Services:**
168
- **VPC (Virtual Private Cloud)**: Software-defined networking, subnets, routing
169
- **CLB (Cloud Load Balancer)**: Application and network load balancing
170
- **CDN (Content Delivery Network)**: Global content caching and acceleration
171

172
```python { .api }
173
# Example service client signatures (CVM, CBS, VPC)
174
class CvmClient(AbstractClient):
175
    def __init__(self, credential, region: str, profile = None): ...
176
    def DescribeInstances(self, request) -> models.DescribeInstancesResponse: ...
177
    def RunInstances(self, request) -> models.RunInstancesResponse: ...
178
    def TerminateInstances(self, request) -> models.TerminateInstancesResponse: ...
179

180
class CbsClient(AbstractClient):
181
    def __init__(self, credential, region: str, profile = None): ...
182
    def CreateDisks(self, request) -> models.CreateDisksResponse: ...
183
    def AttachDisks(self, request) -> models.AttachDisksResponse: ...
184
    def DetachDisks(self, request) -> models.DetachDisksResponse: ...
185

186
class VpcClient(AbstractClient):
187
    def __init__(self, credential, region: str, profile = None): ...
188
    def CreateVpc(self, request) -> models.CreateVpcResponse: ...
189
    def CreateSubnet(self, request) -> models.CreateSubnetResponse: ...
190
    def DescribeVpcs(self, request) -> models.DescribeVpcsResponse: ...
191
```
192

193
[Service Clients](./service-clients.md)
194

195
### Data Models
196

197
Base model class and service-specific request/response models providing JSON serialization and data validation for all API interactions.
198

199
```python { .api }
200
class AbstractModel:
201
    def __init__(self): ...
202
    def to_json_string(self, indent: int = None) -> str: ...
203
    def from_json_string(self, json_string: str): ...
204

205
# Example model classes (all models inherit from AbstractModel)
206
class DescribeInstancesRequest(AbstractModel):
207
    def __init__(self): ...
208

209
class DescribeInstancesResponse(AbstractModel):
210
    def __init__(self): ...
211

212
class Instance(AbstractModel):
213
    def __init__(self): ...
214
```
215

216
[Data Models](./data-models.md)
217

218
## Types
219

220
```python { .api }
221
# Core credential interface
222
class CredentialInterface:
223
    def get_credential(self): ...
224

225
# Request/response base
226
class AbstractModel:
227
    def to_json_string(self, indent: int = None) -> str: ...
228
    def from_json_string(self, json_string: str): ...
229
    def _serialize(self) -> dict: ...
230

231
# Filter for query operations
232
class Filter:
233
    def __init__(self):
234
        self.Name: str = None
235
        self.Values: list = None
236

237
# Basic pagination
238
class Paging:
239
    def __init__(self):
240
        self.Offset: int = None
241
        self.Limit: int = None
242

243
# Common placement information
244
class Placement:
245
    def __init__(self):
246
        self.Zone: str = None
247
        self.ProjectId: int = None
248
        self.HostIds: list = None
249
```