tencentcloud-sdk-python 3.0.1361__py2.py3-none-any.whl → 3.0.1363__py2.py3-none-any.whl

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

tencentcloud/cvm/v20170312/cvm_client.py

@@ -53,6 +53,9 @@ class CvmClient(AbstractClient):
     def AssociateInstancesKeyPairs(self, request):
         """本接口 (AssociateInstancesKeyPairs) 用于将密钥绑定到实例上。
 
+        * 仅支持对 `Linux` 操作系统实例进行绑定操作。
+        * 非强制关机场景下，仅支持对 [STOPPED](https://cloud.tencent.com/document/product/213/15753#InstanceStatus) 状态实例进行绑定操作。
+        * 强制关机场景下，先执行强制关机，再绑定密钥；如实例原状态为 [RUNNING](https://cloud.tencent.com/document/product/213/15753#InstanceStatus)，绑定完成后实例会自动开机。
         * 将密钥的公钥写入到实例的`SSH`配置当中，用户就可以通过该密钥的私钥来登录实例。
         * 如果实例原来绑定过密钥，那么原来的密钥将失效。
         * 如果实例原来是通过密码登录，绑定密钥后无法使用密码登录。
@@ -1268,7 +1271,9 @@ class CvmClient(AbstractClient):
     def DisassociateInstancesKeyPairs(self, request):
         """本接口 (DisassociateInstancesKeyPairs) 用于解除实例的密钥绑定关系。
 
-        * 只支持[`STOPPED`](https://cloud.tencent.com/document/product/213/15753#InstanceStatus)状态的`Linux`操作系统的实例。
+        * 仅支持对 Linux 操作系统实例进行解绑操作。
+        * 非强制关机场景下，仅支持对 [STOPPED](https://cloud.tencent.com/document/product/213/15753#InstanceStatus) 状态实例进行解绑操作。
+        * 强制关机场景下，先执行强制关机，再解绑密钥；如实例原状态为 [RUNNING](https://cloud.tencent.com/document/product/213/15753#InstanceStatus)，解绑完成后实例会自动开机。
         * 解绑密钥后，实例可以通过原来设置的密码登录。
         * 如果原来没有设置密码，解绑后将无法使用 `SSH` 登录。可以调用 [ResetInstancesPassword](https://cloud.tencent.com/document/api/213/15736) 接口来设置登录密码。
         * 支持批量操作。每次请求批量实例的上限为100。如果批量实例存在不允许操作的实例，操作会以特定错误码返回。
@@ -2431,6 +2436,7 @@ class CvmClient(AbstractClient):
         * 默认扩容方式为关机后扩容。
         * 实例操作结果可以通过调用 [DescribeInstances](https://cloud.tencent.com/document/api/213/15728#.E7.A4.BA.E4.BE.8B3-.E6.9F.A5.E8.AF.A2.E5.AE.9E.E4.BE.8B.E7.9A.84.E6.9C.80.E6.96.B0.E6.93.8D.E4.BD.9C.E6.83.85.E5.86.B5) 接口查询，如果实例的最新操作状态(LatestOperationState)为“SUCCESS”，则代表操作成功。
         * 如果是系统盘，目前只支持扩容，不支持缩容。
+        *  如果是运行中的实例，必须指定ForceStop或ResizeOnline任意一个参数为true，否则操作失败。
 
         :param request: Request instance for ResizeInstanceDisks.
         :type request: :class:`tencentcloud.cvm.v20170312.models.ResizeInstanceDisksRequest`