CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-tencentcloud-sdk-python

Comprehensive Python SDK for integrating with Tencent Cloud services, supporting 240+ cloud services with authentication, error handling, and retry mechanisms.

Overview
Eval results
Files

authentication.mddocs/

Authentication and Credentials

Comprehensive authentication system supporting multiple credential types for various deployment scenarios including development environments, production systems, container deployments, and cross-account access patterns.

Capabilities

Basic API Key Authentication

Standard authentication using SecretID and SecretKey pairs obtained from Tencent Cloud console.

class Credential:
    def __init__(self, secret_id: str, secret_key: str, token: str = None):
        """
        Initialize basic API key credentials.
        
        Parameters:
        - secret_id (str): Tencent Cloud Secret ID
        - secret_key (str): Tencent Cloud Secret Key  
        - token (str, optional): Temporary security token for STS credentials
        
        Raises:
        - TencentCloudSDKException: If secret_id or secret_key is None, empty, or contains spaces
        """
    
    def get_credential_info(self):
        """
        Get credential information tuple for API signing.
        
        Returns:
        tuple: (secret_id, secret_key, token)
        """
    
    @property
    def secretId(self) -> str:
        """
        Get secret ID (camelCase accessor for compatibility).
        
        Returns:
        str: Secret ID
        """
    
    @property
    def secretKey(self) -> str:
        """
        Get secret key (camelCase accessor for compatibility).
        
        Returns:
        str: Secret key
        """

Usage Example:

from tencentcloud.common import credential

# Direct credential instantiation (not recommended for production)
cred = credential.Credential("your_secret_id", "your_secret_key")

# With temporary token
cred = credential.Credential("secret_id", "secret_key", "temp_token")

Environment Variable Credentials

Automatically loads credentials from TENCENTCLOUD_SECRET_ID and TENCENTCLOUD_SECRET_KEY environment variables.

class EnvironmentVariableCredential:
    def __init__(self):
        """
        Initialize credential provider that reads from environment variables.
        Looks for TENCENTCLOUD_SECRET_ID and TENCENTCLOUD_SECRET_KEY.
        """
    
    def get_credential(self):
        """
        Get credentials from environment variables.
        
        Returns:
        Credential: Credential object with values from environment
        
        Raises:
        TencentCloudSDKException: If environment variables are not set
        """

Usage Example:

import os
from tencentcloud.common import credential

# Set environment variables
os.environ['TENCENTCLOUD_SECRET_ID'] = 'your_secret_id'
os.environ['TENCENTCLOUD_SECRET_KEY'] = 'your_secret_key'

# Use environment credential provider
cred = credential.EnvironmentVariableCredential().get_credential()

Configuration File Credentials

Loads credentials from configuration files located at standard paths with INI format.

class ProfileCredential:
    def __init__(self):
        """
        Initialize credential provider that reads from configuration file.
        
        Reads credentials from fixed standard paths:
        - Linux: ~/.tencentcloud/credentials or /etc/tencentcloud/credentials
        - Windows: c:\\Users\\NAME\\.tencentcloud\\credentials
        
        Only reads from "default" profile section.
        """
    
    def get_credential(self):
        """
        Load credentials from configuration file.
        
        Returns:
        Credential: Credential object with values from config file
        
        Raises:
        TencentCloudSDKException: If config file not found or invalid format
        """

Configuration File Format:

[default]
secret_id = your_secret_id_here
secret_key = your_secret_key_here

[production]
secret_id = prod_secret_id
secret_key = prod_secret_key

Usage Example:

from tencentcloud.common import credential

# Use default profile
cred = credential.ProfileCredential().get_credential()

# Note: ProfileCredential does not support custom profile names or paths
# It only reads from "default" section in standard locations

Instance Role Credentials

Automatically obtains credentials from CVM instance metadata for applications running on Tencent Cloud instances with assigned roles.

