Merge "integration_2026-01-22_1106749899266" into "cloudmonitor-Python-2018-01-01-online-1907-2025_12_03_14_17_08"

Conflicts:
pyproject.toml

Author: bytestarter

FAQ.EN.md

@@ -0,0 +1,96 @@
+### 1. Get Request and Response Types
+
+Before calling a method, you can obtain the corresponding request and response structures via `param` and `return`.
+Taking `ecs.run_instances` as an example:
+
+```python
+def run_instances(self, body, **kwargs):  # noqa: E501
+    """run_instances
+    :param RunInstancesRequest body: (required)
+    :return: RunInstancesResponse
+    """
+```
+
+### 2. Get Parameter Types for Requests and Responses
+
+In the Request or Response body, you can check specific request parameters and their types via `swagger_types`.
+Taking `volcenginesdkecs.RunInstancesRequest` as an example, its parameter names and definitions are as follows:
+
+```python
+swagger_types = {
+    'auto_renew': 'bool',
+    'auto_renew_period': 'int',
+    'client_token': 'str',
+    'count': 'int',
+    'network_interfaces': 'list[NetworkInterfaceForRunInstancesInput]',
+    'security_enhancement_strategy': 'str',
+    'volumes': 'list[VolumeForRunInstancesInput]',
+    ......
+}
+```
+
+The corresponding request body is:
+
+```python
+volcenginesdkecs.RunInstancesRequest(
+    instance_name="insname",
+    network_interfaces=[volcenginesdkecs.NetworkInterfaceForRunInstancesInput(
+        subnet_id="subnet-2d68bh73d858ozfekrm8fj",
+        security_group_ids=["sg-2b3dq7v0ha0w2dx0eg0nhljv"],
+    )],
+    image_id="image-ybvz29l3da4ox5h0m9",
+    volumes=[volcenginesdkecs.VolumeForRunInstancesInput(
+        volume_type="ESSD",
+        size=40,
+    )],
+    key_pair_name="vtable",
+    instance_charge_type="PostPaid"
+)
+```
+
+### 3. Memory Overflow Occurs
+
+Check whether `Configuration._default` has been initialized.
+If not, each time you create a `Configuration` instance, a new logger handler will be created and added to the global logger.
+It is recommended to set the default configuration via `Configuration.set_default`.
+
+```python
+configuration = volcenginesdkcore.Configuration()
+configuration.client_side_validation = False
+configuration.schema = "http"  # https or http
+configuration.debug = False  # Whether to enable debugging
+
+volcenginesdkcore.Configuration.set_default(configuration)
+```
+
+### 4. Convert Object to Dict
+
+For request and response objects, you can convert them to `dict` using the `to_dict()` method.
+
+### 5. View Usage Examples
+
+[volcenginesdkexamples](https://github.com/volcengine/volcengine-python-sdk/tree/master/volcenginesdkexamples)
+
+### 6. Convert Response Object to CamelCase Dict
+
+After calling an API, the parameters in the received response object typically use PascalCase (CamelCase with the first letter capitalized). When coding with the Python SDK, since Python generally uses snake_case, you may want to convert between the SDK's snake_case fields and the documentation's CamelCase fields.
+
+You can convert the response object into a CamelCase dictionary with the following code. After conversion, the field names in the dictionary will be exactly the same as those in the documentation.
+
+```python
+import json
+import pprint
+from volcenginesdkcore.model import canonical_str
+
+try:
+    resp = api_instance.list_users(req)
+    pprint(resp)  # Response object with snake_case fields
+    dict_resp = json.loads(json.dumps(canonical_str(resp)))
+    pprint(dict_resp)  # Response dict with CamelCase fields
+
+except ApiException as e:
+    print("Exception when calling IAMApi->ListUsers: %s\n" % e)
+
+```
+
+However, this is not the recommended approach. It is suggested to directly use the snake_case parameters in the response object instead of converting.

README.EN.MD

@@ -0,0 +1,205 @@
+English | [中文](README.md)
+
+# Volcengine SDK for Python
+## ⚠️ Known Issue (Historical Versions)
+
+In some historical versions of **volcengine-python-sdk** (**4.0.1 – 4.0.42**, inclusive), the SDK’s built-in retry mechanism has a defect.
+
+When a request encounters an exception (such as network instability or API errors), the SDK may trigger its retry logic internally; however, due to this defect, the retry does not take effect as expected. As a result, the client may still experience the exception from the initial request, and the retry mechanism cannot effectively improve request success rates.
+
+### Affected Versions
+
+- **SDK**: volcengine-python-sdk  
+- **Versions**: 4.0.1 – 4.0.42 (inclusive)
+
+### Impact
+
+For applications that rely on the SDK’s retry mechanism to handle transient failures or network instability:
+
+- Actual request availability may be lower than expected  
+- Retry configurations may not function as intended  
+
+### Resolution and Recommendation
+
+This issue has been fixed in **version 4.0.43 and above**.  
+**We strongly recommend all users upgrade to volcengine-python-sdk ≥ 4.0.43** to ensure the retry mechanism functions correctly in exception scenarios.
+
+## Breaking Change Notice
+
+Breaking change notice for Volcengine SDK for Python.
+
+Affected versions: `3.0.1` and later
+
+Change description:
+
+To address installation failures on Windows caused by excessively long package paths, starting from `3.0.1` we shortened some overly long API model filenames under the `transitrouter` service. If you depended on those full model filenames, this change is not backward compatible. Use the shortened model name as follows:
+
+```python
+from volcenginesdktransitrouter import TransitRouterBandwidthPackageForDescribeTransitRouterBandwidthPackagesOutput
+
+var = TransitRouterBandwidthPackageForDescribeTransitRouterBandwidthPackagesOutput()
+```
+
+Impacted service and APIs:
+
+Service: `transitrouter`
+
+Version: `2020-04-01`
+
+APIs:
+
+- DescribeTransitRouterBandwidthPackages
+- DescribeTransitRouterRoutePolicyTables
+- DescribeTransitRouterRoutePolicyEntries
+- DescribeTransitRouterForwardPolicyTables
+- DescribeTransitRouterBandwidthPackagesBilling
+- DescribeTransitRouterDirectConnectGatewayAttachments
+- DescribeTransitRouterRouteTableAssociations
+- DescribeTransitRouterRouteTablePropagations
+- DescribeTransitRouterTrafficQosQueueEntries
+- DescribeTransitRouterTrafficQosQueuePolicies
+- DescribeTransitRouterTrafficQosMarkingEntries
+- DescribeTransitRouterTrafficQosMarkingPolicies
+
+--------
+
+Affected versions: `2.0.1` and later
+
+Change description:
+
+Starting from `2.0.1`, the default request protocol changes from **HTTP** to **HTTPS**. After upgrading, ensure you test for compatibility risks. If you must continue using HTTP (not recommended), set `scheme` to `http`:
+
+```python
+import volcenginesdkcore
+
+configuration = volcenginesdkcore.Configuration()
+configuration.scheme = 'http'
+```
+
+## Table of Contents
+
+* Requirements
+* Install
+* Usage
+* FAQ
+
+### Requirements
+
+* Python version **>= 2.7**.
+* On Windows, installation may fail due to maximum path length limitations. Configure it as follows:
+
+```
+1. Press Win+R, type regedit to open Registry Editor.
+2. Set LongPathsEnabled to 1 at:
+   HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem
+```
+
+### Install
+
+Install via pip:
+
+```sh
+pip install volcengine-python-sdk
+```
+
+Install via [Setuptools](http://pypi.python.org/pypi/setuptools):
+
+```sh
+python setup.py install --user
+```
+
+(Or `sudo python setup.py install` to install for all users)
+
+### Configuration Usage
+
+Step 1: initialize and configure global defaults
+
+```python
+configuration = volcenginesdkcore.Configuration()
+configuration.client_side_validation = True  # enable client-side validation
+configuration.schema = "http"  # https or http
+configuration.debug = False
+configuration.logger_file = "sdk.log"
+
+volcenginesdkcore.Configuration.set_default(configuration)
+```
+
+Step 2: get the client
+
+```python
+def get_client(ak, sk, region):
+    configuration = volcenginesdkcore.Configuration()
+    configuration.ak = ak
+    configuration.sk = sk
+    configuration.region = region
+    client = volcenginesdkautoscaling.AUTOSCALINGApi(volcenginesdkcore.ApiClient(configuration))
+    return client
+```
+
+### Endpoint Configuration
+
+To customize the endpoint:
+
+```python
+configuration = volcenginesdkcore.Configuration()
+configuration.host = 'ecs.cn-beijing-autodriving.volcengineapi.com'
+```
+
+Standard endpoint rules:
+
+| Regional Service | Global Service |
+|---|---|
+| `{service}.{region}.volcengineapi.com` <br> e.g. `ecs.cn-beijing-autodriving.volcengineapi.com` | `{service}.volcengineapi.com` <br> e.g. `iam.volcengineapi.com` |
+
+Note:
+
+- If the service name contains `_`, it should be converted to `-` in the endpoint. Use lowercase for all characters.
+
+### SDK Example
+
+```python
+from __future__ import print_function
+import volcenginesdkecs
+import volcenginesdkcore
+from pprint import pprint
+from volcenginesdkcore.rest import ApiException
+
+if __name__ == '__main__':
+    configuration = volcenginesdkcore.Configuration()
+    configuration.ak = "Your AK"
+    configuration.sk = "Your SK"
+    configuration.region = "cn-beijing"
+    configuration.client_side_validation = True
+    volcenginesdkcore.Configuration.set_default(configuration)
+
+    api_instance = volcenginesdkecs.ECSApi()
+
+    try:
+        resp = api_instance.run_instances(
+            volcenginesdkecs.RunInstancesRequest(
+                instance_name="insname",
+                instance_type="ecs.g1.large",
+                zone_id="cn-beijing-a",
+                network_interfaces=[volcenginesdkecs.NetworkInterfaceForRunInstancesInput(
+                    subnet_id="subnet-2d68bh73d858ozfekrm8fj",
+                    security_group_ids=["sg-2b3dq7v0ha0w2dx0eg0nhljv"],
+                )],
+                image_id="image-ybvz29l3da4ox5h0m9",
+                volumes=[volcenginesdkecs.VolumeForRunInstancesInput(
+                    volume_type="ESSD",
+                    size=40,
+                )],
+                key_pair_name="vtable",
+                instance_charge_type="PostPaid"
+            ))
+        pprint(resp)
+    except ApiException as e:
+        print("Exception when calling ECSApi->run_instances: %s\n" % e)
+```
+
+For more examples, see: [SDK Integration Guide](./SDK_Integration.md)
+
+### FAQ
+
+For common issues when using the SDK, see [FAQ](FAQ.EN.md).
+

README.md

@@ -1,5 +1,31 @@
+中文 | [English](README.EN.MD)
+
 # Volcengine SDK for Python
 
+## ⚠️ 已知缺陷说明（历史版本）
+
+在 **volcengine-python-sdk** 的部分历史版本（**4.0.1 ～ 4.0.42，含**）中，发现 SDK 内置的重试机制存在缺陷。
+
+当请求过程中出现异常（如网络抖动、接口返回错误等）时，SDK 虽会触发重试逻辑，但由于该缺陷，重试未能实际生效，客户端仍可能直接感知到首次请求异常，导致重试机制无法有效提升请求成功率。
+
+### 影响范围
+
+- **SDK**：volcengine-python-sdk  
+- **受影响版本**：4.0.1 ～ 4.0.42（含）
+
+### 影响说明
+
+对于依赖 SDK 内置重试机制来应对瞬时异常或网络不稳定场景的业务：
+
+- 实际请求可用性可能低于预期  
+- 重试相关配置无法发挥应有的保障作用  
+
+### 解决方案与建议
+
+该问题已在 **4.0.43 及以上版本**中修复。  
+**强烈建议所有用户升级至 volcengine-python-sdk ≥ 4.0.43**，以确保请求重试机制在异常场景下能够正常生效。
+
+
 ## 非兼容升级通知
 
 Volcengine SDK for Python 非兼容升级通知
@@ -184,4 +210,4 @@ if __name__ == '__main__':
 
 ### FAQ ###
 
-关于 SDK 使用时碰到的常见问题，请查看 [FAQ](FAQ.md)
+关于 SDK 使用时碰到的常见问题，请查看 [FAQ](FAQ.md)