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

软件架构

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：

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

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

异步调用：

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())

已实现的接口

回调类接口（状态报告推送、上行推送、模板审核结果推送）为服务端 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

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 读取以下变量：

参与贡献

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 项目页面
• Gitee 代码仓库
• 乐信官方 API 文档
• 英文文档