tencentcloud-sdk-python 3.0.1338__py2.py3-none-any.whl → 3.0.1372__py2.py3-none-any.whl

tencentcloud/common/abstract_client.py

@@ -471,20 +471,19 @@ class AbstractClient(object):
         return resp.content
 
     def call_octet_stream(self, action, headers, body):
-        """
-        Invoke API with application/ocet-stream content-type.
+        """Invoke API with application/ocet-stream content-type.
 
         Note:
         1. only specific API can be invoked in such manner.
         2. only TC3-HMAC-SHA256 signature method can be specified.
         3. only POST request method can be specified
 
-        :type action: str
         :param action: Specific API action name.
-        :type headers: dict
+        :type action: str
         :param headers: Header parameters for this API.
-        :type body: bytes
+        :type headers: dict
         :param body: Bytes of requested body
+        :type body: bytes
         """
         if self.profile.signMethod != "TC3-HMAC-SHA256":
             raise SDKError("ClientError", "Invalid signature method.")
@@ -505,17 +504,16 @@ class AbstractClient(object):
         return json.loads(resp.content)
 
     def call_json(self, action, params, headers=None, options=None):
-        """
-        Call api with json object and return with json object.
+        """Call api with json object and return with json object.
 
-        :type action: str
         :param action: api name e.g. ``DescribeInstances``
+        :type action: str
+        :param params: Request parameters of this action
         :type params: dict
-        :param params: params with this action
+        :param headers: Request headers, like {"X-TC-TraceId": "ffe0c072-8a5d-4e17-8887-a8a60252abca"}
         :type headers: dict
-        :param headers: request header, like {"X-TC-TraceId": "ffe0c072-8a5d-4e17-8887-a8a60252abca"}
+        :param options: Request options, like {"SkipSign": False, "IsMultipart": False, "IsOctetStream": False, "BinaryParams": []}
         :type options: dict
-        :param options: request options, like {"SkipSign": False, "IsMultipart": False, "IsOctetStream": False, "BinaryParams": []}
         """
 
         def _call_once():
@@ -529,6 +527,17 @@ class AbstractClient(object):
         return json.loads(retryer.send_request(_call_once).content)
 
     def call_sse(self, action, params, headers=None, options=None):
+        """Call api with json object and return with sse event.
+
+        :param action: api name e.g. ``ChatCompletions``
+        :type action: str
+        :param params: Request parameters of this action
+        :type params: dict
+        :param headers: Request headers, like {"X-TC-TraceId": "ffe0c072-8a5d-4e17-8887-a8a60252abca"}
+        :type headers: dict
+        :param options: Request options, like {"SkipSign": False, "IsMultipart": False, "IsOctetStream": False, "BinaryParams": []}
+        :type options: dict
+        """
         def _call_once():
             resp = self._call(action, params, options, headers)
             self._check_status(resp)
@@ -557,15 +566,14 @@ class AbstractClient(object):
         return self._process_response_json(resp, resp_type)
 
     def set_stream_logger(self, stream=None, level=logging.DEBUG, log_format=None):
-        """
-        Add a stream handler
+        """Add a stream handler
 
-        :type stream: IO[str]
         :param stream: e.g. ``sys.stdout`` ``sys.stdin`` ``sys.stderr``
-        :type level: int
+        :type stream: IO[str]
         :param level: Logging level, e.g. ``logging.INFO``
-        :type log_format: str
+        :type level: int
         :param log_format: Log message format
+        :type log_format: str
         """
         log = logging.getLogger(LOGGER_NAME)
         log.setLevel(level)
@@ -578,15 +586,14 @@ class AbstractClient(object):
         log.addHandler(sh)
 
     def set_file_logger(self, file_path, level=logging.DEBUG, log_format=None):
-        """
-        Add a file handler
+        """Add a file handler
 
-        :type file_path: str
         :param file_path: path of log file
-        :type level: int
+        :type file_path: str
         :param level: Logging level, e.g. ``logging.INFO``
-        :type log_format: str
+        :type level: int
         :param log_format: Log message format
+        :type log_format: str
         """
         log = logging.getLogger(LOGGER_NAME)
         log.setLevel(level)
@@ -600,9 +607,7 @@ class AbstractClient(object):
         log.addHandler(fh)
 
     def set_default_logger(self):
-        """
-        Set default log handler
-        """
+        """Set default log handler"""
         log = logging.getLogger(LOGGER_NAME)
         log.handlers = []
         logger.addHandler(EmptyHandler())

tencentcloud/common/abstract_model.py

