luosimao-sms 0.1.0

A Python SDK for Luosimao SMS API

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

错误码对照表

枚举常量	错误码	错误描述	解决方案
ErrorCode.OK	0	成功	-
ErrorCode.AUTH_FAILED	-10	验证信息失败	检查 API KEY 是否正确传入
ErrorCode.API_DISABLED	-11	用户接口被禁用	请联系客服解除
ErrorCode.BALANCE_FROZEN	-12	余额冻结	在后台进行解冻操作
ErrorCode.INSUFFICIENT_BALANCE	-20	短信余额不足	进入个人中心购买充值
ErrorCode.EMPTY_MESSAGE	-30	短信内容为空	检查传入参数 message
ErrorCode.SENSITIVE_WORD	-31	短信内容存在敏感词	修改短信内容，更换敏感词
ErrorCode.MISSING_SIGNATURE	-32	短信内容缺少签名信息	在短信末尾增加签名信息 eg.【公司名称】
ErrorCode.MESSAGE_TOO_LONG	-33	短信过长，超过300字	调整短信内容或拆分为多条进行发送
ErrorCode.INVALID_SIGNATURE	-34	签名不可用	在后台签名管理下添加签名
ErrorCode.TEST_SIGNATURE_LIMITED	-35	测试签名受限	在短信后台添加签名并替换
ErrorCode.INVALID_MOBILE	-40	错误的手机号	检查手机号是否正确
ErrorCode.MOBILE_BLACKLISTED	-41	号码在黑名单中	联系客服确认
ErrorCode.FREQUENCY_LIMIT	-42	验证码发送频率过快	前台增加60秒获取限制
ErrorCode.IP_NOT_WHITELISTED	-50	请求发送IP不在白名单内	查看触发短信IP白名单设置

单元测试

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

python -m unittest discover tests

License

MIT License