perk-pushplus-sdk 1.0.0__py3-none-any.whl

perk_pushplus/__init__.py

@@ -0,0 +1,155 @@
+"""perk-pushplus-python-sdk: PushPlus 推送加官方接口的 Python SDK。
+
+提供消息接口（``/send``、``/batchSend``）以及全部开放接口的封装，
+内置 AccessKey 自动管理与本地限流守卫。
+
+参考文档：
+- 消息接口：https://www.pushplus.plus/doc/guide/api.html
+- 开放接口：https://www.pushplus.plus/doc/guide/openApi.html
+
+快速使用::
+
+    from perk_pushplus import PushPlusClient
+
+    client = PushPlusClient.builder() \
+        .token("your_user_token") \
+        .secret_key("your_secret_key") \
+        .build()
+
+    short_code = client.send_simple("标题", "内容")
+"""
+from __future__ import annotations
+
+from . import callback_parser
+from .access_key import AccessKeyManager
+from .client import PushPlusClient, PushPlusClientBuilder
+from .config import DEFAULT_BASE_URL, PushPlusConfig
+from .enums import (
+    CallbackEvent,
+    Channel,
+    ErrorCode,
+    SendStatus,
+    Template,
+    WebhookType,
+)
+from .exceptions import PushPlusError, PushPlusException
+from .http import HttpRequester, HttpResponse, RequestsHttpRequester
+from .models import (
+    AccessKeyResult,
+    ApiResponse,
+    BatchSendRequest,
+    BatchSendResult,
+    CallbackFriendInfo,
+    CallbackPayload,
+    ClawBotInfo,
+    ClawBotMessage,
+    ClawBotQrCode,
+    CpItem,
+    FriendItem,
+    FriendQrCode,
+    MailDetail,
+    MailItem,
+    MessageCompleteInfo,
+    MessageItem,
+    MessageTokenAddRequest,
+    MessageTokenEditRequest,
+    MessageTokenItem,
+    MessageTokenOption,
+    MpItem,
+    PageQuery,
+    PageResult,
+    PreDetail,
+    PreItem,
+    PreSaveRequest,
+    PreTestRequest,
+    SendCount,
+    SendMessageResult,
+    SendRequest,
+    TopicAddRequest,
+    TopicDetail,
+    TopicEditRequest,
+    TopicItem,
+    TopicListQuery,
+    TopicQrCode,
+    TopicUserInfo,
+    TopicUserItem,
+    TopicUserListQuery,
+    UserDefaultDetail,
+    UserDefaultItem,
+    UserDefaultSaveRequest,
+    UserInfo,
+    UserLimitTime,
+    WebhookItem,
+    WebhookSaveRequest,
+)
+from .rate_limit import RateLimitGuard
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+    "PushPlusClient",
+    "PushPlusClientBuilder",
+    "PushPlusConfig",
+    "DEFAULT_BASE_URL",
+    "PushPlusError",
+    "PushPlusException",
+    "AccessKeyManager",
+    "RateLimitGuard",
+    "HttpRequester",
+    "HttpResponse",
+    "RequestsHttpRequester",
+    "callback_parser",
+    "Channel",
+    "Template",
+    "CallbackEvent",
+    "SendStatus",
+    "WebhookType",
+    "ErrorCode",
+    "ApiResponse",
+    "PageQuery",
+    "PageResult",
+    "SendRequest",
+    "BatchSendRequest",
+    "BatchSendResult",
+    "CallbackPayload",
+    "MessageCompleteInfo",
+    "TopicUserInfo",
+    "CallbackFriendInfo",
+    "AccessKeyResult",
+    "MessageItem",
+    "SendMessageResult",
+    "UserInfo",
+    "UserLimitTime",
+    "SendCount",
+    "MessageTokenItem",
+    "MessageTokenOption",
+    "MessageTokenAddRequest",
+    "MessageTokenEditRequest",
+    "TopicItem",
+    "TopicDetail",
+    "TopicQrCode",
+    "TopicListQuery",
+    "TopicUserListQuery",
+    "TopicUserItem",
+    "TopicAddRequest",
+    "TopicEditRequest",
+    "FriendItem",
+    "FriendQrCode",
+    "WebhookItem",
+    "WebhookSaveRequest",
+    "MpItem",
+    "CpItem",
+    "MailItem",
+    "MailDetail",
+    "ClawBotQrCode",
+    "ClawBotInfo",
+    "ClawBotMessage",
+    "UserDefaultItem",
+    "UserDefaultDetail",
+    "UserDefaultSaveRequest",
+    "PreItem",
+    "PreDetail",
+    "PreSaveRequest",
+    "PreTestRequest",
+]