@@ -61,7 +61,11 @@ class AbstractModel(object):
         return json.dumps(self._serialize(allow_none=True), *args, **kwargs)
 
     def from_json_string(self, jsonStr):
-        """Deserialize a JSON formatted str to a Python object"""
+        """Deserialize a JSON formatted str to a Python object
+
+        :param jsonStr: JSON formatted string
+        :type jsonStr: str
+        """
         params = json.loads(jsonStr)
         self._deserialize(params)
 

tencentcloud/common/common_client.py

@@ -21,25 +21,24 @@ from tencentcloud.common.exception.tencent_cloud_sdk_exception import TencentClo
 
 
 class CommonClient(AbstractClient):
-    """
-    使用CommonClient，可以只安装tencentcloud-sdk-python-common包，即可调用各个产品的接口
-    使用详情见github示例
+    """General client for all products.
+
+     With CommonClient, you only need to install the tencentcloud-sdk-python-common package to access APIs of all products.
+     See GitHub examples for usage details: https://github.com/TencentCloud/tencentcloud-sdk-python/tree/master/examples/common_client
 
+    :param service: Product name
+    :type service: str
+    :param version: Version of API
+    :type version: str
+    :param credential: Request credential
+    :type credential: tencentcloud.common.credential.Credential or tencentcloud.common.credential.STSAssumeRoleCredential or None
+    :param region: Request region
+    :type region: str
+    :param profile: Request SDK profile
+    :type profile: tencentcloud.common.profile.client_profile.ClientProfile
     """
 
     def __init__(self, service, version, credential, region, profile=None):
-        """
-        :param credential: 接口调用凭证
-        :type credential: tencentcloud.common.credential.Credential or tencentcloud.common.credential.STSAssumeRoleCredential or None
-        :param region: 接口调用地域
-        :type region: str
-        :param version: 接口版本
-        :type version: str
-        :param service: 接口产品
-        :type service: str
-        :param profile: 请求网络信息
-        :type profile: tencentcloud.common.profile.client_profile.ClientProfile
-        """
         if region is None or version is None or service is None:
             raise TencentCloudSDKException("CommonClient Parameter Error, "
                                            "credential region version service all required.")

tencentcloud/common/credential.py

@@ -35,20 +35,20 @@ from tencentcloud.common.profile.client_profile import ClientProfile
 
 
 class Credential(object):
+    """Tencent Cloud Credentials.
+
+    Access https://console.cloud.tencent.com/cam/capi to manage your credentials.
+
+    :param secret_id: The secret id of your credential.
+    :type secret_id: str
+    :param secret_key: The secret key of your credential.
+    :type secret_key: str
+    :param token: The federation token of your credential, if this field
+                  is specified, secret_id and secret_key should be set
+                  accordingly, see: https://cloud.tencent.com/document/product/598/13896
+    """
+
     def __init__(self, secret_id, secret_key, token=None):
-        """Tencent Cloud Credentials.
-
-        Access https://console.cloud.tencent.com/cam/capi to manage your
-        credentials.
-
-        :param secret_id: The secret id of your credential.
-        :type secret_id: str
-        :param secret_key: The secret key of your credential.
-        :type secret_key: str
-        :param token: The federation token of your credential, if this field
-                      is specified, secret_id and secret_key should be set
-                      accordingly, see: https://cloud.tencent.com/document/product/598/13896
-        """
         if secret_id is None or secret_id.strip() == "":
             raise TencentCloudSDKException("InvalidCredential", "secret id should not be none or empty")
         if secret_id.strip() != secret_id:
@@ -73,6 +73,11 @@ class Credential(object):
 
 
 class CVMRoleCredential(object):
+    """Tencent Cloud Credential via CVM role
+
+    Automatically generates temporary credentials when binding a service role to instance.
+    See https://cloud.tencent.com/document/product/598/85616 for more information.
+    """
     _metadata_endpoint = "http://metadata.tencentyun.com/latest/meta-data/"
     _role_endpoint = _metadata_endpoint + "cam/security-credentials/"
     # In seconds.
@@ -156,9 +161,20 @@ class CVMRoleCredential(object):
 
 
 class STSAssumeRoleCredential(object):
-    """使用STSAssumeRoleCredential，制动role，
-    可以自动生成临时凭证，并使用临时凭证调用接口
-
+    """Tencent Cloud Credential via STS service
+
+    Automatically generates temporary credentials for API calls.
+
+    :param secret_id: The secret id of your credential.
+    :type secret_id: str
+    :param secret_key: The secret key of your credential.
+    :type secret_key: str
+    :param role_arn: Resource descriptions of a role，see https://cloud.tencent.com/document/api/1312/48197
+    :type role_arn: str
+    :param role_session_name: User-defined temporary session name
+    :type role_session_name: str
+    :param duration_seconds: Specifies the validity period of credentials in seconds. Default value: 7200. Maximum value: 43200
+    :type duration_seconds: int
     """
     _region = "ap-guangzhou"
     _version = '2018-08-13'
