py-easy-wwtl 1.0.0
一个简化微网通联API使用的Python工具包，提供短信发送和服务器API调用的便捷封装。
Requires Python: >=3.6

# py-easy-wwtl

一个简化微网通联API使用的Python工具包，提供短信发送和服务器API调用的便捷封装。

## 功能特性

- **短信发送**：支持微网通联短信平台的短信发送
- **同步与异步**：同时支持同步和异步操作
- **响应处理**：统一的响应处理机制，自动验证响应结果
- **签名生成**：内置SHA256签名生成功能
- **类型提示**：完整的类型注解，提供良好的IDE支持

## 安装

### 使用pip安装

```bash
pip install py-easy-wwtl
```

### 从源码安装

```bash
git clone https://gitee.com/guolei19850528/py_easy_wwtl.git
cd py_easy_wwtl
pip install -e .
```

## 依赖

- httpx
- jsonschema
- jsonpath-ng

## 快速开始

### 短信发送

```python
from py_easy_wwtl.sms import Sms

# 初始化Sms实例
sms = Sms(
    account_id="YOUR_ACCOUNT_ID",  # 微网通联账号ID
    password="YOUR_PASSWORD",      # 微网通联账号密码
    product_id="YOUR_PRODUCT_ID"   # 产品ID
)

# 发送短信
response = sms.send_sms(
    phone_nos="13800138000",  # 手机号，多个手机号用逗号分隔
    content="【金泰物业】您的验证码为123456，5分钟内有效"  # 短信内容
)

print(f"发送结果: {response.validated}")
if response.validated:
    print("短信发送成功！")
else:
    print("短信发送失败！")
```

### 异步短信发送

```python
import asyncio
from py_easy_wwtl.sms import Sms

async def main():
    sms = Sms(
        account_id="YOUR_ACCOUNT_ID",
        password="YOUR_PASSWORD",
        product_id="YOUR_PRODUCT_ID"
    )
    
    # 异步发送短信
    response = await sms.async_send_sms(
        phone_nos="13800138000",
        content="【金泰物业】您的验证码为123456，5分钟内有效"
    )
    
    print(f"发送结果: {response.validated}")
    if response.validated:
        print("短信发送成功！")
    else:
        print("短信发送失败！")

asyncio.run(main())
```

## API文档

### Sms类

#### 初始化参数
- `base_url`：API基础URL，默认为"https://api.51welink.com/"
- `account_id`：微网通联账号ID
- `password`：微网通联账号密码
- `product_id`：产品ID
- `smms_encrypt_key`：加密密钥，默认为"SMmsEncryptKey"
- `client_kwargs`：传递给httpx.Client的额外参数

#### 方法
- `client(**kwargs)`：创建同步客户端实例
- `async_client(**kwargs)`：创建异步客户端实例
- `request(client=None, **kwargs)`：同步请求方法
- `async_request(client=None, **kwargs)`：异步请求方法
- `send_sms(client=None, phone_nos="", content="", **kwargs)`：同步发送短信
- `async_send_sms(client=None, phone_nos="", content="", **kwargs)`：异步发送短信

### 工具函数

#### sha256_signature

```python
def sha256_signature(
        account_id: str = "",
        password: str = "",
        phone_nos: str = "",
        random_digits: Optional[Union[int, str]] = "",
        timestamp: Optional[Union[int, str]] = "",
        smms_encrypt_key: str = ""
) -> str:
    """
    生成SHA256签名

    Args:
        account_id: 账号ID
        password: 密码
        phone_nos: 手机号，多个手机号用逗号分隔
        random_digits: 随机数字
        timestamp: 时间戳
        smms_encrypt_key: 加密密钥

    Returns:
        str: SHA256签名结果
    """
```

### 响应处理

所有API调用都会返回`RequestResponse`对象，包含以下属性：
- `validated`：响应是否有效
- `value`：从响应中提取的值
- `json`：响应的JSON数据
- `response`：原始的httpx.Response对象

## 测试

运行测试用例：

```bash
python -m unittest test_wwtl_sms.py
```

## 项目结构

```
py-easy-wwtl/
├── py_easy_wwtl/
│   ├── __init__.py        # 模块初始化和响应处理
│   └── sms.py             # 短信发送类
├── test_wwtl_sms.py       # 短信发送测试
├── setup.py               # 安装配置
├── requirements.txt       # 依赖声明
├── LICENSE                # 许可证
└── README.md              # 项目文档
```

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！

## 联系方式

- 作者：guolei
- 邮箱：174000902@qq.com
- 项目地址：https://gitee.com/guolei19850528/py_easy_wwtl