perk_pushplus/access_key.py

@@ -0,0 +1,77 @@
+"""AccessKey 管理器：缓存 + 过期前自动刷新 + 多线程安全。"""
+from __future__ import annotations
+
+import logging
+import threading
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING, Optional
+
+from .config import PushPlusConfig
+from .exceptions import PushPlusError
+
+if TYPE_CHECKING:
+    from .api.access_key import AccessKeyApi
+
+
+_logger = logging.getLogger("perk_pushplus")
+
+
+class AccessKeyManager:
+    """提供线程安全的 AccessKey 缓存与过期前自动刷新能力。
+
+    在调用任意需要 ``access-key`` 的开放接口前，:class:`OpenApi` 基类会
+    自动通过本类拿到一个有效的 AccessKey。
+
+    刷新策略：在 ``expiresIn`` 到期前 :attr:`PushPlusConfig.access_key_refresh_ahead_seconds`
+    秒视为过期。文档说明老 key 在新 key 生成后 5 分钟内仍可用，因此默认 300 秒提前量足够安全。
+
+    线程安全：多线程并发调用 :meth:`get_access_key` 时仅会触发一次刷新。
+    """
+
+    def __init__(self, config: PushPlusConfig, access_key_api: "AccessKeyApi") -> None:
+        self._config = config
+        self._api = access_key_api
+        self._lock = threading.Lock()
+        self._cached_key: Optional[str] = None
+        self._expire_at: datetime = datetime.min
+
+    def get_access_key(self) -> str:
+        """获取有效的 AccessKey。如已缓存且未过期则直接返回；否则触发刷新。"""
+
+        if self._is_valid():
+            return self._cached_key  # type: ignore[return-value]
+        return self.refresh()
+
+    def refresh(self) -> str:
+        """强制刷新。多线程并发调用时仅会真正发起一次刷新请求。"""
+
+        with self._lock:
+            if self._is_valid():
+                return self._cached_key  # type: ignore[return-value]
+            result = self._api.get_access_key()
+            if result is None or not result.accessKey:
+                raise PushPlusError("获取 AccessKey 失败：返回为空")
+            ttl_seconds = int(result.expiresIn) if result.expiresIn is not None else 7200
+            ahead = max(0, int(self._config.access_key_refresh_ahead_seconds))
+            effective_ttl = max(1, ttl_seconds - ahead)
+            self._cached_key = result.accessKey
+            self._expire_at = datetime.now() + timedelta(seconds=effective_ttl)
+            _logger.debug(
+                "[pushplus] AccessKey refreshed, ttl=%ss, refresh in <= %ss",
+                ttl_seconds,
+                effective_ttl,
+            )
+            return self._cached_key
+
+    def invalidate(self) -> None:
+        """失效缓存。下次调用 :meth:`get_access_key` 时会重新拉取。"""
+
+        with self._lock:
+            self._cached_key = None
+            self._expire_at = datetime.min
+
+    def _is_valid(self) -> bool:
+        return self._cached_key is not None and datetime.now() < self._expire_at
+
+
+__all__ = ["AccessKeyManager"]

