haozhuma 0.1.0__py3-none-any.whl

haozhuma/__init__.py

@@ -0,0 +1,22 @@
+from .client import HaozhuClient, from_token, login
+from .exceptions import HaozhuAPIError, HaozhuError, HaozhuResponseError, HaozhuTimeoutError
+from .models import AccountSummary, MessageResult, PhoneResult
+from .provider import SMSProvider
+from .token_cache import TokenCache
+
+__all__ = [
+    "AccountSummary",
+    "HaozhuAPIError",
+    "HaozhuClient",
+    "HaozhuError",
+    "HaozhuResponseError",
+    "HaozhuTimeoutError",
+    "MessageResult",
+    "PhoneResult",
+    "SMSProvider",
+    "TokenCache",
+    "from_token",
+    "login",
+]
+
+__version__ = "0.1.0"

haozhuma/client.py

@@ -0,0 +1,463 @@
+from __future__ import annotations
+
+import os
+import re
+import time
+from typing import Any, Callable, Mapping
+
+from curl_cffi import requests
+
+from .exceptions import HaozhuAPIError, HaozhuResponseError, HaozhuTimeoutError
+from .models import AccountSummary, MessageResult, PhoneResult
+from .token_cache import TokenCache
+
+SUCCESS_CODES = {"0", "200"}
+DEFAULT_SERVER = "api.haozhuma.com"
+DEFAULT_AUTHOR = "adminzfz"
+DEFAULT_POLL_INTERVAL = 15
+DEFAULT_WAIT_TIMEOUT = 180
+CODE_PATTERN = re.compile(r"(?<!\d)(\d{4,8})(?!\d)")
+
+
+class HaozhuClient:
+    def __init__(
+        self,
+        server: str = DEFAULT_SERVER,
+        username: str = "",
+        password: str = "",
+        token: str = "",
+        project_id: str = "",
+        author: str = DEFAULT_AUTHOR,
+        timeout: int = 10,
+        poll_interval: int = DEFAULT_POLL_INTERVAL,
+        wait_timeout: int = DEFAULT_WAIT_TIMEOUT,
+        impersonate: str = "chrome120",
+        session: Any | None = None,
+    ):
+        self.base_url = self.normalize_server(server)
+        self.username = str(username or "").strip()
+        self.password = str(password or "").strip()
+        self.project_id = str(project_id or "").strip()
+        self.author = str(author or DEFAULT_AUTHOR).strip()
+        self.timeout = int(timeout)
+        self.poll_interval = int(poll_interval)
+        self.wait_timeout = int(wait_timeout)
+        self.impersonate = str(impersonate or "").strip() or None
+        self.session = session or requests.Session()
+        self._token = str(token or "").strip()
+        self.last_phone: PhoneResult | None = None
+        self.last_message: MessageResult | None = None
+
+    @classmethod
+    def from_env(cls, prefix: str = "HAOZHUMA_") -> "HaozhuClient":
+        def env(name: str, default: str = "") -> str:
+            return os.getenv(f"{prefix}{name}", default)
+
+        return cls(
+            server=env("SERVER", DEFAULT_SERVER),
+            username=env("USER"),
+            password=env("PASSWORD"),
+            token=env("TOKEN"),
+            project_id=env("SID"),
+            author=env("AUTHOR", DEFAULT_AUTHOR),
+            poll_interval=int(env("POLL_INTERVAL", str(DEFAULT_POLL_INTERVAL))),
+            wait_timeout=int(env("WAIT_TIMEOUT", str(DEFAULT_WAIT_TIMEOUT))),
+            impersonate=env("IMPERSONATE", "chrome120"),
+        )
+
+    @staticmethod
+    def normalize_server(server: str) -> str:
+        value = str(server or DEFAULT_SERVER).strip().rstrip("/")
+        if value.startswith(("http://", "https://")):
+            return value
+        return f"https://{value}"
+
+    @property
+    def token(self) -> str:
+        return self._token
+
+    @property
+    def phone(self) -> str:
+        if not self.last_phone:
+            return ""
+        return self.last_phone.phone
+
+    @property
+    def phone_info(self) -> PhoneResult | None:
+        return self.last_phone
+
+    @property
+    def message(self) -> MessageResult | None:
+        return self.last_message
+
+    @property
+    def code(self) -> str:
+        if not self.last_message:
+            return ""
+        return self.last_message.sms_code
+
+    def _sid(self, sid: str = "") -> str:
+        value = str(sid or self.project_id or "").strip()
+        if not value:
+            raise ValueError("豪猪项目ID为空，请传入 sid 或初始化 project_id")
+        return value
+
+    def _phone(self, phone: str = "") -> str:
+        value = str(phone or self.phone or "").strip()
+        if not value:
+            raise ValueError("当前没有手机号，请先调用 get_phone()，或显式传入 phone")
+        return value
+
+    def _request_kwargs(self, params: Mapping[str, Any]) -> dict[str, Any]:
+        kwargs: dict[str, Any] = {
+            "params": dict(params),
+            "timeout": self.timeout,
+        }
+        if self.impersonate:
+            kwargs["impersonate"] = self.impersonate
+        return kwargs
+
+    def request(self, api: str, allow_wait: bool = False, **params: Any) -> dict[str, Any]:
+        query: dict[str, Any] = {"api": api}
+        for key, value in params.items():
+            if value in (None, ""):
+                continue
+            query[key] = value
+
+        response = self.session.get(f"{self.base_url}/sms/", **self._request_kwargs(query))
+        response.raise_for_status()
+        response.encoding = "utf-8"
+
+        try:
+            data = response.json()
+        except Exception as exc:
+            raise HaozhuResponseError(f"豪猪接口返回非 JSON: api={api}, text={response.text[:300]}") from exc
+
+        if not isinstance(data, dict):
+            raise HaozhuResponseError(f"豪猪接口返回结构异常: api={api}, payload={data!r}")
+
+        code = str(data.get("code", "")).strip()
+        msg = str(data.get("msg") or "")
+        if code in SUCCESS_CODES:
+            return data
+        if allow_wait and code == "-1" and "等待" in msg:
+            return data
+        raise HaozhuAPIError(api, data)
+
+    def login(self, username: str = "", password: str = "", force: bool = False) -> str:
+        if self._token and not force:
+            return self._token
+
+        user = str(username or self.username or "").strip()
+        passwd = str(password or self.password or "").strip()
+        if not user or not passwd:
+            raise ValueError("豪猪 API 用户名或密码为空")
+
+        data = self.request("login", **{"user": user, "pass": passwd})
+        token = str(data.get("token") or "").strip()
+        if not token:
+            raise HaozhuResponseError(f"豪猪登录未返回 token: {data}")
+        self._token = token
+        return token
+
+    def ensure_token(self) -> str:
+        if self._token:
+            return self._token
+        return self.login()
+
+    def get_summary(self) -> AccountSummary:
+        data = self.request("getSummary", token=self.ensure_token())
+        return AccountSummary.from_payload(data)
+
+    def get_phone_raw(
+        self,
+        sid: str = "",
+        phone: str = "",
+        isp: str | int = "",
+        province: str | int = "",
+        ascription: str | int = "",
+        paragraph: str = "",
+        exclude: str = "",
+        uid: str = "",
+        author: str = "",
+    ) -> dict[str, Any]:
+        return self.request(
+            "getPhone",
+            token=self.ensure_token(),
+            sid=self._sid(sid),
+            phone=str(phone or ""),
+            isp=isp,
+            Province=province,
+            ascription=ascription,
+            paragraph=paragraph,
+            exclude=exclude,
+            uid=uid,
+            author=author or self.author,
+        )
+
+    def get_phone_info(self, sid: str = "", **filters: Any) -> PhoneResult:
+        self.last_phone = PhoneResult.from_payload(self.get_phone_raw(sid=sid, **filters))
+        return self.last_phone
+
+    def get_phone(self, sid: str = "", **filters: Any) -> str:
+        return self.get_phone_info(sid=sid, **filters).phone
+
+    def occupy_phone_info(self, phone: str, sid: str = "", author: str = "") -> PhoneResult:
+        self.last_phone = PhoneResult.from_payload(
+            self.get_phone_raw(
+                sid=sid,
+                phone=str(phone),
+                author=author or self.author,
+            )
+        )
+        return self.last_phone
+
+    def occupy_phone(self, phone: str, sid: str = "", author: str = "") -> str:
+        return self.occupy_phone_info(phone=phone, sid=sid, author=author).phone
+
+    def get_message_raw(self, phone: str = "", sid: str = "", allow_wait: bool = False) -> dict[str, Any]:
+        phone_value = self._phone(phone)
+        return self.request(
+            "getMessage",
+            allow_wait=allow_wait,
+            token=self.ensure_token(),
+            sid=self._sid(sid),
+            phone=phone_value,
+        )
+
+    def get_message(self, phone: str = "", sid: str = "", allow_wait: bool = False) -> MessageResult:
+        sid_value = self._sid(sid)
+        phone_value = self._phone(phone)
+        payload = self.get_message_raw(phone_value, sid=sid_value, allow_wait=allow_wait)
+        self.last_message = MessageResult.from_payload(
+            phone=phone_value,
+            sid=sid_value,
+            payload=payload,
+            sms_code=self.extract_code(payload),
+        )
+        return self.last_message
+
+    def release_phone(self, phone: str = "", sid: str = "") -> dict[str, Any]:
+        return self.request(
+            "cancelRecv",
+            token=self.ensure_token(),
+            sid=self._sid(sid),
+            phone=self._phone(phone),
+        )
+
+    def release_all(self) -> dict[str, Any]:
+        return self.request("cancelAllRecv", token=self.ensure_token())
+
+    def blacklist_phone(self, phone: str = "", sid: str = "") -> dict[str, Any]:
+        return self.request(
+            "addBlacklist",
+            token=self.ensure_token(),
+            sid=self._sid(sid),
+            phone=self._phone(phone),
+        )
+
+    def block_phone(self, phone: str = "", sid: str = "") -> dict[str, Any]:
+        return self.blacklist_phone(phone=phone, sid=sid)
+
+    @staticmethod
+    def extract_code(payload: Mapping[str, Any] | str, fallback_code: str = "") -> str:
+        if isinstance(payload, Mapping):
+            fallback_code = str(payload.get("yzm") or fallback_code or "")
+            sms_text = str(payload.get("sms") or "")
+        else:
+            sms_text = str(payload or "")
+
+        digits = CODE_PATTERN.findall(fallback_code)
+        if digits:
+            return digits[0]
+        matches = CODE_PATTERN.findall(sms_text)
+        if matches:
+            return matches[0]
+        return ""
+
+    def poll_message(
+        self,
+        phone: str = "",
+        sid: str = "",
+        timeout: int | None = None,
+        interval: int | None = None,
+        auto_blacklist: bool = False,
+        on_attempt: Callable[[int, MessageResult], None] | None = None,
+    ) -> MessageResult:
+        sid_value = self._sid(sid)
+        phone_value = self._phone(phone)
+        wait_timeout = int(timeout or self.wait_timeout)
+        poll_interval = int(interval or self.poll_interval)
+        deadline = time.monotonic() + wait_timeout
+        last_payload: dict[str, Any] | None = None
+        attempt = 0
+
+        while time.monotonic() <= deadline:
+            attempt += 1
+            last_payload = self.get_message_raw(phone_value, sid=sid_value, allow_wait=True)
+            message = MessageResult.from_payload(
+                phone=phone_value,
+                sid=sid_value,
+                payload=last_payload,
+                sms_code=self.extract_code(last_payload),
+            )
+            self.last_message = message
+            if on_attempt:
+                on_attempt(attempt, message)
+            if message.sms_code:
+                return message
+            sleep_for = min(poll_interval, max(0, deadline - time.monotonic()))
+            if sleep_for <= 0:
+                break
+            time.sleep(sleep_for)
+
+        if auto_blacklist:
+            self.blacklist_phone(phone_value, sid=sid_value)
+        raise HaozhuTimeoutError(phone=phone_value, sid=sid_value, last_payload=last_payload)
+
+    def poll_code(
+        self,
+        phone: str = "",
+        sid: str = "",
+        timeout: int | None = None,
+        interval: int | None = None,
+        auto_blacklist: bool = False,
+        on_attempt: Callable[[int, MessageResult], None] | None = None,
+    ) -> str:
+        return self.poll_message(
+            phone=phone,
+            sid=sid,
+            timeout=timeout,
+            interval=interval,
+            auto_blacklist=auto_blacklist,
+            on_attempt=on_attempt,
+        ).sms_code
+
+    def next_code(
+        self,
+        sid: str = "",
+        timeout: int | None = None,
+        interval: int | None = None,
+        auto_release: bool = True,
+        auto_blacklist: bool = True,
+        on_attempt: Callable[[int, MessageResult], None] | None = None,
+        **filters: Any,
+    ) -> tuple[str, str]:
+        phone = self.get_phone(sid=sid, **filters)
+        try:
+            code = self.poll_code(
+                phone=phone,
+                sid=sid,
+                timeout=timeout,
+                interval=interval,
+                auto_blacklist=False,
+                on_attempt=on_attempt,
+            )
+        except HaozhuTimeoutError:
+            if auto_blacklist:
+                self.blacklist(phone=phone, sid=sid)
+            raise
+        if auto_release:
+            self.release(phone=phone, sid=sid)
+        return phone, code
+
+    def release(self, phone: str = "", sid: str = "") -> dict[str, Any]:
+        return self.release_phone(phone=phone, sid=sid)
+
+    def blacklist(self, phone: str = "", sid: str = "") -> dict[str, Any]:
+        return self.blacklist_phone(phone=phone, sid=sid)
+
+    def block(self, phone: str = "", sid: str = "") -> dict[str, Any]:
+        return self.blacklist_phone(phone=phone, sid=sid)
+
+    def close(self) -> None:
+        close = getattr(self.session, "close", None)
+        if callable(close):
+            close()
+
+    def __enter__(self) -> "HaozhuClient":
+        return self
+
+    def __exit__(self, _exc_type: Any, _exc: Any, _tb: Any) -> None:
+        self.close()
+
+
+def login(
+    user: str,
+    password: str,
+    sid: str = "",
+    server: str = DEFAULT_SERVER,
+    author: str = DEFAULT_AUTHOR,
+    timeout: int = 10,
+    poll_interval: int = DEFAULT_POLL_INTERVAL,
+    wait_timeout: int = DEFAULT_WAIT_TIMEOUT,
+    impersonate: str = "chrome120",
+    session: Any | None = None,
+    use_cache: bool = True,
+    token_cache: TokenCache | None = None,
+    force: bool = False,
+) -> HaozhuClient:
+    """Create a token-bearing client for batch registration code.
+
+    By default this reads TokenCache first. If no token exists, it logs in once,
+    writes the token cache, and returns a reusable stateful client.
+    """
+    cache = token_cache or TokenCache()
+    if use_cache and not force:
+        cached_token = cache.get(server=server, user=user, sid=sid)
+        if cached_token:
+            return HaozhuClient(
+                server=server,
+                username=user,
+                password=password,
+                token=cached_token,
+                project_id=sid,
+                author=author,
+                timeout=timeout,
+                poll_interval=poll_interval,
+                wait_timeout=wait_timeout,
+                impersonate=impersonate,
+                session=session,
+            )
+
+    client = HaozhuClient(
+        server=server,
+        username=user,
+        password=password,
+        project_id=sid,
+        author=author,
+        timeout=timeout,
+        poll_interval=poll_interval,
+        wait_timeout=wait_timeout,
+        impersonate=impersonate,
+        session=session,
+    )
+    token = client.login(force=True)
+    if use_cache:
+        cache.set(server=server, user=user, sid=sid, token=token)
+    return client
+
+
+def from_token(
+    token: str,
+    sid: str = "",
+    server: str = DEFAULT_SERVER,
+    author: str = DEFAULT_AUTHOR,
+    timeout: int = 10,
+    poll_interval: int = DEFAULT_POLL_INTERVAL,
+    wait_timeout: int = DEFAULT_WAIT_TIMEOUT,
+    impersonate: str = "chrome120",
+    session: Any | None = None,
+) -> HaozhuClient:
+    """Create a client from an existing token without calling login."""
+    return HaozhuClient(
+        server=server,
+        token=token,
+        project_id=sid,
+        author=author,
+        timeout=timeout,
+        poll_interval=poll_interval,
+        wait_timeout=wait_timeout,
+        impersonate=impersonate,
+        session=session,
+    )

