diff --git a/README.md b/README.md index 5293a4a..1495684 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,99 @@ -# PyQCloud SDK +# pyqcloud-sdk -PyQCloud SDK 是一个用于简化调用腾讯云 API 的 Python 库。通过使用 `tencentcloud-sdk-python-common` 包和预先爬取的 `endpoints_*.json` 数据文件,该 SDK 提供了便捷的方式来与腾讯云的各种服务进行交互。 +**English** · [简体中文](./README.zh-CN.md) -## 使用 +[![Python Versions](https://img.shields.io/pypi/pyversions/pyqcloud-sdk.svg)](https://pypi.org/project/pyqcloud-sdk) +[![PyPI version](https://badge.fury.io/py/pyqcloud-sdk.svg)](https://badge.fury.io/py/pyqcloud-sdk) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -以下是一个简单的使用示例: +pyqcloud-sdk is a Python package that simplifies the calling of Tencent Cloud product APIs. With just a product ID, region, operation code, and request parameters, you can achieve API calls. The main features are: + +- Simplified and unified API calling method +- Automatic handling of authentication, region, and client settings +- Supports all services supported by the original SDK +- Supports custom log configuration +- Based on tencentcloud-sdk-python-common, providing a higher-level abstraction +- Pre-fetches product interface information from [tencentcloud-sdk-python](https://github.com/TencentCloud/tencentcloud-sdk-python/tree/master/tencentcloud) + +## Installation + +Install using pip: + +```console +pip install pyqcloud-sdk +``` + +Supports Python 3.6+ + +## Quick Start ```python -from pyqcloud_sdk import Services +import logging +from pyqcloud_sdk import Services, setup_logging + +# Set up logging (optional) +setup_logging(level=logging.INFO) -cvm = Services("cvm", "ap-shanghai") -action = "DescribeInstances" -params = {"Limit": 1} -err, res = cvm.call(action, params) # 或者 cvm.call_wite_retry(action, params) -print(err, res) +# Initialize service +service = Services( + name="cvm", # Service name, required + region="ap-guangzhou", # Region, required + secret_id="your_secret_id", # Optional, default reads from environment variable + secret_key="your_secret_key", # Optional, default reads from environment variable + version="2017-03-12" # Optional, API version, default is the latest version +) + +# Call API +response = service.call("DescribeInstances", {"Limit": 1}) +print(response) +``` + +## Authentication Configuration + +It is recommended to set authentication information using environment variables: + +- Default reads `TENCENTCLOUD_SECRET_ID` and `TENCENTCLOUD_SECRET_KEY` +- Use `set_secret_from_env()` to specify custom environment variable names: + +```python +service.set_secret_from_env('CUSTOM_ID_ENV', 'CUSTOM_KEY_ENV') ``` -## 许可证 +## Error Handling + +```python +from pyqcloud_sdk.exceptions import ServiceError, ClientError + +try: + response = service.call("DescribeInstances", {}) +except ServiceError as e: + print(f"Service error: {e}") +except ClientError as e: + print(f"Client error: {e}") +... +``` + +## Custom Logging + +```python +from pyqcloud_sdk import setup_logging +import logging + +setup_logging(level=logging.DEBUG, format="%(asctime)s - %(levelname)s - %(message)s") +``` + +## Notes + +1. Keep SecretId and SecretKey safe and avoid leakage. +2. In production environments, it is recommended to store sensitive information using environment variables or configuration files. +3. This package automatically handles most API call retries, but special cases may require custom retry logic. +4. Before using, ensure that the necessary access permissions have been granted in the Tencent Cloud console and that the corresponding services have been enabled. + +## License + +This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. + +## Related Links -该项目基于 MIT 许可证开源。详情请参阅 LICENSE 文件。 +- [Tencent Cloud API Documentation](https://cloud.tencent.com/document/api) +- [tencentcloud-sdk-python](https://github.com/TencentCloud/tencentcloud-sdk-python) diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..607ae02 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,99 @@ +# pyqcloud-sdk + +[English](./README.md) · **简体中文** + +[![Python Versions](https://img.shields.io/pypi/pyversions/pyqcloud-sdk.svg)](https://pypi.org/project/pyqcloud-sdk) +[![PyPI version](https://badge.fury.io/py/pyqcloud-sdk.svg)](https://badge.fury.io/py/pyqcloud-sdk) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + +pyqcloud-sdk 是一个简化腾讯云产品 API 调用的 Python 包。只需使用产品 ID、地域、执行操作代码及请求参数即可实现调用,主要特性: + +- 简化及统一 API 调用方式 +- 自动处理认证、区域等客户端设置 +- 支持所有原 SDK 中支持的服务 +- 支持自定义日志配置 +- 基于 tencentcloud-sdk-python-common 提供更高层次的抽象 +- 预先爬取 [tencentcloud-sdk-python](https://github.com/TencentCloud/tencentcloud-sdk-python/tree/master/tencentcloud) 中的产品接口信息 + +## 安装 + +使用 pip 安装: + +```console +pip install pyqcloud-sdk +``` + +支持 Python 3.6+ + +## 快速开始 + +```python +import logging +from pyqcloud_sdk import Services, setup_logging + +# 设置日志(可选) +setup_logging(level=logging.INFO) + +# 初始化服务 +service = Services( + name="cvm", # 服务名称,必填 + region="ap-guangzhou", # 区域,必填 + secret_id="your_secret_id", # 可选,默认读取环境变量 + secret_key="your_secret_key", # 可选,默认读取环境变量 + version="2017-03-12" # 可选,API 版本,默认为最新版本 +) + +# 调用 API +response = service.call("DescribeInstances", {"Limit": 1}) +print(response) +``` + +## 认证配置 + +推荐使用环境变量设置认证信息: + +- 默认读取 `TENCENTCLOUD_SECRET_ID` 和 `TENCENTCLOUD_SECRET_KEY` +- 使用 `set_secret_from_env()` 指定自定义环境变量名: + +```python +service.set_secret_from_env('CUSTOM_ID_ENV', 'CUSTOM_KEY_ENV') +``` + +## 错误处理 + +```python +from pyqcloud_sdk.exceptions import ServiceError, ClientError + +try: + response = service.call("DescribeInstances", {}) +except ServiceError as e: + print(f"服务错误: {e}") +except ClientError as e: + print(f"客户端错误: {e}") +... +``` + +## 自定义日志 + +```python +from pyqcloud_sdk import setup_logging +import logging + +setup_logging(level=logging.DEBUG, format="%(asctime)s - %(levelname)s - %(message)s") +``` + +## 注意事项 + +1. 妥善保管 SecretId 和 SecretKey,避免泄露。 +2. 生产环境建议使用环境变量或配置文件存储敏感信息。 +3. 本包自动处理大多数 API 调用重试,特殊情况可能需要自定义重试逻辑。 +4. 使用前确保已在腾讯云控制台开通相应服务并获取必要访问权限。 + +## 许可证 + +本项目采用 MIT 许可证。详情请参见 [LICENSE](LICENSE) 文件。 + +## 相关链接 + +- [腾讯云 API 文档](https://cloud.tencent.com/document/api) +- [tencentcloud-sdk-python](https://github.com/TencentCloud/tencentcloud-sdk-python) diff --git a/examples/test.py b/examples/get_cvm.py similarity index 99% rename from examples/test.py rename to examples/get_cvm.py index 3166854..b9550c9 100644 --- a/examples/test.py +++ b/examples/get_cvm.py @@ -2,7 +2,6 @@ from pyqcloud_sdk import Services - logging.basicConfig(level=logging.INFO)