Luosimao SMS Python SDK

Luosimao SMS Python SDK 是一个用于与 Luosimao 短信 API 进行交互的 Python 客户端库。它旨在简化短信发送（单条/批量）和余额查询操作，并内置了针对网络抖动的自动重试机制以及对 Luosimao 错误码的统一封装。

功能特性

• 单条短信发送: 快速发送验证码、触发类等单条短信。
• 批量短信发送: 支持定时发送、向多个号码批量发送通知、提醒类短信。
• 余额与状态查询: 轻松获取当前账户的短信余额信息。
• 自动重试机制: 内置基于 urllib3 的请求重试策略，在遇到网络波动（如 ConnectionError）或服务端限流/错误（HTTP 429, 500, 502, 503, 504）时会自动重试。
• 签名自动封装: 传入 API Key 时自动处理 key- 前缀拼接细节，开发者无需关心。
• 统一的错误码枚举: 详细的 ErrorCode 枚举和 LuosimaoException 异常类，便于异常捕获与处理。

安装

你可以通过 pip 安装此 SDK（待发布到 PyPI 后）：

pip install luosimao-sms

(如果你是通过源码安装，可以在项目根目录运行 pip install .)

快速开始

初始化客户端

from luosimao import LuosimaoClient, LuosimaoException, ErrorCode

# 初始化客户端，填入你的 API KEY
# API KEY 包含或不包含 'key-' 前缀均可，SDK 会自动处理
api_key = "你的_API_KEY"

# 推荐使用 context manager，它会自动关闭底层的 requests.Session
with LuosimaoClient(api_key=api_key) as client:
    # 你的业务代码...
    pass

1. 发送单条短信

from luosimao import LuosimaoClient, LuosimaoException

with LuosimaoClient(api_key="你的_API_KEY") as client:
    try:
        # 短信内容末尾务必增加签名信息，例如：【公司名称】
        response = client.send_sms(
            mobile="13761428268", 
            message="验证码：321123【铁壳测试】"
        )
        print("发送成功:", response)
    except LuosimaoException as e:
        print(f"发送失败，错误码: {e.code}, 错误信息: {e.message}")
        if e.hit:
            print(f"触发敏感词: {e.hit}")

2. 批量发送短信

批量接口专门用于大量号码的内容群发，不建议发送验证码等有时效性要求的内容。

from luosimao import LuosimaoClient

with LuosimaoClient(api_key="你的_API_KEY") as client:
    mobiles = ["13761428268", "18521513391"]
    
    # 也可以指定发送时间：time="2026-04-01 12:30:00"
    response = client.send_batch_sms(
        mobile_list=mobiles, 
        message="提醒：您的账号即将到期，请及时充值【铁壳测试】"
    )
    print("批量发送成功:", response)

3. 查询账户余额

from luosimao import LuosimaoClient

with LuosimaoClient(api_key="你的_API_KEY") as client:
    status = client.get_status()
    print(f"当前余额: {status.get('deposit')}")

异常处理与错误码

SDK 提供了一个 ErrorCode 枚举类，包含 Luosimao API 的所有常见错误码。你可以根据这些错误码进行针对性的异常处理：

from luosimao import LuosimaoClient, LuosimaoException, ErrorCode

try:
    client = LuosimaoClient(api_key="你的_API_KEY")
    client.send_sms(mobile="13712345678", message="不合规内容【公司名称】")
except LuosimaoException as e:
    if e.code == ErrorCode.INSUFFICIENT_BALANCE:
        print("短信余额不足，请充值！")
    elif e.code == ErrorCode.SENSITIVE_WORD:
        print(f"短信内容包含敏感词: {e.hit}")
    elif e.code == ErrorCode.MISSING_SIGNATURE:
        print("短信内容缺少签名信息，请在末尾添加【公司名称】")
    else:
        print(f"其他 API 错误: {e}")

错误码对照表

单元测试

如果你需要运行该项目的单元测试以进行二次开发，可以使用以下命令：

python -m unittest discover tests

License

MIT License