haozhuma/exceptions.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+
+class HaozhuError(Exception):
+    """Base exception for haozhuma client errors."""
+
+
+class HaozhuAPIError(HaozhuError):
+    """Raised when Haozhuma returns a non-success response."""
+
+    def __init__(self, api: str, payload: Mapping[str, Any]):
+        self.api = api
+        self.payload = dict(payload)
+        code = self.payload.get("code")
+        msg = self.payload.get("msg")
+        super().__init__(f"豪猪接口失败: api={api}, code={code}, msg={msg}, payload={self.payload}")
+
+
+class HaozhuResponseError(HaozhuError):
+    """Raised when the HTTP response is not valid JSON or has an invalid shape."""
+
+
+class HaozhuTimeoutError(HaozhuError, TimeoutError):
+    """Raised when polling SMS code times out."""
+
+    def __init__(self, phone: str, sid: str, last_payload: Mapping[str, Any] | None = None):
+        self.phone = str(phone)
+        self.sid = str(sid)
+        self.last_payload = dict(last_payload or {})
+        super().__init__(f"等待验证码超时: phone={self.phone}, sid={self.sid}, last={self.last_payload}")

haozhuma/models.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class AccountSummary:
+    money: str = ""
+    num: int = 0
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> "AccountSummary":
+        raw = dict(payload)
+        try:
+            num = int(raw.get("num") or 0)
+        except (TypeError, ValueError):
+            num = 0
+        return cls(
+            money=str(raw.get("money") or ""),
+            num=num,
+            raw=raw,
+        )
+
+
+@dataclass(frozen=True)
+class PhoneResult:
+    phone: str
+    sid: str = ""
+    shop_name: str = ""
+    country_name: str = ""
+    country_code: str = ""
+    country_qu: str = ""
+    uid: str = ""
+    sp: str = ""
+    phone_gsd: str = ""
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> "PhoneResult":
+        raw = dict(payload)
+        return cls(
+            phone=str(raw.get("phone") or ""),
+            sid=str(raw.get("sid") or ""),
+            shop_name=str(raw.get("shop_name") or ""),
+            country_name=str(raw.get("country_name") or ""),
+            country_code=str(raw.get("country_code") or ""),
+            country_qu=str(raw.get("country_qu") or ""),
+            uid=str(raw.get("uid") or ""),
+            sp=str(raw.get("sp") or ""),
+            phone_gsd=str(raw.get("phone_gsd") or ""),
+            raw=raw,
+        )
+
+
+@dataclass(frozen=True)
+class MessageResult:
+    phone: str
+    sid: str
+    sms: str = ""
+    sms_code: str = ""
+    api_code: str = ""
+    msg: str = ""
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def ok(self) -> bool:
+        return self.api_code in {"0", "200"} and bool(self.sms_code)
+
+    @classmethod
+    def from_payload(cls, phone: str, sid: str, payload: Mapping[str, Any], sms_code: str = "") -> "MessageResult":
+        raw = dict(payload)
+        return cls(
+            phone=str(phone),
+            sid=str(sid),
+            sms=str(raw.get("sms") or ""),
+            sms_code=str(sms_code or raw.get("yzm") or ""),
+            api_code=str(raw.get("code", "")),
+            msg=str(raw.get("msg") or ""),
+            raw=raw,
+        )