perk_pushplus/api/__init__.py

@@ -0,0 +1,33 @@
+"""API 子包入口。"""
+from .access_key import AccessKeyApi
+from .base import AbstractApi, OpenAbstractApi
+from .channel import ChannelApi
+from .clawbot import ClawBotApi
+from .friend import FriendApi
+from .message import MessageApi
+from .message_token import MessageTokenApi
+from .open_message import OpenMessageApi
+from .pre import PreApi
+from .setting import SettingApi
+from .topic import TopicApi
+from .topic_user import TopicUserApi
+from .user import UserApi
+from .webhook import WebhookApi
+
+__all__ = [
+    "AbstractApi",
+    "OpenAbstractApi",
+    "AccessKeyApi",
+    "MessageApi",
+    "OpenMessageApi",
+    "UserApi",
+    "MessageTokenApi",
+    "TopicApi",
+    "TopicUserApi",
+    "FriendApi",
+    "WebhookApi",
+    "ChannelApi",
+    "ClawBotApi",
+    "SettingApi",
+    "PreApi",
+]

perk_pushplus/api/access_key.py

@@ -0,0 +1,44 @@
+"""开放接口 - 获取 AccessKey。"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..config import PushPlusConfig
+from ..exceptions import PushPlusError
+from ..http import HttpRequester
+from ..models import AccessKeyResult
+from .base import AbstractApi
+
+
+class AccessKeyApi(AbstractApi):
+    """对应文档「一. 获取 AccessKey」。"""
+
+    def __init__(self, config: PushPlusConfig, http: HttpRequester) -> None:
+        super().__init__(config, http)
+
+    def get_access_key(
+        self,
+        token: Optional[str] = None,
+        secret_key: Optional[str] = None,
+    ) -> AccessKeyResult:
+        """获取 AccessKey。
+
+        ``token`` / ``secret_key`` 不传时使用 :class:`PushPlusConfig` 中的配置。
+        """
+
+        token = token or self.config.token
+        secret_key = secret_key or self.config.secret_key
+        if not token:
+            raise PushPlusError("获取 AccessKey 需要 token")
+        if not secret_key:
+            raise PushPlusError("获取 AccessKey 需要 secretKey")
+        body = {"token": token, "secretKey": secret_key}
+        result = self.execute_for_data(
+            "POST", "/api/common/openApi/getAccessKey", None, body, AccessKeyResult
+        )
+        if result is None:
+            raise PushPlusError("获取 AccessKey 失败：返回为空")
+        return result
+
+
+__all__ = ["AccessKeyApi"]

perk_pushplus/api/base.py

@@ -0,0 +1,210 @@
+"""API 基类：提供请求执行、统一错误处理、access-key 自动注入与重试。"""
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, Dict, Mapping, Optional, Type, TypeVar
+from urllib.parse import quote
+
+from ..config import PushPlusConfig
+from ..exceptions import PushPlusError
+from ..http import HttpRequester, to_json
+from ..models.base import ApiResponse, model_from_dict, model_to_dict
+
+if TYPE_CHECKING:
+    from ..access_key import AccessKeyManager
+
+
+T = TypeVar("T")
+HEADER_ACCESS_KEY = "access-key"
+_CODE_ACCESS_KEY_INVALID = 401
+
+
+class AbstractApi:
+    """API 基类。"""
+
+    def __init__(self, config: PushPlusConfig, http: HttpRequester) -> None:
+        self.config = config
+        self.http = http
+
+    def resolve_url(self, path: str) -> str:
+        """拼接绝对 URL。"""
+
+        if path.startswith("http://") or path.startswith("https://"):
+            return path
+        base = self.config.resolve_base_url()
+        return base + (path if path.startswith("/") else "/" + path)
+
+    @staticmethod
+    def build_query(params: Optional[Mapping[str, Any]]) -> str:
+        """把 mapping 拼成 query string；忽略 ``None`` 值。"""
+
+        if not params:
+            return ""
+        parts = []
+        for key, value in params.items():
+            if value is None:
+                continue
+            parts.append(f"{quote(str(key), safe='')}={quote(str(value), safe='')}")
+        return "&".join(parts)
+
+    @classmethod
+    def append_query(cls, path: str, params: Optional[Mapping[str, Any]]) -> str:
+        """在 path 上追加 query string。"""
+
+        q = cls.build_query(params)
+        if not q:
+            return path
+        sep = "&" if "?" in path else "?"
+        return f"{path}{sep}{q}"
+
+    def execute(
+        self,
+        method: str,
+        path: str,
+        headers: Optional[Dict[str, str]],
+        body: Any,
+        data_type: Optional[Type[T]] = None,
+    ) -> ApiResponse[T]:
+        """执行请求并返回原始 :class:`ApiResponse`（不进行 code 校验）。"""
+
+        url = self.resolve_url(path)
+        body_json: Optional[str]
+        if body is None:
+            body_json = None
+        elif isinstance(body, str):
+            body_json = body
+        else:
+            body_json = to_json(model_to_dict(body))
+        resp = self.http.execute(method, url, headers, body_json)
+        if not resp.is_successful:
+            raise PushPlusError(
+                f"PushPlus 接口 HTTP 调用失败: status={resp.status_code}, body={resp.body}",
+                code=resp.status_code,
+            )
+        return self._parse_api_response(resp.body, data_type)
+
+    def execute_for_data(
+        self,
+        method: str,
+        path: str,
+        headers: Optional[Dict[str, str]],
+        body: Any,
+        data_type: Optional[Type[T]] = None,
+    ) -> Optional[T]:
+        """执行请求并直接返回 ``data``；非 200 抛出异常。"""
+
+        resp = self.execute(method, path, headers, body, data_type)
+        if not resp.is_success():
+            raise PushPlusError(
+                self._build_business_error_message("PushPlus 接口业务失败", resp),
+                code=resp.code if resp.code is not None else -1,
+            )
+        return resp.data
+
+    @staticmethod
+    def _parse_api_response(
+        response_body: str, data_type: Optional[Type[T]] = None
+    ) -> ApiResponse[T]:
+        if response_body is None or response_body == "":
+            raise PushPlusError("PushPlus 接口返回为空")
+        try:
+            payload = json.loads(response_body)
+        except (TypeError, ValueError) as exc:
+            raise PushPlusError(
+                f"解析 PushPlus 响应 JSON 失败: {exc}, payload={response_body}", cause=exc
+            ) from exc
+        if not isinstance(payload, dict):
+            raise PushPlusError(f"PushPlus 接口返回非 JSON 对象: {response_body}")
+
+        result: ApiResponse[T] = ApiResponse(
+            code=payload.get("code"), msg=payload.get("msg"), data=None
+        )
+        data_node = payload.get("data")
+        if result.is_success():
+            if data_node is None:
+                result.data = None
+                return result
+            try:
+                if data_type is None:
+                    result.data = data_node
+                else:
+                    result.data = model_from_dict(data_type, data_node)
+            except Exception as exc:  # noqa: BLE001
+                raise PushPlusError(
+                    f"解析 PushPlus 响应 data 字段失败: {exc}, payload={response_body}",
+                    cause=exc,
+                ) from exc
+            return result
+        # 业务失败：把 data 中的字符串/简单值附加到 msg。
+        data_text = AbstractApi._extract_data_text(data_node)
+        if data_text:
+            if not result.msg:
+                result.msg = data_text
+            elif data_text not in result.msg:
+                result.msg = f"{result.msg}: {data_text}"
+        return result
+
+    @staticmethod
+    def _extract_data_text(data_node: Any) -> Optional[str]:
+        if data_node is None:
+            return None
+        if isinstance(data_node, (str, int, float, bool)):
+            return str(data_node)
+        try:
+            return json.dumps(data_node, ensure_ascii=False)
+        except Exception:  # noqa: BLE001
+            return None
+
+    @staticmethod
+    def _build_business_error_message(prefix: str, resp: ApiResponse) -> str:
+        return f"{prefix}: code={resp.code}, msg={resp.msg}"
+
+
+class OpenAbstractApi(AbstractApi):
+    """开放接口基类。
+
+    会自动在 header 中带上 ``access-key``，并在收到 ``code=401`` 时尝试刷新 AccessKey 后重试一次。
+    """
+
+    def __init__(
+        self,
+        config: PushPlusConfig,
+        http: HttpRequester,
+        access_key_manager: "AccessKeyManager",
+    ) -> None:
+        super().__init__(config, http)
+        self.access_key_manager = access_key_manager
+
+    def _headers_with_access_key(self) -> Dict[str, str]:
+        return {HEADER_ACCESS_KEY: self.access_key_manager.get_access_key()}
+
+    def execute_open(
+        self,
+        method: str,
+        path: str,
+        body: Any = None,
+        data_type: Optional[Type[T]] = None,
+    ) -> Optional[T]:
+        """执行带 ``access-key`` 的请求；当返回 ``code=401`` 时自动刷新 key 并重试一次。"""
+
+        headers = self._headers_with_access_key()
+        resp = self.execute(method, path, headers, body, data_type)
+        if resp.is_success():
+            return resp.data
+        if resp.code is not None and int(resp.code) == _CODE_ACCESS_KEY_INVALID:
+            self.access_key_manager.invalidate()
+            retry_headers = self._headers_with_access_key()
+            retry = self.execute(method, path, retry_headers, body, data_type)
+            if retry.is_success():
+                return retry.data
+            raise PushPlusError(
+                f"PushPlus 开放接口业务失败(重试后): code={retry.code}, msg={retry.msg}",
+                code=retry.code if retry.code is not None else -1,
+            )
+        raise PushPlusError(
+            f"PushPlus 开放接口业务失败: code={resp.code}, msg={resp.msg}",
+            code=resp.code if resp.code is not None else -1,
+        )
+
+
+__all__ = ["AbstractApi", "OpenAbstractApi", "HEADER_ACCESS_KEY"]

perk_pushplus/api/channel.py

@@ -0,0 +1,47 @@
+"""开放接口 - 微信公众号/企业微信/邮箱渠道列表（文档「七. 渠道配置接口」 5-8）。"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..models import CpItem, MailDetail, MailItem, MpItem, PageQuery, PageResult
+from .base import OpenAbstractApi
+
+
+class ChannelApi(OpenAbstractApi):
+    """微信公众号 / 企业微信 / 邮箱渠道列表。"""
+
+    def mp_list(self, query: Optional[PageQuery] = None) -> PageResult[MpItem]:
+        """微信公众号渠道列表。"""
+
+        body = query if query is not None else PageQuery()
+        result = self.execute_open(
+            "POST", "/api/open/mp/list", body, PageResult[MpItem]
+        )
+        return result or PageResult(list=[])
+
+    def cp_list(self, query: Optional[PageQuery] = None) -> PageResult[CpItem]:
+        """企业微信应用渠道列表。"""
+
+        body = query if query is not None else PageQuery()
+        result = self.execute_open(
+            "POST", "/api/open/cp/list", body, PageResult[CpItem]
+        )
+        return result or PageResult(list=[])
+
+    def mail_list(self, query: Optional[PageQuery] = None) -> PageResult[MailItem]:
+        """邮箱渠道列表。"""
+
+        body = query if query is not None else PageQuery()
+        result = self.execute_open(
+            "POST", "/api/open/mail/list", body, PageResult[MailItem]
+        )
+        return result or PageResult(list=[])
+
+    def mail_detail(self, mail_id: int) -> MailDetail:
+        """邮箱渠道详情。"""
+
+        path = self.append_query("/api/open/mail/detail", {"mailId": int(mail_id)})
+        return self.execute_open("GET", path, None, MailDetail)
+
+
+__all__ = ["ChannelApi"]

