Metadata-Version: 2.4
Name: luosimao-sms
Version: 0.1.0
Summary: A Python SDK for Luosimao SMS API
Home-page: https://github.com/luosimao-oss/sms-python
Author: Jichen
Author-email: jichen@luosimao.com
License: MIT
Keywords: sms,luosimao,短信,验证码,触发短信,batch-sms
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Communications :: Telephony
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.20.0
Requires-Dist: urllib3>=1.26.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: responses>=0.13.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Luosimao SMS Python SDK

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/)

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

## 功能特性

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

## 安装

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

```bash
pip install luosimao-sms
```

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

## 快速开始

### 初始化客户端

```python
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. 发送单条短信

```python
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. 批量发送短信

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

```python
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. 查询账户余额

```python
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 的所有常见错误码。你可以根据这些错误码进行针对性的异常处理：

```python
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白名单设置 |

## 单元测试

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

```bash
python -m unittest discover tests
```

## License

MIT License