haozhuma/provider.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Protocol, runtime_checkable
+
+from .models import MessageResult, PhoneResult
+
+
+@runtime_checkable
+class SMSProvider(Protocol):
+    @property
+    def token(self) -> str: ...
+
+    @property
+    def phone(self) -> str: ...
+
+    @property
+    def code(self) -> str: ...
+
+    def get_phone(self, sid: str = "", **filters: Any) -> str: ...
+
+    def get_phone_info(self, sid: str = "", **filters: Any) -> PhoneResult: ...
+
+    def poll_code(
+        self,
+        phone: str = "",
+        sid: str = "",
+        timeout: int | None = None,
+        interval: int | None = None,
+        auto_blacklist: bool = False,
+        on_attempt: Callable[[int, MessageResult], None] | None = None,
+    ) -> str: ...
+
+    def poll_message(
+        self,
+        phone: str = "",
+        sid: str = "",
+        timeout: int | None = None,
+        interval: int | None = None,
+        auto_blacklist: bool = False,
+        on_attempt: Callable[[int, MessageResult], None] | None = None,
+    ) -> MessageResult: ...
+
+    def next_code(
+        self,
+        sid: str = "",
+        timeout: int | None = None,
+        interval: int | None = None,
+        auto_release: bool = True,
+        auto_blacklist: bool = True,
+        on_attempt: Callable[[int, MessageResult], None] | None = None,
+        **filters: Any,
+    ) -> tuple[str, str]: ...
+
+    def release(self, phone: str = "", sid: str = "") -> dict[str, Any]: ...
+
+    def blacklist(self, phone: str = "", sid: str = "") -> dict[str, Any]: ...
+
+    def close(self) -> None: ...

