tencentcloud-sdk-python and the shape of a generated cloud SDK

One common package plus one package per product, and you pick one way

The packaging is the first decision, and it is not obvious from the repository description.

Installing a specific product means installing the common package first, which is mandatory, and then the package for the product you need. The commands are pip install --upgrade tencentcloud-sdk-python-common for the common package and pip install --upgrade tencentcloud-sdk-python-cvm for the CVM product, with the async flavour installed by adding the async extra in brackets to the common package name.

There is also an all-in-one option, pip install --upgrade tencentcloud-sdk-python, which installs the calling code for every cloud product. The guidance is that this package is therefore large, and that anyone sensitive to size should install the specific product package instead. The package name abbreviations for each product are listed in the products.md file.

The constraints in the notes are the part worth internalising. The two installation methods are mutually exclusive, you only choose one. If you install several product packages, they and the common package should be kept on the same version. Users who cannot reach the official index can speed up downloads with a mirror, using pip install -i against the Tencent pypi mirror and naming the package. And if both Python 2 and Python 3 are present, the Python 3 environment needs pip3.

That last rule and the version alignment rule are the two that cause trouble in practice, and both are the kind of thing the documentation tells you once and never again.

The core of a call is four objects

The simplified example in the documentation shows the shape of every call, and it is short enough to read as a template.

import os
from tencentcloud.common import credential
from tencentcloud.common.exception.tencent_cloud_sdk_exception import TencentCloudSDKException
from tencentcloud.cvm.v20170312 import cvm_client, models

Then a credential, a client, a request and a response:

    cred = credential.Credential(
        os.environ.get("TENCENTCLOUD_SECRET_ID"),
        os.environ.get("TENCENTCLOUD_SECRET_KEY"))
    client = cvm_client.CvmClient(cred, "ap-shanghai")

    req = models.DescribeInstancesRequest()
    resp = client.DescribeInstances(req)

    print(resp.to_json_string())

Four things to notice.

First, the credential is read from environment variables rather than hardcoded, and the documentation is emphatic about why. Hardcoding keys into code can expose them if the code leaks, and the credential is used to encrypt the signature string that the server verifies. The SecretID identifies the caller and the SecretKey signs the request, and the SecretKey must be kept strictly.

Second, the client is constructed with a region string, ap-shanghai in this case, and the region is a first-class argument rather than something hidden in configuration.

Third, the request object is a distinct class with a name matching the interface, and the client's method has the same name. Every interface has a corresponding request object, and the request object's member variables are the interface's input parameters.

Fourth, the response is a matching class with a to_json_string method, and it also exposes individual fields, so the example prints resp.TotalCount as well as the whole JSON.

A profile object is where signing, proxy and retry live

The detailed example adds a layer of configuration that the simple one omits, and that layer is the practical part.

The HTTP profile controls the transport. It has a scheme, a keepAlive flag, a request method, a request timeout in seconds and an endpoint. The endpoint field is worth pausing on: setting it to a region-specific domain such as cvm.ap-shanghai.tencentcloudapi.com overrides the default, which is described as nearest-entry behaviour. The proxy option is set the same way, on the profile constructor.

The client profile sits above it and carries the signing method, which is set to TC3-HMAC-SHA256, and a language setting that switches the response messages between English and Chinese, with Chinese as the default. The httpProfile is assigned onto the client profile.

Retry is configured on the client profile too, through a retryer. The example attaches a StandardRetryer with a maximum of three attempts and a logger, and the comment explains the intent: when a network or rate limiting error occurs, retry three times and log it.

Logging has its own set of calls, with stream, file and default logger variants, and a note that the file logger rotates output, keeping at most ten files with a maximum size of 512MB each.

This is the part that makes the SDK usable in production rather than in a tutorial. Signing, proxying, timeouts, retry and logging are all first-class configuration instead of things you patch in.

Requests carry filters, headers and typed member variables

The request object is not a bag of strings, and the detailed example shows the two features that make it more than a dictionary.

Filters are the first. The example creates a Filter object, sets its Name to zone and its Values to a list of two zones, and assigns the list of filters to the request. The Filters member is a list of Filter objects. That is a typed representation of a structured query parameter, and the alternative, a string you format by hand, is exactly the kind of thing that breaks silently when a value contains a separator.

Headers are the second. The request object accepts a headers dictionary, and the example sets X-TC-TraceId to a UUID so the call can be traced on the server side. The documentation notes that other custom headers such as X-TC-Canary work the same way, and that the header must be a dictionary.

The response side is symmetrical. The response is an instance of a class named after the interface, and its fields are documented in the same place as the request parameters, so you can pull out a single value like TotalCount rather than parsing the JSON yourself.

