Metadata-Version: 2.4
Name: snowland-py253
Version: 0.1
Summary: Python3 SDK for 253.com (SMS)
Author-email: "A.Star" <astar@snowland.ltd>
Maintainer-email: "A.Star" <astar@snowland.ltd>
License: Apache v2.0 License
Project-URL: Homepage, https://gitee.com/snowlandltd/snowland-253-python
Keywords: sms,253,snowland
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: Implementation
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: astartool
Requires-Dist: snowland-smx
Requires-Dist: configparser
Requires-Dist: snowland-http
Dynamic: license-file

# snowland-253-python

# py253

[![version](https://img.shields.io/pypi/v/snowland-py253.svg)](https://pypi.python.org/pypi/snowland-py253)
[![gitee](https://gitee.com/snowlandltd/snowland-253-python/badge/star.svg)](https://gitee.com/snowlandltd/snowland-253-python/stargazers)
[![download](https://img.shields.io/pypi/dm/snowland-py253.svg)](https://pypi.org/project/snowland-py253)
[![wheel](https://img.shields.io/pypi/wheel/snowland-py253.svg)](https://pypi.python.org/pypi/snowland-py253)
![status](https://img.shields.io/pypi/status/snowland-py253.svg)

#### 介绍
创蓝253接口SDK

### 使用方法

本 SDK 基于 `snowland-http` 封装，支持**同步**与**异步**两种调用方式。

#### 同步调用（默认 `requests` 后端）

```python
import configparser
from snowland_py253.account_manage import AccountManage
from snowland_py253.internal_message import InternalMessage
cp = configparser.ConfigParser()
cp.read('../config.conf')
account = cp.get('sms', 'account')
password = cp.get('sms', 'password')
acc = InternalMessage(account=account, password=password)


# sms = acc.send_sms("【雪域网络】测试接口", "15343126139")
# print(sms)
pull = acc.pull_mo()
print(pull)
pull = acc.pull_report()
print(pull)

balance = acc.get_user_balance()
print(balance)

acc = AccountManage(account=account, password=password)
balance = acc.add_sub_account()
print(balance)

# 子账号激活 / 查询 / 调拨 / 状态等
acc.active_sub_account(sub_account="sub", sms_type=49, status=1)
acc.get_sub_account(sub_account="sub")
acc.allot_sub_account(sub_account="sub", sms_type=49, count=100)
acc.get_sub_account_ids()
acc.get_sub_account_status(sub_account="sub")

# 资质 / 签名 / 模板管理（Base: https://api.chuanglan.com/api）
from snowland_py253.internal_message import QualificationManager
mgr = QualificationManager(account=account, password=password, api_name="YOUR_API_NAME")
mgr.add_qualification(company_name="雪域网络", qualification_type=1, license_url="https://x/y.jpg")
mgr.add_signature(sign_name="雪域网络", sign_type=1)
mgr.add_template(content="您的验证码为{s}", content_name="验证码",
                 signature_name="雪域网络", business_category="01",
                 business_subcategory="02")

```

#### 异步调用（需指定异步后端，如 `httpx` / `aiohttp`）

```python
import asyncio
import configparser
from snowland_py253.internal_message import InternalMessage

cp = configparser.ConfigParser()
cp.read('../config.conf')
account = cp.get('sms', 'account')
password = cp.get('sms', 'password')


async def main():
    # backend 指定为异步后端后即可使用 *_async 方法
    acc = InternalMessage(account=account, password=password, backend="httpx")
    async with acc:
        balance = await acc.get_user_balance_async()
        print(balance)
        report = await acc.pull_report_async()
        print(report)


asyncio.run(main())
```

> 构造参数说明：
> - `account` / `password`：253 平台账号与密码。
> - `uri`：接口基础地址（默认各业务已内置）。
> - `backend`：HTTP 后端，默认为 `"auto"`（按 `httpx` → `aiohttp` → `requests` → `stdlib` 自动选择可用后端）。也可显式指定：`"requests"`（仅同步）、`"httpx"`（同步+异步）、`"aiohttp"`（仅异步）、`"stdlib"`（零依赖，仅同步）。
> - `rate_limit`：可选 `snowland_http.RateLimitConfig`，用于全局限流。
> - `max_workers` / `max_concurrency`：同步线程池 / 异步并发信号量上限。
>
> 说明：异步方法（`*_async`）要求 `backend` 为异步后端（如 `httpx` / `aiohttp`），使用前请先安装对应依赖（`pip install httpx` 或 `pip install aiohttp`）。仅安装 `snowland-http` 时，默认回退到零依赖的 `stdlib` 后端，可正常进行同步调用。

### 单元测试

本项目的单元测试基于 Python 标准库 `unittest` 编写（不使用 pytest 等第三方框架），
测试文件位于 `tests/` 目录，通过 `unittest` 的 mock 机制隔离真实网络请求。

```bash
# 运行全部测试
python -m unittest discover -s tests

# 运行单个测试模块
python -m unittest tests.test_qualification
python -m unittest tests.test_internal_message
python -m unittest tests.test_unified_message

# 查看详细日志
python -m unittest tests.test_qualification -v
```

> 测试约定：
> - 每个同步方法均配套 `*_async` 异步方法，测试同时覆盖同步与异步（异步后端用 `FakeAsyncBackend` 模拟）。
> - 公共参数（`username` / `timestamp` / `signature` / `api_name`）及响应结构通过 `tests/helpers.py` 的 `make_http_response` / `run` / `FakeAsyncBackend` 辅助。
> - 新增 / 修改接口方法时，请同步更新对应 `tests/test_*.py`，并保证 `python -m unittest discover -s tests` 全绿。