haozhuma/token_cache.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+TOKEN_CACHE_ENV = "HAOZHUMA_TOKEN_CACHE"
+APP_DIR_NAME = "haozhuma"
+TOKEN_CACHE_FILE_NAME = "token_cache.json"
+
+
+class TokenCache:
+    def __init__(self, path: str | Path | None = None):
+        self.path = Path(path).expanduser().resolve() if path else self.default_path()
+
+    @staticmethod
+    def default_path() -> Path:
+        override = os.getenv(TOKEN_CACHE_ENV)
+        if override:
+            return Path(override).expanduser().resolve()
+
+        appdata = os.getenv("APPDATA")
+        if appdata:
+            return Path(appdata) / APP_DIR_NAME / TOKEN_CACHE_FILE_NAME
+
+        return Path.home() / ".cache" / APP_DIR_NAME / TOKEN_CACHE_FILE_NAME
+
+    @staticmethod
+    def make_key(server: str, user: str, sid: str = "") -> str:
+        server_value = str(server or "").strip().rstrip("/").lower()
+        user_value = str(user or "").strip()
+        sid_value = str(sid or "").strip()
+        return "|".join([server_value, user_value, sid_value])
+
+    def load(self) -> dict[str, dict[str, Any]]:
+        if not self.path.exists():
+            return {}
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            return {}
+        if not isinstance(data, dict):
+            return {}
+        return {str(key): dict(value) for key, value in data.items() if isinstance(value, dict)}
+
+    def save(self, data: dict[str, dict[str, Any]]) -> Path:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(
+            json.dumps(data, ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        return self.path
+
+    def get(self, server: str, user: str, sid: str = "") -> str:
+        key = self.make_key(server, user, sid)
+        entry = self.load().get(key) or {}
+        return str(entry.get("token") or "").strip()
+
+    def set(self, server: str, user: str, sid: str, token: str) -> Path:
+        key = self.make_key(server, user, sid)
+        data = self.load()
+        data[key] = {
+            "server": str(server or ""),
+            "user": str(user or ""),
+            "sid": str(sid or ""),
+            "token": str(token or ""),
+            "updated_at": int(time.time()),
+        }
+        return self.save(data)
+
+    def delete(self, server: str, user: str, sid: str = "") -> bool:
+        key = self.make_key(server, user, sid)
+        data = self.load()
+        if key not in data:
+            return False
+        data.pop(key, None)
+        self.save(data)
+        return True
+
+    def clear(self) -> bool:
+        if self.path.exists():
+            self.path.unlink()
+            return True
+        return False

haozhuma-0.1.0.dist-info/METADATA

@@ -0,0 +1,191 @@
+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` | 保留 | 用法文档 |
+
+## 免责声明
+
+本模块仅用于已授权项目的验证码接收、测试环境验证和自动化流程开发。使用者需自行确认账号、项目和接口调用均符合平台规则与当地法律。

haozhuma-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+haozhuma/__init__.py,sha256=gx4Ui8CNa9C_NmCz7hL_X2yOmjioj79vJfCxstWpv7g,582
+haozhuma/client.py,sha256=7ug1WMjgsgSpsjNU0icHQUo4c9hyhPf4mkrEHIwTaiM,16020
+haozhuma/exceptions.py,sha256=XkeX5dN-5DcvKuh3nHijIBqXucSpIkGn_DRW9RK_WvI,1143
+haozhuma/models.py,sha256=4tlL3LKIg09dz1tbItJtiUG0XL4TLSh_XQJNsyBUQDA,2395
+haozhuma/provider.py,sha256=KLn8AXG8dgtvtISIvLtOAf4M_4-km-rSxyv0Tvi54Es,1641
+haozhuma/token_cache.py,sha256=m5Gb-vp9axlopeCbxeUnEq1PpI4llAgPFr8Fde1rZJY,2878
+haozhuma-0.1.0.dist-info/METADATA,sha256=idTCLF7uVksnUgMGmSqIT4LD03eJz-dJpMGgIX4fQ5o,5228
+haozhuma-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+haozhuma-0.1.0.dist-info/top_level.txt,sha256=ls6AnC1j0U2-OVa60J0BdgQcZLEdKxRpRjZANXOtw6U,9
+haozhuma-0.1.0.dist-info/RECORD,,

haozhuma-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

haozhuma-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+haozhuma