The one constraint is stated plainly in the notes on the common client. You must know exactly which parameters an interface requires, otherwise the call may fail. A generic entry point does not protect you from a wrong request.

The common client and the async path arrived in specific versions

Two later additions changed how the SDK can be used.

From version 3.0.396 the SDK supports a generic API calling style, the Common Client. Installing only the tencentcloud-sdk-python-common package is enough to call any product. The trade is stated in the same breath: you must know precisely which parameters the interface you are calling needs, otherwise the call may fail. A reference example is provided in the examples directory under common_client.

From version 3.1.0 the SDK supports asynchronous calls. The async version is based on the httpx library and is aimed at high concurrency situations, and it requires the async flavour of the common package, installed with the async extra.

The rules for the async path are specific. The async client needs the module with an _async suffix, such as cvm_client_async. Using async with is recommended so the client is released correctly. And the async API surface matches the synchronous one, with the only difference being that you add await before the call. All the synchronous configuration options are supported, including proxy, retry and signing.

That last property is the important one. Because the two surfaces are identical apart from await, you can move a call to the async client without restructuring the surrounding code, which is what makes the async path practical rather than a separate API to learn.

The requests dependency and the OpenSSL problem it creates

There is a dependency note in the documentation that is worth reading before you deploy, because it produces a confusing error message.

The project depends on the requests library. Since version 2.30.0 of requests, requests is built against urllib3 2.0, and urllib3 2.0 requires OpenSSL 1.1.1 or newer. If your Python was compiled against an older OpenSSL, importing the SDK raises an error along the lines of urllib3 v2.0 only supports OpenSSL 1.1.1+, currently the ssl module is compiled with OpenSSL 1.0.x.

There are two documented fixes. Either downgrade urllib3 to the 1.26.x line, which is inside the range requests itself allows, since requests depends on urllib3 at 1.21.1 or newer and below 3. Or rebuild the Python environment against OpenSSL 1.1.1 or newer.

The setup script shows the dependency declaration that produces this situation:

    install_requires=["requests>=2.16.0"],
    extras_require={"async": ["httpx>=0.22.0"]},

The lower bound of 2.16.0 is permissive, which is good, and it is the resolver picking the newest requests that satisfies it, combined with a Python built against an old OpenSSL, that produces the failure. The async extra pulls httpx at 0.22.0 or newer, and httpx does not have this particular constraint.

The supported Python versions are listed as 2.7 and 3.6 through 3.12 in the requirements section, and the classifiers list 2.7 plus 3.7 through 3.12.

Credentials, endpoints and installing from the source tree

The prerequisites are worth reading as a checklist.

You need a supported Python version, you need the product opened from the Tencent Cloud console, and you need three things: the SecretID, the SecretKey and the endpoint. The endpoint takes the general form of a subdomain under tencentcloudapi.com, with the CVM example given as cvm.tencentcloudapi.com, and the specific value depends on the product.

The credentials are obtained from the console before the first call to a cloud API, and the documentation is direct about the SecretKey: it is the key used to encrypt the signature string and have the server verify it, and it must be kept strictly, avoiding disclosure.

If you would rather not use pip, the source route is to download the latest code from the CNB, GitHub or Gitee repository, extract it, and run the install from the extracted directory:

    $ cd tencentcloud-sdk-python
    $ python setup.py install

The source tree tells you the shape of the project. The tencentcloud/ directory holds the common code and the per-product packages, there is a QcloudApi/ directory for the older generation of the API, and an examples/ directory with a folder per product, including cls, cvm, ocr, soe, hunyuan, apigateway_proxy, dts, ecc, ess, hcm, tci and wss. There is a common_client folder for the generic calling style, a package.py that drives the code generation, a products.md listing the package name abbreviations, a CHANGELOG.md and a SERVICE_CHANGELOG.md.

The setup script identifies the package as Apache License 2.0, with the classifier Development Status :: 5 - Production/Stable. The last push to the repository was on 2026-10-19, and the project publishes no GitHub releases, so the version in the package itself is the only reference point.

Editorial conclusion

tencentcloud-sdk-python suits a Python service that needs to call a handful of Tencent Cloud products and wants the signing, retry and error handling already written, since the common package plus a product package keeps the dependency surface small. It does not suit a project that wants a small, stable client library you can read in an afternoon, because the generated surface is large and the model objects are numerous, and it does not suit a team that needs to support Python 2.7 indefinitely without reading the dependency notes. Before installing, choose between the per-product packages and the all-in-one package rather than both, because the documentation says only one approach may be used, and note that the last push was on 2026-10-19 with the project publishing no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. TencentCloud/tencentcloud-sdk-python on GitHub