perk-pushplus-sdk 1.0.0__tar.gz

perk_pushplus_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: perk-pushplus-sdk
+Version: 1.0.0
+Summary: pushplus(推送加) 官方接口的 Python SDK，覆盖消息发送接口与全部开放接口。
+Author: perk-net
+License: Apache-2.0
+Project-URL: Homepage, https://www.pushplus.plus
+Project-URL: Documentation, https://www.pushplus.plus/doc/guide/api.html
+Project-URL: Source, https://github.com/pushplus/perk-pushplus-python-sdk
+Project-URL: Issues, https://github.com/pushplus/perk-pushplus-python-sdk/issues
+Keywords: pushplus,wechat,notify,sdk,webhook
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+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 :: Communications
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+
+# perk-pushplus-python-sdk
+
+[pushplus(推送加)](https://www.pushplus.plus) 官方接口的 Python SDK，覆盖 **消息接口** 与 **全部开放接口**。
+
+- **消息接口**（`/send`、`/batchSend`）：单渠道 + 多渠道发送，含 Builder API。
+- **开放接口**（`/api/open/...`）：用户、消息、消息 token、群组、群组用户、好友、webhook、渠道、ClawBot、功能设置、预处理信息。
+- **AccessKey 自动管理**：缓存 + 过期前自动刷新；`code=401` 自动刷新并重试一次。
+- **本地限流守卫**：命中 `code=900` 后按 token 短路同 token 后续发送，避免被服务端长期封禁。
+- **回调解析**：`message_complate`、`add_topic_user`、`add_friend` 三类回调统一解析。
+- **类型友好**：`dataclass` + `Enum`，附带 `py.typed`。
+
+> 接口文档：
+> - 消息接口：<https://www.pushplus.plus/doc/guide/api.html>
+> - 开放接口：<https://www.pushplus.plus/doc/guide/openApi.html>
+
+## 安装
+
+```bash
+pip install perk-pushplus-sdk
+```
+
+## 快速开始
+
+### 1. 构建客户端
+
+```python
+from perk_pushplus import PushPlusClient
+
+client = (
+    PushPlusClient.builder()
+    .token("your_user_token")          # 个人中心 -> 一对一推送
+    .secret_key("your_secret_key")     # 个人中心 -> 开发设置（开放接口必填）
+    .build()
+)
+```
+
+> `PushPlusClient` 线程安全，建议作为单例长期持有。
+
+### 2. 发送消息
+
+```python
+from perk_pushplus import Channel, SendRequest, Template
+
+# 最简：默认 wechat / html
+short_code = client.send_simple("标题", "<b>内容</b>")
+
+# 完整：使用 Builder
+short_code = client.send(
+    SendRequest.builder()
+    .title("CPU 告警")
+    .content("# CPU > 90%\n请尽快处理")
+    .template(Template.MARKDOWN)
+    .channel(Channel.WECHAT)
+    .topic("ops")
+    .callback_url("https://your.host/pushplus/callback")
+    .build()
+)
+```
+
+### 3. 多渠道发送
+
+```python
+from perk_pushplus import BatchSendRequest, Channel
+
+results = client.batch_send(
+    BatchSendRequest.builder()
+    .title("多渠道告警")
+    .content("CPU > 90%")
+    .channel(Channel.WECHAT).option("")
+    .channel(Channel.WEBHOOK).option("bark")
+    .channel(Channel.EXTENSION).option("")
+    .build()
+)
+for r in results:
+    print(r.channel, r.shortCode, r.code, r.message)
+```
+
+### 4. 开放接口
+
+```python
+# 用户
+info = client.user.my_info()
+limit = client.user.get_limit_time()
+
+# 消息
+page = client.open_message.list()
+result = client.open_message.query_result("short-code")
+
+# 消息 token
+from perk_pushplus import MessageTokenAddRequest
+new_token = client.message_token.add(MessageTokenAddRequest(name="for-jenkins"))
+
+# 群组
+from perk_pushplus import TopicListQuery
+topics = client.topic.list(TopicListQuery.of(1, 20, topic_type=0))
+detail = client.topic.detail(topic_id=123)
+
+# 好友
+qr = client.friend.get_qr_code(content="welcome")
+friends = client.friend.list()
+
+# webhook 渠道
+webhooks = client.webhook.list()
+
+# 设置
+client.setting.change_is_send(1)  # 启用发送
+
+# 预处理（会员）
+client.pre.test(...)
+```
+
+### 5. 异步发送
+
+```python
+fut = client.send_async(SendRequest(content="hello"))
+print(fut.result(timeout=10))
+```
+
+### 6. 回调解析
+
+```python
+from perk_pushplus import CallbackEvent, callback_parser
+
+# 在你的 web 框架（Flask/FastAPI/Django/...）的回调入口里：
+def on_pushplus_callback(raw_body: str) -> str:
+    payload = callback_parser.parse(raw_body)
+    if payload.event is CallbackEvent.MESSAGE_COMPLETE:
+        info = payload.messageInfo
+        print("发送结果", info.shortCode, info.get_send_status_enum())
+    elif payload.event is CallbackEvent.ADD_TOPIC_USER:
+        print("新订阅", payload.topicUserInfo.openId)
+    elif payload.event is CallbackEvent.ADD_FRIEND:
+        print("新好友", payload.friendInfo.token, payload.qrCode)
+    return "ok"
+```
+
+## 配置
+
+`PushPlusClient.builder()` 支持的全部参数：
+
+| 方法                                    | 默认值                       | 说明                                                   |
+| ------------------------------------- | ------------------------- | ---------------------------------------------------- |
+| `token(str)`                          | -                         | 用户 token 或消息 token；发送消息接口默认使用                        |
+| `secret_key(str)`                     | -                         | 开放接口 secretKey                                       |
+| `base_url(str)`                       | `https://www.pushplus.plus` | 服务地址                                                 |
+| `connect_timeout(float)`              | `10.0` 秒                  | 连接超时                                                 |
+| `read_timeout(float)`                 | `30.0` 秒                  | 读超时                                                  |
+| `access_key_refresh_ahead_seconds(int)` | `300`                     | 在 AccessKey 过期前多少秒主动刷新                               |
+| `log_request(bool)`                   | `False`                   | 打印 DEBUG 级请求/响应日志                                    |
+| `rate_limit_guard_enabled(bool)`      | `True`                    | 是否启用本地限流守卫（命中 900 后短路）                               |
+| `rate_limit_cooldown_seconds(float)`  | `None`（次日 0 点）            | 命中 900 后的本地禁推时长（秒）                                   |
+| `user_agent(str)`                     | `perk-pushplus-python-sdk/<v>` | UA 头                                              |
+| `http_requester(HttpRequester)`       | 内置 `requests` 实现           | 自定义 HTTP 客户端（aiohttp/httpx 等可适配）                     |
+
+## 错误处理
+
+所有请求异常都会抛出 `PushPlusError`：
+
+```python
+from perk_pushplus import ErrorCode, PushPlusError
+
+try:
+    client.send_simple("t", "c")
+except PushPlusError as exc:
+    if exc.is_rate_limited():
+        print("命中 code=900，已被本地守卫拒绝")
+    elif exc.error_code is ErrorCode.NOT_VERIFIED:
+        print("账号未实名")
+    else:
+        print(exc.code, exc.message)
+```
+
+`PushPlusError` 暴露：
+
+- `code`：业务 code 或 HTTP 状态码
+- `message`：错误描述
+- `error_code` -> `ErrorCode` 枚举
+- `is_rate_limited()`：是否为 `code=900`
+
+## 自定义 HTTP 客户端
+
+实现 `HttpRequester`（`Protocol`）即可：
+
+```python
+from perk_pushplus import HttpRequester, HttpResponse
+
+class MyRequester(HttpRequester):
+    def execute(self, method, url, headers, body) -> HttpResponse:
+        ...
+
+client = PushPlusClient.builder().http_requester(MyRequester()).build()
+```
+
+## 兼容性
+
+- Python `>= 3.8`
+- 仅依赖 `requests`
+
+## 许可证
+
+Apache License 2.0

perk_pushplus_sdk-1.0.0/README.md

@@ -0,0 +1,201 @@
+# perk-pushplus-python-sdk
+
+[pushplus(推送加)](https://www.pushplus.plus) 官方接口的 Python SDK，覆盖 **消息接口** 与 **全部开放接口**。
+
+- **消息接口**（`/send`、`/batchSend`）：单渠道 + 多渠道发送，含 Builder API。
+- **开放接口**（`/api/open/...`）：用户、消息、消息 token、群组、群组用户、好友、webhook、渠道、ClawBot、功能设置、预处理信息。
+- **AccessKey 自动管理**：缓存 + 过期前自动刷新；`code=401` 自动刷新并重试一次。
+- **本地限流守卫**：命中 `code=900` 后按 token 短路同 token 后续发送，避免被服务端长期封禁。
+- **回调解析**：`message_complate`、`add_topic_user`、`add_friend` 三类回调统一解析。
+- **类型友好**：`dataclass` + `Enum`，附带 `py.typed`。
+
+> 接口文档：
+> - 消息接口：<https://www.pushplus.plus/doc/guide/api.html>
+> - 开放接口：<https://www.pushplus.plus/doc/guide/openApi.html>
+
+## 安装
+
+```bash
+pip install perk-pushplus-sdk
+```
+
+## 快速开始
+
+### 1. 构建客户端
+
+```python
+from perk_pushplus import PushPlusClient
+
+client = (
+    PushPlusClient.builder()
+    .token("your_user_token")          # 个人中心 -> 一对一推送
+    .secret_key("your_secret_key")     # 个人中心 -> 开发设置（开放接口必填）
+    .build()
+)
+```
+
+> `PushPlusClient` 线程安全，建议作为单例长期持有。
+
+### 2. 发送消息
+
+```python
+from perk_pushplus import Channel, SendRequest, Template
+
+# 最简：默认 wechat / html
+short_code = client.send_simple("标题", "<b>内容</b>")
+
+# 完整：使用 Builder
+short_code = client.send(
+    SendRequest.builder()
+    .title("CPU 告警")
+    .content("# CPU > 90%\n请尽快处理")
+    .template(Template.MARKDOWN)
+    .channel(Channel.WECHAT)
+    .topic("ops")
+    .callback_url("https://your.host/pushplus/callback")
+    .build()
+)
+```
+
+### 3. 多渠道发送
+
+```python
+from perk_pushplus import BatchSendRequest, Channel
+
+results = client.batch_send(
+    BatchSendRequest.builder()
+    .title("多渠道告警")
+    .content("CPU > 90%")
+    .channel(Channel.WECHAT).option("")
+    .channel(Channel.WEBHOOK).option("bark")
+    .channel(Channel.EXTENSION).option("")
+    .build()
+)
+for r in results:
+    print(r.channel, r.shortCode, r.code, r.message)
+```
+
+### 4. 开放接口
+
+```python
+# 用户
+info = client.user.my_info()
+limit = client.user.get_limit_time()
+
+# 消息
+page = client.open_message.list()
+result = client.open_message.query_result("short-code")
+
+# 消息 token
+from perk_pushplus import MessageTokenAddRequest
+new_token = client.message_token.add(MessageTokenAddRequest(name="for-jenkins"))
+
+# 群组
+from perk_pushplus import TopicListQuery
+topics = client.topic.list(TopicListQuery.of(1, 20, topic_type=0))
+detail = client.topic.detail(topic_id=123)
+
+# 好友
+qr = client.friend.get_qr_code(content="welcome")
+friends = client.friend.list()
+
+# webhook 渠道
+webhooks = client.webhook.list()
+
+# 设置
+client.setting.change_is_send(1)  # 启用发送
+
+# 预处理（会员）
+client.pre.test(...)
+```
+
+### 5. 异步发送
+
+```python
+fut = client.send_async(SendRequest(content="hello"))
+print(fut.result(timeout=10))
+```
+
+### 6. 回调解析
+
+```python
+from perk_pushplus import CallbackEvent, callback_parser
+
+# 在你的 web 框架（Flask/FastAPI/Django/...）的回调入口里：
+def on_pushplus_callback(raw_body: str) -> str:
+    payload = callback_parser.parse(raw_body)
+    if payload.event is CallbackEvent.MESSAGE_COMPLETE:
+        info = payload.messageInfo
+        print("发送结果", info.shortCode, info.get_send_status_enum())
+    elif payload.event is CallbackEvent.ADD_TOPIC_USER:
+        print("新订阅", payload.topicUserInfo.openId)
+    elif payload.event is CallbackEvent.ADD_FRIEND:
+        print("新好友", payload.friendInfo.token, payload.qrCode)
+    return "ok"
+```
+
+## 配置
+
+`PushPlusClient.builder()` 支持的全部参数：
+
+| 方法                                    | 默认值                       | 说明                                                   |
+| ------------------------------------- | ------------------------- | ---------------------------------------------------- |
+| `token(str)`                          | -                         | 用户 token 或消息 token；发送消息接口默认使用                        |
+| `secret_key(str)`                     | -                         | 开放接口 secretKey                                       |
+| `base_url(str)`                       | `https://www.pushplus.plus` | 服务地址                                                 |
+| `connect_timeout(float)`              | `10.0` 秒                  | 连接超时                                                 |
+| `read_timeout(float)`                 | `30.0` 秒                  | 读超时                                                  |
+| `access_key_refresh_ahead_seconds(int)` | `300`                     | 在 AccessKey 过期前多少秒主动刷新                               |
+| `log_request(bool)`                   | `False`                   | 打印 DEBUG 级请求/响应日志                                    |
+| `rate_limit_guard_enabled(bool)`      | `True`                    | 是否启用本地限流守卫（命中 900 后短路）                               |
+| `rate_limit_cooldown_seconds(float)`  | `None`（次日 0 点）            | 命中 900 后的本地禁推时长（秒）                                   |
+| `user_agent(str)`                     | `perk-pushplus-python-sdk/<v>` | UA 头                                              |
+| `http_requester(HttpRequester)`       | 内置 `requests` 实现           | 自定义 HTTP 客户端（aiohttp/httpx 等可适配）                     |
+
+## 错误处理
+
+所有请求异常都会抛出 `PushPlusError`：
+
+```python
+from perk_pushplus import ErrorCode, PushPlusError
+
+try:
+    client.send_simple("t", "c")
+except PushPlusError as exc:
+    if exc.is_rate_limited():
+        print("命中 code=900，已被本地守卫拒绝")
+    elif exc.error_code is ErrorCode.NOT_VERIFIED:
+        print("账号未实名")
+    else:
+        print(exc.code, exc.message)
+```
+
+`PushPlusError` 暴露：
+
+- `code`：业务 code 或 HTTP 状态码
+- `message`：错误描述
+- `error_code` -> `ErrorCode` 枚举
+- `is_rate_limited()`：是否为 `code=900`
+
+## 自定义 HTTP 客户端
+
+实现 `HttpRequester`（`Protocol`）即可：
+
+```python
+from perk_pushplus import HttpRequester, HttpResponse
+
+class MyRequester(HttpRequester):
+    def execute(self, method, url, headers, body) -> HttpResponse:
+        ...
+
+client = PushPlusClient.builder().http_requester(MyRequester()).build()
+```
+
+## 兼容性
+
+- Python `>= 3.8`
+- 仅依赖 `requests`
+
+## 许可证
+
+Apache License 2.0

perk_pushplus_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "perk-pushplus-sdk"
+version = "1.0.0"
+description = "pushplus(推送加) 官方接口的 Python SDK，覆盖消息发送接口与全部开放接口。"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.8"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "perk-net" },
+]
+keywords = ["pushplus", "wechat", "notify", "sdk", "webhook"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.25.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "responses>=0.23",
+]
+
+[project.urls]
+Homepage = "https://www.pushplus.plus"
+Documentation = "https://www.pushplus.plus/doc/guide/api.html"
+Source = "https://github.com/pushplus/perk-pushplus-python-sdk"
+Issues = "https://github.com/pushplus/perk-pushplus-python-sdk/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+perk_pushplus = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

perk_pushplus_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

perk_pushplus_sdk-1.0.0/src/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",
+]