Metadata-Version: 2.4
Name: pywwtl
Version: 1.0.0
Summary: 微网通联（SMMS）短信平台的 Python SDK，支持同步和异步两种调用方式。
Home-page: https://gitee.com/guolei19850528/pywwtl
Author: guolei
Author-email: 174000902@qq.com
License: MIT
Keywords: 微网通联 短信
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx
Requires-Dist: jsonschema
Requires-Dist: decorator
Requires-Dist: jsonpath-ng
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# pywwtl - 微网通联 API Python SDK

微网通联（SMMS）短信平台的 Python SDK，支持同步和异步两种调用方式。

## 功能特性

- ✅ 同步短信发送
- ✅ 异步短信发送
- ✅ 自动签名生成（SHA256）
- ✅ 参数自动组装
- ✅ JSON Schema 响应校验

## 安装

```bash
pip install pywwtl
```

## 快速开始

### 同步发送

```python
from pywwtl import Sms

# 初始化客户端
sms = Sms(
    account_id="your_account_id",
    password="your_password",
    product_id="your_product_id",
    smms_encrypt_key="your_encrypt_key"
)

# 发送短信
response = sms.send(
    phone_nos="13800138000",
    content="【微网通联】您的验证码是：1234"
)

# 检查发送结果
from pywwtl.utils import get_send_result
if get_send_result(response):
    print("发送成功")
else:
    print("发送失败")
```

### 异步发送

```python
import asyncio
from pywwtl import Sms

async def main():
    # 初始化异步客户端
    sms = Sms(
        account_id="your_account_id",
        password="your_password",
        use_async_client=True
    )

    # 异步发送短信
    response = await sms.async_send(
        phone_nos="13800138000,13900139000",
        content="【微网通联】您的验证码是：1234"
    )

    print(response.json())

asyncio.run(main())
```

## API 文档

### Sms 类

#### 初始化参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| account_id | str | 是 | - | 微网通联账号ID |
| password | str | 是 | - | 账号密码 |
| product_id | str | 否 | "" | 产品ID |
| base_url | str | 否 | "https://api.51welink.com/" | API基础URL |
| smms_encrypt_key | str | 否 | "SMmsEncryptKey" | 加密密钥 |
| client_kwargs | dict | 否 | {} | httpx客户端参数 |
| use_async_client | bool | 否 | False | 是否使用异步客户端 |

#### send() 方法 - 同步发送

```python
def send(
    client: Optional[httpx.Client] = None,
    phone_nos: Optional[str] = "",
    content: Optional[str] = "",
    **kwargs
) -> httpx.Response
```

**参数说明**：
- `client`: 可选的同步客户端实例
- `phone_nos`: 目标手机号，多个用逗号分隔，如 "13800138000,13900139000"
- `content`: 短信内容
- `**kwargs`: 传递给httpx.Client.request的额外参数

**返回值**：`httpx.Response` 对象

#### async_send() 方法 - 异步发送

```python
async def async_send(
    client: Optional[httpx.AsyncClient] = None,
    phone_nos: Optional[str] = "",
    content: Optional[str] = "",
    **kwargs
) -> httpx.Response
```

**参数说明**：
- `client`: 可选的异步客户端实例
- `phone_nos`: 目标手机号，多个用逗号分隔
- `content`: 短信内容
- `**kwargs`: 传递给httpx.AsyncClient.request的额外参数

**返回值**：`httpx.Response` 对象

### 工具函数

#### get_send_result() - 判断发送结果

```python
from pywwtl.utils import get_send_result

response = sms.send(phone_nos="13800138000", content="test")
if get_send_result(response):
    print("发送成功")
```

#### json_find_first() - JSONPath 数据提取

```python
from pywwtl.utils import json_find_first

data = {"data": {"items": [{"id": 1, "name": "test"}]}}
value = json_find_first("$.data.items[0].name", data)
# value = "test"
```

#### json_is_valid() - JSON Schema 校验

```python
from pywwtl.utils import json_is_valid

schema = {"type": "object", "properties": {"Result": {"type": "string"}}}
data = {"Result": "succ"}
if json_is_valid(schema, data):
    print("校验通过")
```

## 响应示例

成功响应：
```json
{
    "Result": "succ",
    "MsgId": "1234567890",
    "Desc": "发送成功"
}
```

失败响应：
```json
{
    "Result": "fail",
    "Desc": "账号不存在"
}
```

## 注意事项

1. **签名机制**：SDK 会自动生成 SHA256 签名，无需手动处理
2. **手机号格式**：多个手机号用英文逗号分隔，如 "13800138000,13900139000"
3. **超时设置**：默认超时时间为60秒，可通过 `client_kwargs` 调整
4. **SSL验证**：默认禁用SSL验证，适应内部环境

## 技术栈

- Python 3.10+
- httpx - HTTP客户端
- jsonschema - JSON Schema校验
- jsonpath-ng - JSONPath解析

## 许可证

MIT License

## 作者

- **Author**: guolei
- **Email**: 174000902@qq.com

## 项目主页

[https://gitee.com/guolei19850528/pywwtl](https://gitee.com/guolei19850528/pywwtl)