@@ -167,17 +183,7 @@ class STSAssumeRoleCredential(object):
 
     def __init__(self, secret_id, secret_key, role_arn, role_session_name, duration_seconds=7200, endpoint=None):
         """
-        :param secret_id: 接口调用凭证id
-        :type secret_id: str
-        :param secret_key: 接口调用凭证key
-        :type secret_key: str
-        https://cloud.tencent.com/document/api/1312/48197
-        :param role_arn: 角色的资源描述，参考官网文档 https://cloud.tencent.com/document/api/1312/48197 中 RoleArn 参数的描述。
-        :type role_arn: str
-        :param role_session_name: 临时会话名称，由用户自定义名称
-        :type role_session_name: str
-        :param duration_seconds: 获取临时凭证的有效期，默认7200s
-        :type duration_seconds: int
+
         """
         self._long_secret_id = secret_id
         self._long_secret_key = secret_key
@@ -221,19 +227,6 @@ class STSAssumeRoleCredential(object):
         return self._token
 
     def _need_refresh(self):
-        """
-        https://cloud.tencent.com/document/api/1312/48197
-        此函数自动使用初始secret_id和secret_key，自动调用上述链接中获取临时凭证的接口，并返回临时凭证
-
-        :param role_arn: 角色的资源描述，上述链接RoleArn参数中有详细获取方式
-        :type role_arn: str
-        :param role_session_name: 临时会话名称，由用户自定义名称
-        :type role_session_name: str
-        :param duration_seconds: 获取临时凭证的有效期，默认7200s
-        :type duration_seconds: int
-
-        """
-
         if None in [self._token, self._tmp_secret_key, self._tmp_secret_id] or self._expired_time < int(time.time()):
             self.get_sts_tmp_role_arn()
 
@@ -260,18 +253,14 @@ class STSAssumeRoleCredential(object):
 
 
 class EnvironmentVariableCredential(object):
+    """Tencent Cloud EnvironmentVariableCredential.
 
-    def get_credential(self):
-        """Tencent Cloud EnvironmentVariableCredential.
-
-        Access https://console.cloud.tencent.com/cam/capi to manage your
-        credentials.
+    Acquire credential from environment variables.
+    Access https://console.cloud.tencent.com/cam/capi to manage your credentials.
+    Set secret id and secret key as `TENCENTCLOUD_SECRET_ID` and `TENCENTCLOUD_SECRET_KEY `in environment variables.
+    """
 
-        :param secret_id: The secret id of your credential, get by environment variable TENCENTCLOUD_SECRET_ID
-        :type secret_id: str
-        :param secret_key: The secret key of your credential. get by environment variable TENCENTCLOUD_SECRET_KEY
-        :type secret_key: str
-        """
+    def get_credential(self):
         self.secret_id = os.environ.get('TENCENTCLOUD_SECRET_ID')
         self.secret_key = os.environ.get('TENCENTCLOUD_SECRET_KEY')
 
@@ -283,23 +272,17 @@ class EnvironmentVariableCredential(object):
 
 
 class ProfileCredential(object):
+    """Tencent Cloud ProfileCredential.
+
+    Access https://console.cloud.tencent.com/cam/capi to manage your credentials.
+    default file position is "~/.tencentcloud/credentials" or "/etc/tencentcloud/credentials", it is ini format.
+    such as:
+    [default]
+    secret_id=""
+    secret_key=""
+    """
 
     def get_credential(self):
-        """Tencent Cloud ProfileCredential.
-
-        Access https://console.cloud.tencent.com/cam/capi to manage your credentials.
-
-        default file position is "~/.tencentcloud/credentials" or "/etc/tencentcloud/credentials", it is ini format.
-        such as:
-        [default]
-        secret_id=""
-        secret_key=""
-
-        :param secret_id: The secret id of your credential.
-        :type secret_id: str
-        :param secret_key: The secret key of your credential.
-        :type secret_key: str
-        """
         home_path = os.environ.get('HOME') or os.environ.get('HOMEPATH')
         if os.path.exists(home_path + "/.tencentcloud/credentials"):
             file_path = home_path + "/.tencentcloud/credentials"
