Merge pull request #6 from YongSangUn/logging

docs: add README and examples.

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)

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)

examples/test.py → examples/get_cvm.py

@@ -2,7 +2,6 @@
 
 from pyqcloud_sdk import Services
 
-
 logging.basicConfig(level=logging.INFO)