perk_pushplus/api/clawbot.py

@@ -0,0 +1,49 @@
+"""开放接口 - 微信 ClawBot（文档「八. 微信ClawBot接口」）。"""
+from __future__ import annotations
+
+from typing import List
+
+from ..models import ClawBotInfo, ClawBotMessage, ClawBotQrCode
+from .base import OpenAbstractApi
+
+
+class ClawBotApi(OpenAbstractApi):
+    """微信 ClawBot 渠道相关接口。"""
+
+    def get_bot_qrcode(self) -> ClawBotQrCode:
+        """获取二维码。"""
+
+        return self.execute_open(
+            "GET", "/api/open/clawBot/getBotQrcode", None, ClawBotQrCode
+        )
+
+    def get_qrcode_status(self, qrcode: str) -> None:
+        """扫码结果查询。"""
+
+        path = self.append_query(
+            "/api/open/clawBot/getQrcodeStatus", {"getQrcodeStatus": qrcode}
+        )
+        self.execute_open("GET", path, None, None)
+
+    def bot_info(self) -> ClawBotInfo:
+        """绑定详情。"""
+
+        return self.execute_open(
+            "GET", "/api/open/clawBot/botInfo", None, ClawBotInfo
+        )
+
+    def unbind(self) -> None:
+        """解绑。"""
+
+        self.execute_open("GET", "/api/open/clawBot/unbind", None, None)
+
+    def get_msg(self) -> List[ClawBotMessage]:
+        """获取发送消息。"""
+
+        result = self.execute_open(
+            "GET", "/api/open/clawBot/getMsg", None, List[ClawBotMessage]
+        )
+        return result or []
+
+
+__all__ = ["ClawBotApi"]

