Metadata-Version: 2.4
Name: py-lmobile-toolkit
Version: 3.0.2
Summary: 乐信（51welink）短信服务 Python SDK，提供同步和异步接口调用，支持签名认证
Author-email: Guolei <174000902@qq.com>
License: MIT License
        
        Copyright (c) 2026 郭磊
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://gitee.com/guolei19850528/py_lmobile_toolkit
Project-URL: Repository, https://gitee.com/guolei19850528/py_lmobile_toolkit.git
Project-URL: Documentation, https://www.lmobile.cn/ApiPages/index.html
Keywords: lmobile,51welink,python,client,api,短信,sms,乐信
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Communications
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
Dynamic: license-file

# py-lmobile-toolkit

#### 介绍

`py-lmobile-toolkit` 是乐信（51welink）短信开放平台的非官方 Python 客户端库，封装官方 HTTP API，提供同步客户端 `SmsClient` 和异步客户端 `AsyncSmsClient`（方法名完全一致，异步客户端支持 `async with` 上下文管理器），签名采用 MD5 + SHA256，响应模型基于 Pydantic v2。

- 项目主页：https://gitee.com/guolei19850528/py_lmobile_toolkit
- PyPI：https://pypi.org/project/py-lmobile-toolkit/
- 官方 API 文档：https://www.lmobile.cn/ApiPages/index.html
- 许可证：[MIT License](LICENSE)

#### 软件架构

```
py_lmobile_toolkit/
├── sms/
│   ├── __init__.py
│   ├── auth.py       # 签名生成（MD5/SHA256/时间戳/随机数）
│   ├── client.py     # SmsClient（同步）与 AsyncSmsClient（异步）
│   └── models.py     # Pydantic 响应模型
```

核心组件：
- `SmsClientConfig`：客户端配置（base_url、account_id、password、product_id、smms_encrypt_key），基于 Pydantic 校验
- `SmsClient`：同步 HTTP 客户端，支持 `with` 上下文管理器
- `AsyncSmsClient`：异步 HTTP 客户端，支持 `async with` 上下文管理器，方法名与 `SmsClient` 完全一致
- `SmsBaseResponse` 及各接口响应模型：`Result` 字段标识成功/失败，`extra="allow"` 兼容 API 扩展字段

#### 安装教程

推荐使用 uv：

```bash
uv add py-lmobile-toolkit
```

或从本地源码安装（开发模式）：

```bash
uv pip install -e .
uv pip install -e ".[dev]"
```

或者使用 pip：

```bash
pip install py-lmobile-toolkit
pip install -e .
pip install -e ".[dev]"
```

#### 使用说明

##### 快速开始

同步调用：

```python
from py_lmobile_toolkit.sms.client import SmsClient

with SmsClient(
    account_id="your_account_id",
    password="your_password",
    product_id="your_product_id",
) as sms:
    response = sms.send_sms(
        phone_nos="13800138000",
        content="【乐信】您的验证码是：123456",
    )
    print(f"成功: {response.ok}, 结果码: {response.Result}")
```

异步调用：

```python
import asyncio
from py_lmobile_toolkit.sms.client import AsyncSmsClient


async def main():
    async with AsyncSmsClient(
        account_id="your_account_id",
        password="your_password",
        product_id="your_product_id",
    ) as sms:
        response = await sms.send_sms(
            phone_nos=["13800138000"],
            content="【乐信】批量发送测试",
        )
        print(f"成功: {response.ok}, 结果码: {response.Result}")


asyncio.run(main())
```

##### 已实现的接口

