haozhuma 0.1.0

Haozhuma SMS receiving platform Python client

haozhuma

haozhuma 是豪猪接码平台的 Python 代码 SDK，面向注册机、批量任务和接码流程封装。

当前版本已经移除了 CLI，只保留代码调用入口。

快速启动

cd haozhuma
python -m pip install -e .

环境依赖

依赖	最低版本	用途
Python	3.9	运行 SDK
curl_cffi	0.7.0	HTTP 客户端

最短用法

from haozhuma import login

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

这段代码内部完成：

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

状态机用法

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()

next_code() 用法

next_code() 适合注册机主循环。

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

默认行为：

参数	默认值	作用
auto_release	True	取码成功后自动释放号码
auto_blacklist	True	超时后自动拉黑号码

TokenCache 用法

login() 默认自动读写 TokenCache。

• 命中缓存：直接复用 token
• 未命中缓存：重新登录并写回缓存

from haozhuma import TokenCache, login

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

如果你不想用缓存：

from haozhuma import login

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

已有 token 的用法

from haozhuma import from_token

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

保留完整响应对象

如果你不只要字符串，也可以拿完整结构。

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)

SMSProvider 抽象

SMSProvider 是统一协议，方便以后接别的接码平台。

from haozhuma import SMSProvider, login

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

API 对照

SDK 方法	返回值	说明
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	接码平台统一抽象

当前目录说明

文件	是否保留	说明
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	保留	pip install 打包入口
README.md	保留	用法文档

免责声明

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