class CVMRoleCredential:
    def __init__(self, role_name: str = None):
        """
        Initialize CVM instance role credential provider.
        
        Parameters:
        - role_name (str, optional): Specific role name (auto-detected if not provided)
        """
    
    def get_credential_info(self):
        """
        Get credential information tuple from CVM instance metadata.
        
        Returns:
        tuple: (secret_id, secret_key, token)
        
        Raises:
        TencentCloudSDKException: If not running on CVM or role not assigned
        """
    
    @property
    def secretId(self) -> str:
        """
        Get secret ID (camelCase accessor for compatibility).
        
        Returns:
        str: Secret ID from instance metadata
        """
    
    @property
    def secretKey(self) -> str:
        """
        Get secret key (camelCase accessor for compatibility).
        
        Returns:
        str: Secret key from instance metadata
        """
    
    def update_credential(self):
        """
        Force refresh of credentials from metadata service.
        """
    
    def get_role_name(self) -> str:
        """
        Get the role name associated with this instance.
        
        Returns:
        str: Role name
        """

Usage Example:

from tencentcloud.common import credential

# Automatic role detection
cred = credential.CVMRoleCredential().get_credential()

# Specific role name
cred = credential.CVMRoleCredential("MyAppRole").get_credential()

STS Assume Role Credentials

Cross-account access using Security Token Service (STS) to assume roles in different Tencent Cloud accounts.

class STSAssumeRoleCredential:
    def __init__(self, secret_id: str, secret_key: str, role_arn: str, role_session_name: str, duration_seconds: int = 7200, endpoint: str = None):
        """
        Initialize STS assume role credential provider.
        
        Parameters:
        - secret_id (str): Base account Secret ID
        - secret_key (str): Base account Secret Key
        - role_arn (str): ARN of role to assume (format: qcs::cam::account-id:role/role-name)
        - role_session_name (str): Session identifier for audit purposes
        - duration_seconds (int): Session duration in seconds (900-7200, default: 7200)
        - endpoint (str, optional): Custom STS endpoint
        """
    
    def get_credential_info(self):
        """
        Get credential information tuple with automatic refresh.
        
        Returns:
        tuple: (secret_id, secret_key, token)
        
        Raises:
        TencentCloudSDKException: If role assumption fails or insufficient permissions
        """
    
    @property
    def secretId(self) -> str:
        """
        Get secret ID (camelCase accessor for compatibility).
        
        Returns:
        str: Secret ID from assumed role
        """
    
    @property
    def secretKey(self) -> str:
        """
        Get secret key (camelCase accessor for compatibility).
        
        Returns:
        str: Secret key from assumed role
        """
    
    def get_sts_tmp_role_arn(self) -> str:
        """
        Get the assumed role ARN.
        
        Returns:
        str: Role ARN being assumed
        """

Usage Example:

from tencentcloud.common import credential

# Cross-account role assumption
cred = credential.STSAssumeRoleCredential(
    secret_id="base_account_secret_id",
    secret_key="base_account_secret_key", 
    role_arn="qcs::cam::100001234567:role/CrossAccountRole",
    role_session_name="MyAppSession",
    duration_seconds=3600
).get_credential()

OIDC Credentials

OpenID Connect (OIDC) authentication for cloud-native applications, particularly useful in Kubernetes environments.