@@ -371,6 +354,7 @@ class DefaultCredentialProvider(object):
 
 
 class DefaultTkeOIDCRoleArnProvider(object):
+    """Acquire credential via TKE IdP automatically."""
     def get_credential(self):
         return self.get_credentials()
 
@@ -382,6 +366,25 @@ class DefaultTkeOIDCRoleArnProvider(object):
 
 
 class OIDCRoleArnCredential(object):
+    """TencentCloud OIDC Credential
+
+    OIDC is an authentication protocol built on OAuth 2.0. Tencent Cloud CAM supports OIDC role-based SSO.
+    See https://cloud.tencent.com/document/product/598/96013 for more information.
+    This will apply for an OIDC role credential automatically.
+
+    :param region: Region for AssumeRoleWithWebIdentity call. See https://cloud.tencent.com/document/product/1312/73070
+    :type region: str
+    :param provider_id: Identity provider name
+    :type provider_id: str
+    :param web_identity_token: OIDC token issued by the IdP
+    :type web_identity_token: str
+    :param role_arn: Role access description name
+    :type role_arn: str
+    :param role_session_name: Session name
+    :type role_session_name: str
+    :param duration_seconds: The validity period of the temporary credential in seconds. Default value: 7200s. Maximum value: 43200s.
+    :type duration_seconds: int
+    """
     _version = '2018-08-13'
     _service = "sts"
     _action = 'AssumeRoleWithWebIdentity'

tencentcloud/common/exception/tencent_cloud_sdk_exception.py

@@ -3,7 +3,7 @@
 import sys
 
 class TencentCloudSDKException(Exception):
-    """tencentcloudapi sdk 异常类"""
+    """tencentcloudapi sdk exception"""
 
     def __init__(self, code=None, message=None, requestId=None):
         self.code = code

tencentcloud/common/profile/client_profile.py

@@ -18,25 +18,27 @@ from tencentcloud.common.profile.http_profile import HttpProfile
 
 
 class ClientProfile(object):
+    """SDK profile.
+
+    :param signMethod: The signature method, valid choice: HmacSHA1, HmacSHA256, TC3-HMAC-SHA256
+    :type signMethod: str
+    :param httpProfile: The http profile
+    :type httpProfile: :class:`HttpProfile`
+    :param language: Valid choice: en-US, zh-CN.
+    :type language: str
+    :param disable_region_breaker: Switch of region breaker.
+    :type disable_region_breaker: bool
+    :param region_breaker_profile: The region breaker profile.
+    :type region_breaker_profile: :class:`RegionBreakerProfile`
+    :param request_client: Custom request client.
+    :type request_client: str
+    :param retryer: Custom retry configuration.
+    :type retryer: :class:`tencentcloud.common.retry.StandardRetryer`
+    """
     unsignedPayload = False
 
     def __init__(self, signMethod=None, httpProfile=None, language="zh-CN",
                  disable_region_breaker=True, region_breaker_profile=None, request_client=None, retryer=None):
-        """SDK profile.
-
-        :param signMethod: The signature method, valid choice: HmacSHA1, HmacSHA256, TC3-HMAC-SHA256
-        :type signMethod: str
-        :param httpProfile: The http profile
-        :type httpProfile: :class:`HttpProfile`
-        :param language: Valid choice: en-US, zh-CN.
-        :type language: str
-        :param disable_region_breaker: Switch of region breaker.
-        :type disable_region_breaker: bool
-        :param region_breaker_profile: The region breaker profile.
-        :type region_breaker_profile: :class:`RegionBreakerProfile`
-        :param request_client: Custom request client.
-        :type request_client: str
-        """
         self.httpProfile = HttpProfile() if httpProfile is None else httpProfile
         self.signMethod = "TC3-HMAC-SHA256" if signMethod is None else signMethod
         valid_language = ["zh-CN", "en-US"]
@@ -59,6 +61,21 @@ class ClientProfile(object):
 
 
 class RegionBreakerProfile(object):