perk_pushplus/api/friend.py

@@ -0,0 +1,58 @@
+"""开放接口 - 好友功能（文档「十. 好友功能接口」）。"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..models import FriendItem, FriendQrCode, PageQuery, PageResult
+from .base import OpenAbstractApi
+
+
+class FriendApi(OpenAbstractApi):
+    """好友相关接口。"""
+
+    def get_qr_code(
+        self,
+        app_id: Optional[str] = None,
+        content: Optional[str] = None,
+        second: Optional[int] = None,
+        scan_count: Optional[int] = None,
+    ) -> FriendQrCode:
+        """获取个人二维码。"""
+
+        params = {}
+        if app_id is not None:
+            params["appId"] = app_id
+        if content is not None:
+            params["content"] = content
+        if second is not None:
+            params["second"] = int(second)
+        if scan_count is not None:
+            params["scanCount"] = int(scan_count)
+        path = self.append_query("/api/open/friend/getQrCode", params)
+        return self.execute_open("GET", path, None, FriendQrCode)
+
+    def list(self, query: Optional[PageQuery] = None) -> PageResult[FriendItem]:
+        """获取好友列表。"""
+
+        body = query if query is not None else PageQuery()
+        result = self.execute_open(
+            "POST", "/api/open/friend/list", body, PageResult[FriendItem]
+        )
+        return result or PageResult(list=[])
+
+    def delete(self, friend_id: int) -> None:
+        """删除好友。"""
+
+        path = self.append_query(
+            "/api/open/friend/deleteFriend", {"friendId": int(friend_id)}
+        )
+        self.execute_open("GET", path, None, None)
+
+    def edit_remark(self, id_: int, remark: str) -> None:
+        """修改好友备注。"""
+
+        body = {"id": int(id_), "remark": remark}
+        self.execute_open("POST", "/api/open/friend/editRemark", body, None)
+
+
+__all__ = ["FriendApi"]