py-lmobile-toolkit

乐信（51welink）短信服务 Python SDK，提供同步与异步客户端，支持 MD5 + SHA256 签名认证，响应模型基于 Pydantic v2。

English | 中文

项目简介

py-lmobile-toolkit 是乐信（51welink）短信开放平台的非官方 Python 客户端库，封装了官方 HTTP API，提供同步客户端 SmsClient 和异步客户端 AsyncSmsClient，两者方法名完全一致，异步客户端支持 async with 上下文管理器。

• 项目主页：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

功能特性

• ✅ 同步客户端 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

注意：账号、密码、产品 ID 等敏感信息请通过环境变量（.env 文件）配置，勿硬编码在代码中。

安装

推荐：使用 uv 安装

uv add py-lmobile-toolkit

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

uv pip install -e .

安装测试依赖：

uv pip install -e ".[dev]"

或者使用 pip 安装

pip install py-lmobile-toolkit

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

pip install -e .

安装测试依赖：

pip install -e ".[dev]"

快速开始

同步调用

from py_lmobile_toolkit.sms.client import SmsClient

# 创建同步客户端
sms = SmsClient(
    account_id="your_account_id",
    password="your_password",
    product_id="your_product_id",
)

# 发送单条短信
response = sms.send_sms(
    phone_nos="13800138000",
    content="【乐信】您的验证码是：123456，请于 5 分钟内正确输入",
)
print(f"成功: {response.ok}, 结果码: {response.Result}")

sms.close()

也可使用上下文管理器自动关闭客户端：

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(response.ok, response.Result)

异步调用

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", "13900139000"],
            content="【乐信】批量发送测试",
        )
        print(f"成功: {response.ok}, 结果码: {response.Result}")


asyncio.run(main())

已实现的接口

回调类接口（状态报告推送、上行推送、模板审核结果推送）为服务端 Webhook，非客户端调用接口，此处不提供客户端方法。如需接收推送，请在业务服务器上实现对应 HTTP 接口并解析请求体。

端点说明

• 提交短信 端点 /EncryptionSubmit/SendSms.ashx 为已知可靠（与历史版本一致）。
• 其余接口端点基于官方文档接口名称推断，均标注 [待核实]，定义在 src/py_lmobile_toolkit/sms/client.py 的顶部常量中，请以 https://www.lmobile.cn/ApiPages/index.html 实际文档的请求地址与参数为准进行调整。
• 每个方法均接受 url 关键字参数可覆盖默认端点，亦可通过 **kwargs 透传 httpx 参数。

响应模型

所有响应均继承 SmsBaseResponse，包含 Result 字段，Result 为 "succ" 表示成功，可通过 ok 属性判断：

from py_lmobile_toolkit.sms.models import SmsSendSmsResponse

response: SmsSendSmsResponse = sms.send_sms(...)
if response.ok:
    print("发送成功")
else:
    print(f"发送失败，结果码: {response.Result}")

所有模型均开启 extra="allow"，兼容 API 返回的扩展字段。

签名生成算法

签名生成遵循以下步骤：

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

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",
)

示例代码 (examples/)

完整可运行示例位于 examples/sms/，文件命名规则为 example_*.py（同步）与 example_async_*.py（异步）。

运行示例前，请复制模板并填写真实账号：

cp examples/sms/.env.example examples/sms/.env

测试 (tests/)

测试用例位于 tests/sms/，基于 pytest + pytest-asyncio，统一从 tests/sms/.env 读取配置，公共夹具定义在 tests/sms/conftest.py。

运行测试前，请复制模板并填写真实账号：

cp tests/sms/.env.example tests/sms/.env

安装测试依赖并运行：

uv pip install -e ".[dev]"
pytest tests/sms -q

未配置 SMS_ACCOUNT_ID / SMS_PASSWORD 时，测试会自动跳过。

目录结构

py_lmobile_toolkit/
├── README.md                 # 中文文档（本文件）
├── README.en.md              # 英文文档
├── pyproject.toml            # 项目元数据与依赖
├── LICENSE                   # MIT 许可证
├── .gitignore                # Git 忽略规则
├── src/
│   └── py_lmobile_toolkit/
│       ├── __init__.py       # 顶层包
│       ├── py.typed          # PEP 561 类型标记
│       └── sms/              # 短信子包
│           ├── __init__.py
│           ├── auth.py       # 签名生成工具（md5/sha256/timestamp/random_digits）
│           ├── client.py     # SmsClient（同步）与 AsyncSmsClient（异步）
│           └── models.py     # pydantic 响应模型
├── tests/
│   └── sms/
│       ├── __init__.py
│       ├── conftest.py       # 公共夹具（客户端、查询条件）
│       ├── .env.example      # 测试配置模板
│       └── test_*.py         # 各接口的同步 / 异步测试用例
└── examples/
    └── sms/
        ├── .env.example      # 示例配置模板
        ├── example_common.py # 示例公共辅助（读取配置、构造客户端）
        ├── example_*.py      # 各接口同步示例
        └── example_async_*.py # 各接口异步示例

环境变量配置

示例与测试均通过 .env 文件读取以下环境变量：

贡献指南

欢迎提交 Issue 和 Pull Request。在提交代码前，请：

1. Fork 本仓库并创建特性分支
2. 编写或更新对应的测试用例
3. 确保 pytest 全部通过
4. 提交 Pull Request，描述变更内容与动机

许可证

本项目基于 MIT License 开源。

相关链接

• PyPI 项目页面
• Gitee 代码仓库
• 乐信官方 API 文档
• 英文文档