class OIDCRoleArnCredential:
    def __init__(self, region: str, provider_id: str, web_identity_token: str, role_arn: str, role_session_name: str, duration_seconds: int = 7200, endpoint: str = None):
        """
        Initialize OIDC role ARN credential provider.
        
        Parameters:
        - region (str): Tencent Cloud region
        - provider_id (str): OIDC provider identifier
        - web_identity_token (str): OIDC identity token (JWT)
        - role_arn (str): ARN of role to assume
        - role_session_name (str): Session identifier
        - duration_seconds (int): Session duration in seconds (900-7200, default: 7200)
        - endpoint (str, optional): Custom STS endpoint
        """
    
    def get_credential_info(self):
        """
        Get credential information tuple with automatic refresh.
        
        Returns:
        tuple: (secret_id, secret_key, token)
        
        Raises:
        TencentCloudSDKException: If OIDC token invalid or role assumption fails
        """
    
    @property
    def secretId(self) -> str:
        """
        Get secret ID (camelCase accessor for compatibility).
        
        Returns:
        str: Secret ID from assumed role
        """
    
    @property
    def secretKey(self) -> str:
        """
        Get secret key (camelCase accessor for compatibility).
        
        Returns:
        str: Secret key from assumed role
        """
    
    def refresh(self):
        """
        Manually refresh credentials using OIDC token.
        """
    
    @property
    def endpoint(self) -> str:
        """
        Get the STS endpoint.
        
        Returns:
        str: STS endpoint URL
        """
    
    @endpoint.setter
    def endpoint(self, endpoint: str):
        """
        Set custom STS endpoint.
        
        Parameters:
        - endpoint (str): Custom STS endpoint URL
        """
    
    def get_credential(self):
        """
        Use OIDC token to assume role and get credentials.
        
        Returns:
        Credential: Temporary credentials from OIDC authentication
        
        Raises:
        TencentCloudSDKException: If OIDC authentication fails
        """

class DefaultTkeOIDCRoleArnProvider:
    def __init__(self):
        """
        Initialize TKE (Tencent Kubernetes Engine) OIDC credential provider.
        Automatically detects TKE environment and uses service account tokens.
        """
    
    def get_credential(self):
        """
        Get credentials using TKE OIDC provider.
        
        Returns:
        Credential: Credentials for TKE workload identity
        
        Raises:
        TencentCloudSDKException: If not in TKE environment or configuration invalid
        """

Usage Example:

from tencentcloud.common import credential

# Manual OIDC token
cred = credential.OIDCRoleArnCredential(
    oidc_token="eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
    role_arn="qcs::cam::100001234567:role/TkeRole",
    role_session_name="TkeWorkload"
).get_credential()

# TKE automatic OIDC
cred = credential.DefaultTkeOIDCRoleArnProvider().get_credential()

Default Credential Provider Chain

Automatic credential resolution using a prioritized chain of credential providers, ideal for applications that need to work across different environments.

class DefaultCredentialProvider:
    def __init__(self):
        """
        Initialize default credential provider chain.
        
        Resolution order:
        1. Environment variables (TENCENTCLOUD_SECRET_ID, TENCENTCLOUD_SECRET_KEY)
        2. Configuration file (~/.tencentcloud/credentials)
        3. CVM instance role
        4. TKE OIDC provider
        """
    
    def get_credential(self):
        """
        Get credentials using provider chain resolution.
        
        Returns:
        Credential: First successfully resolved credential from chain
        
        Raises:
        TencentCloudSDKException: If no credential provider succeeds
        """

Usage Example:

from tencentcloud.common import credential

# Automatic credential resolution
cred = credential.DefaultCredentialProvider().get_credential()

# Use in client initialization
from tencentcloud.cvm.v20170312 import cvm_client
client = cvm_client.CvmClient(cred, "ap-shanghai")

Common Authentication Patterns

Development Environment:

# Option 1: Environment variables (recommended)
from tencentcloud.common import credential
cred = credential.EnvironmentVariableCredential().get_credential()

# Option 2: Configuration file
cred = credential.ProfileCredential().get_credential()

Production Environment:

# Option 1: Instance role (recommended for CVM)
cred = credential.CVMRoleCredential().get_credential()

# Option 2: Default provider chain (works everywhere)
cred = credential.DefaultCredentialProvider().get_credential()

Container/Kubernetes Environment:

# TKE with OIDC
cred = credential.DefaultTkeOIDCRoleArnProvider().get_credential()

# Or use default provider chain
cred = credential.DefaultCredentialProvider().get_credential()

Cross-Account Access:

# STS assume role
cred = credential.STSAssumeRoleCredential(
    "base_secret_id", "base_secret_key",
    "qcs::cam::target-account:role/TargetRole",
    "CrossAccountSession"
).get_credential()

Install with Tessl CLI

npx tessl i tessl/pypi-tencentcloud-sdk-python

docs

authentication.md

client-infrastructure.md

configuration.md

data-models.md

error-handling.md

index.md

service-clients.md

tile.json