haozhuma 0.1.2

Python SDK for Haozhuma SMS receiving platform

haozhuma

haozhuma 是一个面向注册机、批量任务和验证码自动化流程的 豪猪接码 Python SDK。

项目地址：https://github.com/laozig/haozhuma

问题反馈：https://github.com/laozig/haozhuma/issues

特性

• 纯代码 SDK，适合直接嵌入注册机工程。
• login() 默认自动复用 TokenCache。
• HaozhuClient.next_code() 一行完成取号和取码。
• 支持 with 上下文，自动关闭 HTTP 会话。
• 提供 SMSProvider 协议，方便以后接入其他接码平台。

安装

从 PyPI 安装

pip install haozhuma

从源码安装

git clone https://github.com/laozig/haozhuma.git
cd haozhuma
python -m pip install -e .

最短用法

from haozhuma import login

with login("your_user", "your_password", sid="92162") as sms:
    phone, code = sms.next_code()
    print(phone, code)

这段代码内部会完成：

• 登录豪猪平台。
• 复用或写入 token 缓存。
• 获取手机号。
• 轮询验证码。
• 成功后自动释放号码。

常见用法

1. 状态机写法

from haozhuma import login

sms = login("your_user", "your_password", sid="92162")

phone = sms.get_phone()
code = sms.poll_code()

print(phone, code)
print(sms.phone, sms.code)

sms.release()

2. 批量任务写法

from haozhuma import login

sms = login("your_user", "your_password", sid="92162")

for index in range(100):
    try:
        phone, code = sms.next_code()
        print(index, phone, code)
    except TimeoutError:
        print(index, "timeout")

3. 手动控制缓存

from haozhuma import TokenCache, login

cache = TokenCache("./token_cache.json")
sms = login("your_user", "your_password", sid="92162", token_cache=cache)

4. 已有 token 时直接恢复

from haozhuma import from_token

sms = from_token("your_token", sid="92162")
phone = sms.get_phone()
code = sms.poll_code()

5. 获取完整响应对象

from haozhuma import login

sms = login("your_user", "your_password", sid="92162")

phone_info = sms.get_phone_info()
message = sms.poll_message()

print(phone_info.raw)
print(message.raw)

核心 API

API	返回值	说明
login()	HaozhuClient	登录并返回可复用对象，默认自动复用 TokenCache
from_token()	HaozhuClient	用已有 token 恢复对象
get_phone()	str	获取号码并保存状态
get_phone_info()	PhoneResult	获取号码完整响应
poll_code()	str	轮询验证码并保存状态
poll_message()	MessageResult	轮询短信完整响应
next_code()	(phone, code)	一行完成取号和取码
release()	dict	释放当前号码
blacklist()	dict	拉黑当前号码
TokenCache	class	管理登录态缓存
SMSProvider	Protocol	接码平台统一抽象

默认行为

参数	默认值	作用
use_cache	True	登录时优先读 TokenCache
auto_release	True	next_code() 成功后自动释放号码
auto_blacklist	True	next_code() 超时后自动拉黑号码

项目结构

文件	说明
src/haozhuma/client.py	核心客户端
src/haozhuma/token_cache.py	token 缓存
src/haozhuma/provider.py	接码平台抽象协议
src/haozhuma/models.py	响应模型
src/haozhuma/exceptions.py	异常定义
src/haozhuma/__init__.py	对外导出
pyproject.toml	打包配置
LICENSE	开源许可证

开发与发布

本地构建：

python -m build
python -m twine check dist/*

发布到 PyPI：

python -m twine upload dist/*

License

本项目使用 MIT License，见 LICENSE。

免责声明

本模块仅用于已授权项目的验证码接收、测试环境验证和自动化流程开发。使用者需自行确认账号、项目和接口调用均符合平台规则与当地法律。