Metadata-Version: 2.4
Name: haozhuma
Version: 0.1.1
Summary: Python SDK for Haozhuma SMS receiving platform
Author: laozig
License-Expression: MIT
Project-URL: Homepage, https://github.com/laozig/haozhuma
Project-URL: Repository, https://github.com/laozig/haozhuma
Project-URL: Documentation, https://github.com/laozig/haozhuma#readme
Project-URL: Issues, https://github.com/laozig/haozhuma/issues
Keywords: haozhuma,sms,otp,verification-code
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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
License-File: LICENSE
Requires-Dist: curl_cffi>=0.7.0
Dynamic: license-file

# haozhuma

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

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

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

## 特性

- 纯代码 SDK，适合直接嵌入注册机工程。
- [`login()`](src/haozhuma/client.py:385) 默认自动复用 [`TokenCache`](src/haozhuma/token_cache.py:14)。
- [`HaozhuClient.next_code()`](src/haozhuma/client.py:336) 一行完成取号和取码。
- 支持 `with` 上下文，自动关闭 HTTP 会话。
- 提供 [`SMSProvider`](src/haozhuma/provider.py:9) 协议，方便以后接入其他接码平台。

## 安装

### 从 PyPI 安装

```bash
pip install haozhuma
```

### 从源码安装

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

## 最短用法

```python
from haozhuma import login

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

这段代码内部会完成：

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

## 常见用法

### 1. 状态机写法

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

### 2. 批量任务写法

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

### 3. 手动控制缓存

```python
from haozhuma import TokenCache, login

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

### 4. 已有 token 时直接恢复

```python
from haozhuma import from_token

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

### 5. 获取完整响应对象

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

## 核心 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` | 开源许可证 |

## 开发与发布

本地构建：

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

发布到 PyPI：

```bash
python -m twine upload dist/*
```

## License

本项目使用 MIT License，见 [`LICENSE`](LICENSE)。

## 免责声明

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