Metadata-Version: 2.4
Name: haozhuma
Version: 0.1.0
Summary: Haozhuma SMS receiving platform Python client
Author: laozig
License: MIT
Project-URL: Homepage, https://api.haozhuma.com
Project-URL: Documentation, https://api.haozhuma.com
Keywords: haozhuma,sms,otp,verification-code
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: curl_cffi>=0.7.0

# haozhuma

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

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

## 快速启动

```bash
cd haozhuma
python -m pip install -e .
```

## 环境依赖

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

## 最短用法

```python
from haozhuma import login

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

这段代码内部完成：

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

## 状态机用法

```python
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()` 适合注册机主循环。

```python
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`](src/haozhuma/token_cache.py:14)。

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

```python
from haozhuma import TokenCache, login

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

如果你不想用缓存：

```python
from haozhuma import login

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

## 已有 `token` 的用法

```python
from haozhuma import from_token

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

## 保留完整响应对象

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

```python
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`](src/haozhuma/provider.py:9) 是统一协议，方便以后接别的接码平台。

```python
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` | 保留 | 用法文档 |

## 免责声明

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