| 分类 | 接口 | 同步方法 | 异步方法 | 响应模型 | 端点状态 |
|------|------|----------|----------|----------|----------|
| 短信API | 提交短信 | `send_sms` / `send` | `send_sms` / `send` | `SmsSendSmsResponse` | ✅ 已知可靠 |
| 短信API | 提交个性化短信(变量XML格式) | `send_personalized_xml` | `send_personalized_xml` | `SmsBaseResponse` | [待核实] |
| 短信API | 提交个性化短信(变量Json格式) | `send_personalized_json` | `send_personalized_json` | `SmsBaseResponse` | [待核实] |
| 短信API | 拉取状态报告 | `pull_status_report` | `pull_status_report` | `SmsPullReportResponse` | [待核实] |
| 短信API | 拉取上行信息 | `pull_mo_message` | `pull_mo_message` | `SmsPullMoResponse` | [待核实] |
| 短信API | 取消定时消息发送 | `cancel_scheduled_sms` | `cancel_scheduled_sms` | `SmsCancelScheduledResponse` | [待核实] |
| 模板短信API | 提交模板短信 | `submit_template_sms` | `submit_template_sms` | `SmsSubmitTemplateSmsResponse` | [待核实] |
| 模板短信API | 提交个性化模板短信 | `submit_personalized_template_sms` | `submit_personalized_template_sms` | `SmsBaseResponse` | [待核实] |
| 模板短信API | 短信模板报备 | `register_template` | `register_template` | `SmsRegisterTemplateResponse` | [待核实] |
| 模板短信API | 视频短信模板报备 | `register_video_template` | `register_video_template` | `SmsRegisterVideoTemplateResponse` | [待核实] |
| 模板短信API | 删除模板 | `delete_template` | `delete_template` | `SmsDeleteTemplateResponse` | [待核实] |
| 模板短信API | 查询模板 | `query_template` | `query_template` | `SmsQueryTemplateResponse` | [待核实] |
| 账号API | 查询余量 | `query_balance` | `query_balance` | `SmsBalanceResponse` | [待核实] |
| 账号API | 查询计费量 | `query_billing` | `query_billing` | `SmsBillingResponse` | [待核实] |
| 其他API | H5跳转小程序短链生成 | `generate_h5_miniprogram_short_link` | `generate_h5_miniprogram_short_link` | `SmsH5ShortLinkResponse` | [待核实] |
| 其他API | 更新H5跳小程序的AccessToken | `update_h5_miniprogram_access_token` | `update_h5_miniprogram_access_token` | `SmsUpdateAccessTokenResponse` | [待核实] |

回调类接口（状态报告推送、上行推送、模板审核结果推送）为服务端 Webhook，非客户端调用接口，此处不提供客户端方法。

##### 签名生成算法

1. 密码 MD5 加密：`MD5(password + smms_encrypt_key)`，结果转大写
2. 参数拼接（按顺序）：`AccountId={account_id}&PhoneNos={first_phone}&Password={md5_password}&Random={random}&Timestamp={timestamp}`（`PhoneNos` 只取第一个手机号）
3. SHA256 加密：对拼接后的字符串做 SHA256 哈希，作为 `AccessKey`

```python
from py_lmobile_toolkit.sms.auth import timestamp, random_digits, sha256_signature

ts = timestamp()
digits = random_digits()
signature = sha256_signature(
    account_id="your_account_id",
    password="your_password",
    phone_nos="13800138000",
    random_digits=digits,
    timestamp=ts,
    smms_encrypt_key="SMmsEncryptKey",
)
```

##### 环境变量配置

示例与测试通过 `.env` 读取以下变量：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `SMS_BASE_URL` | API 基础地址 | `https://api.51welink.com/` |
| `SMS_ACCOUNT_ID` | 账号 ID（必填） | — |
| `SMS_PASSWORD` | 账号密码（必填） | — |
| `SMS_PRODUCT_ID` | 产品 ID | `""` |
| `SMS_SMMS_ENCRYPT_KEY` | 加密密钥（MD5 盐值） | `SMmsEncryptKey` |

#### 参与贡献

1. Fork 本仓库
2. 新建 `Feat_xxx` 分支
3. 提交代码
4. 新增 Pull Request

#### 特技

- 同步客户端 `SmsClient` 与异步客户端 `AsyncSmsClient`，方法名完全一致
- 异步客户端支持 `async with` 上下文管理器
- 请求签名认证（MD5 密码 + SHA256 签名，AccessKey）
- 响应数据模型验证（Pydantic v2），所有模型开启 `extra="allow"`，兼容 API 扩展字段
- 覆盖官方文档导航中的全部客户端可调用接口（短信/模板短信/账号/其他 API）
- 接口端点以常量集中管理，便于按官方文档精确对齐
- 所有方法支持透传 `**kwargs` 给 httpx，方便覆盖 URL、请求头等
- 基于 Python 3.10+，依赖 `httpx>=0.24.0` 与 `pydantic>=2.0`

#### 相关链接

- [PyPI 项目页面](https://pypi.org/project/py-lmobile-toolkit/)
- [Gitee 代码仓库](https://gitee.com/guolei19850528/py_lmobile_toolkit)
- [乐信官方 API 文档](https://www.lmobile.cn/ApiPages/index.html)
- [英文文档](README.en.md)