+    """RegionBreaker profile.
+
+    :param backup_endpoint: Backup region of endpoint, default ap-guangzhou.tencentcloudapi.com.
+    :type backup_endpoint: str
+    :param max_fail_num: Max failure to trigger breaker, default 5.
+    :type max_fail_num: int
+    :param max_fail_percent: Max failure percent to trigger breaker, default 0.75.
+    :type max_fail_percent: float
+    :param window_interval: Decides when to reset counter if the state is StateClosed, default 5 minutes.
+    :type window_interval: int
+    :param timeout: Decides when to turn StateOpen to StateHalfOpen, default 60 seconds.
+    :type timeout: int
+    :param max_requests: Decides when to turn StateHalfOpen to StateClosed, default 5 successful requests.
+    :type max_requests: int
+    """
 
     def __init__(self, backup_endpoint="ap-guangzhou.tencentcloudapi.com",
                  max_fail_num=5,
@@ -66,21 +83,6 @@ class RegionBreakerProfile(object):
                  window_interval=60 * 5,
                  timeout=60,
                  max_requests=5):
-        """RegionBreaker profile.
-
-        :param backup_endpoint: Backup region of endpoint, default ap-guangzhou.tencentcloudapi.com.
-        :type backup_endpoint: str
-        :param max_fail_num: Max failure to trigger breaker, default 5.
-        :type max_fail_num: int
-        :param max_fail_percent: Max failure percent to trigger breaker, default 0.75.
-        :type max_fail_percent: float
-        :param window_interval: Decides when to reset counter if the state is StateClosed, default 5 minutes.
-        :type window_interval: int
-        :param timeout: Decides when to turn StateOpen to StateHalfOpen, default 1 minutes.
-        :type timeout: int
-        :param max_requests: Decides when to turn StateHalfOpen to StateClosed, default 5 successful requests.
-        :type timeout: int
-        """
         self.backup_endpoint = backup_endpoint
         if not self.check_endpoint():
             raise TencentCloudSDKException("ClientError", "the format of `backup_endpoint` must be tencentcloudapi.com "

tencentcloud/common/profile/http_profile.py

@@ -14,22 +14,30 @@
 
 
 class HttpProfile(object):
+    """HTTP profile.
+
+    :param protocol: Request schema, http or https, default is https.
+    :type protocol: str
+    :param endpoint: The domain to access, like: cvm.tencentcloudapi.com
+    :type endpoint: str
+    :param reqMethod: The http method, valid choice: GET, POST
+    :type reqMethod: str
+    :param reqTimeout: The http timeout in second.
+    :type reqTimeout: int
+    :param keepAlive: Whether set keep alive.
+    :type keepAlive: bool
+    :param proxy: Custom proxy server, like: http(s)://{user}:{password}@{ip}:{port}.
+    :type proxy: str
+    :param rootDomain: The root domain to access, like: tencentcloudapi.com.
+    :type rootDomain: str
+    :param certification: Custom certificate path (typically not required).
+        Set `False` to disable certificate verification.
+    :type certification: str or bool
+    """
     scheme = "https"
 
     def __init__(self, protocol=None, endpoint=None, reqMethod="POST", reqTimeout=60,
                  keepAlive=False, proxy=None, rootDomain=None, certification=None):
-        """HTTP profile.
-        :param protocol: http or https, default is https.
-        :type protocol: str
-        :param endpoint: The domain to access, like: cvm.tencentcloudapi.com
-        :type endpoint: str
-        :param reqMethod: the http method, valid choice: GET, POST
-        :type reqMethod: str
-        :param reqTimeout: The http timeout in second.
-        :type reqTimeout: int
-        :param rootDomain: The root domain to access, like: tencentcloudapi.com.
-        :type rootDomain: str
-        """
         self.endpoint = endpoint
         self.reqTimeout = 60 if reqTimeout is None else reqTimeout
         self.reqMethod = "POST" if reqMethod is None else reqMethod

tencentcloud/common/retry.py

@@ -5,11 +5,29 @@ from tencentcloud.common.exception import TencentCloudSDKException
 
 
 class NoopRetryer(object):
+    """configuration without retry
+
+    NoopRetryer is a retry policy that does nothing.
+    It is useful when you don't want to retry.
+    """
+
     def send_request(self, fn):
         return fn()
 
 
 class StandardRetryer(object):
+    """Retry configuration
+
+    StandardRetryer is a retry policy that retries on network errors or frequency limitation.
+    :param max_attempts: Maximum number of attempts.
+    :type max_attempts: int
+    :param backoff_fn: A function that takes the number of attempts and returns the number of seconds to sleep before the next retry.
+       Default sleep time is 2^n seconds, n is the number of attempts.
+    :type backoff_fn: function
+    :param logger: A logger to log retry attempts. If not provided, no logging will be performed.
+    :type logger: logging.Logger
+    """
+
     def __init__(self, max_attempts=3, backoff_fn=None, logger=None):
         self._max_attempts = max_attempts
         self._backoff_fn = backoff_fn or self.backoff