perk-pushplus-sdk 1.2.1__tar.gz → 1.2.2__tar.gz

{perk_pushplus_sdk-1.2.1 → perk_pushplus_sdk-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: perk-pushplus-sdk
-Version: 1.2.1
+Version: 1.2.2
 Summary: pushplus(推送加) 官方接口的 Python SDK，覆盖消息发送接口与全部开放接口。
 Author: perk-net
 License: Apache-2.0
@@ -35,7 +35,7 @@ Requires-Dist: responses>=0.23; extra == "dev"
 [pushplus(推送加)](https://www.pushplus.plus) 官方接口的 Python SDK，覆盖 **消息接口** 与 **全部开放接口**。
 
 - **消息接口**（`/send`、`/batchSend`）：单渠道 + 多渠道发送，含 Builder API。
-- **开放接口**（`/api/open/...` 与 `/push/api/open/...`）：用户、消息、消息 token、群组、群组用户、好友、webhook、渠道、ClawBot、功能设置、预处理信息、图片服务、push 表单、push 文档、push 表格。
+- **开放接口**（`/api/open/...` 与 `/push/api/open/...`）：用户、消息、消息 token、群组、群组用户、好友、webhook、渠道、ClawBot、QQ 机器人、功能设置、预处理信息、图片服务、push 表单、push 文档、push 表格。
 - **AccessKey 自动管理**：缓存 + 过期前自动刷新；`code=401` 自动刷新并重试一次。
 - **本地限流守卫**：命中 `code=900` 后按 token 短路同 token 后续发送，避免被服务端长期封禁。
 - **回调解析**：`message_complate`、`add_topic_user`、`add_friend` 三类回调统一解析。
@@ -168,6 +168,20 @@ topic_blacklist = client.topic_user.blacklist_list(TopicUserListQuery.of(1, 20,
 # webhook 渠道
 webhooks = client.webhook.list()
 
+# QQ 机器人：绑定 -> 认领群 -> 建配置 -> 发到群
+from perk_pushplus import QqBotSaveRequest
+link = client.qq_bot.get_bind_link()   # link.url 生成二维码，或私聊发送 link.bindCode
+bind = client.qq_bot.bot_info()        # bind.isBind == 1 表示已绑定
+qq_groups = client.qq_bot.group_list()
+client.qq_bot.add(QqBotSaveRequest(qqName="运维告警群", qqCode="ops-group", qqGroupId=qq_groups[0].id))
+client.send(SendRequest(
+    title="服务告警",
+    content="订单服务响应超时",
+    channel=Channel.QQ,
+    option="ops-group",  # 不传 option 则发给自己
+    template=Template.TXT,
+))
+
 # 设置
 client.setting.change_is_send(1)  # 启用发送
 

{perk_pushplus_sdk-1.2.1 → perk_pushplus_sdk-1.2.2}/README.md

@@ -3,7 +3,7 @@
 [pushplus(推送加)](https://www.pushplus.plus) 官方接口的 Python SDK，覆盖 **消息接口** 与 **全部开放接口**。
 
 - **消息接口**（`/send`、`/batchSend`）：单渠道 + 多渠道发送，含 Builder API。
-- **开放接口**（`/api/open/...` 与 `/push/api/open/...`）：用户、消息、消息 token、群组、群组用户、好友、webhook、渠道、ClawBot、功能设置、预处理信息、图片服务、push 表单、push 文档、push 表格。
+- **开放接口**（`/api/open/...` 与 `/push/api/open/...`）：用户、消息、消息 token、群组、群组用户、好友、webhook、渠道、ClawBot、QQ 机器人、功能设置、预处理信息、图片服务、push 表单、push 文档、push 表格。
 - **AccessKey 自动管理**：缓存 + 过期前自动刷新；`code=401` 自动刷新并重试一次。
 - **本地限流守卫**：命中 `code=900` 后按 token 短路同 token 后续发送，避免被服务端长期封禁。
 - **回调解析**：`message_complate`、`add_topic_user`、`add_friend` 三类回调统一解析。
@@ -136,6 +136,20 @@ topic_blacklist = client.topic_user.blacklist_list(TopicUserListQuery.of(1, 20,
 # webhook 渠道
 webhooks = client.webhook.list()
 
+# QQ 机器人：绑定 -> 认领群 -> 建配置 -> 发到群
+from perk_pushplus import QqBotSaveRequest
+link = client.qq_bot.get_bind_link()   # link.url 生成二维码，或私聊发送 link.bindCode
+bind = client.qq_bot.bot_info()        # bind.isBind == 1 表示已绑定
+qq_groups = client.qq_bot.group_list()
+client.qq_bot.add(QqBotSaveRequest(qqName="运维告警群", qqCode="ops-group", qqGroupId=qq_groups[0].id))
+client.send(SendRequest(
+    title="服务告警",
+    content="订单服务响应超时",
+    channel=Channel.QQ,
+    option="ops-group",  # 不传 option 则发给自己
+    template=Template.TXT,
+))
+
 # 设置
 client.setting.change_is_send(1)  # 启用发送
 

{perk_pushplus_sdk-1.2.1 → perk_pushplus_sdk-1.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "perk-pushplus-sdk"
-version = "1.2.1"
+version = "1.2.2"
 description = "pushplus(推送加) 官方接口的 Python SDK，覆盖消息发送接口与全部开放接口。"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.8"

{perk_pushplus_sdk-1.2.1 → perk_pushplus_sdk-1.2.2}/src/perk_pushplus/__init__.py

@@ -84,6 +84,12 @@ from .models import (
     PreItem,
     PreSaveRequest,
     PreTestRequest,
+    QqBotBindInfo,
+    QqBotBindLink,
+    QqBotInfo,
+    QqBotItem,
+    QqBotSaveRequest,
+    QqGroupItem,
     SendCount,
     SendMessageResult,
     SendRequest,
@@ -108,7 +114,7 @@ from .models import (
 )
 from .rate_limit import RateLimitGuard
 
-__version__ = "1.2.1"
+__version__ = "1.2.2"
 
 __all__ = [
     "__version__",
@@ -175,6 +181,12 @@ __all__ = [
     "ClawBotQrCode",
     "ClawBotInfo",
     "ClawBotMessage",
+    "QqBotBindLink",
+    "QqBotInfo",
+    "QqBotBindInfo",
+    "QqGroupItem",
+    "QqBotItem",
+    "QqBotSaveRequest",
     "UserDefaultItem",
     "UserDefaultDetail",
     "UserDefaultSaveRequest",

{perk_pushplus_sdk-1.2.1 → perk_pushplus_sdk-1.2.2}/src/perk_pushplus/api/__init__.py

@@ -12,6 +12,7 @@ from .message import MessageApi
 from .message_token import MessageTokenApi
 from .open_message import OpenMessageApi
 from .pre import PreApi
+from .qqbot import QqBotApi
 from .setting import SettingApi
 from .topic import TopicApi
 from .topic_user import TopicUserApi
@@ -32,6 +33,7 @@ __all__ = [
     "WebhookApi",
     "ChannelApi",
     "ClawBotApi",
+    "QqBotApi",
     "SettingApi",
     "PreApi",
     "ImageApi",

perk_pushplus_sdk-1.2.2/src/perk_pushplus/api/qqbot.py

@@ -0,0 +1,89 @@
+"""开放接口 - QQ 机器人（文档「九. QQ机器人接口」）。"""
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import List, Optional
+
+from ..models import (
+    PageQuery,
+    PageResult,
+    QqBotBindInfo,
+    QqBotBindLink,
+    QqBotItem,
+    QqBotSaveRequest,
+    QqGroupItem,
+)
+from .base import OpenAbstractApi
+
+SEND_TYPE_QQ_GROUP = 2
+"""发送到 QQ 群，目前渠道配置仅支持该类型。"""
+
+
+class QqBotApi(OpenAbstractApi):
+    """QQ 机器人绑定与渠道配置相关接口。"""
+
+    def get_bind_link(self, refresh: bool = False) -> QqBotBindLink:
+        """获取绑定链接与绑定码；``refresh=True`` 时旧绑定码失效并重新生成。"""
+
+        path = "/api/open/qqBot/getBindLink"
+        if refresh:
+            path = self.append_query(path, {"refresh": "true"})
+        return self.execute_open("GET", path, None, QqBotBindLink)
+
+    def bot_info(self) -> QqBotBindInfo:
+        """查询绑定状态。"""
+
+        return self.execute_open(
+            "GET", "/api/open/qqBot/botInfo", None, QqBotBindInfo
+        )
+
+    def unbind(self) -> None:
+        """解绑 QQ 机器人。"""
+
+        self.execute_open("GET", "/api/open/qqBot/unbind", None, None)
+
+    def group_list(self) -> List[QqGroupItem]:
+        """获取机器人已加入的 QQ 群列表。"""
+
+        result = self.execute_open(
+            "GET", "/api/open/qqBot/groupList", None, List[QqGroupItem]
+        )
+        return result or []
+
+    def list(self, query: Optional[PageQuery] = None) -> PageResult[QqBotItem]:
+        """获取 QQ 机器人渠道配置列表。"""
+
+        body = query if query is not None else PageQuery()
+        result = self.execute_open(
+            "POST", "/api/open/qqBot/list", body, PageResult[QqBotItem]
+        )
+        return result or PageResult(list=[])
+
+    def add(self, request: QqBotSaveRequest) -> None:
+        """新增渠道配置，用于把消息发送到指定 QQ 群；发给自己无需创建配置。"""
+
+        self.execute_open(
+            "POST", "/api/open/qqBot/add", _with_default_send_type(request), None
+        )
+
+    def edit(self, request: QqBotSaveRequest) -> None:
+        """修改渠道配置；配置编码不可修改。"""
+
+        self.execute_open(
+            "POST", "/api/open/qqBot/edit", _with_default_send_type(request), None
+        )
+
+    def delete(self, config_id: int) -> None:
+        """删除渠道配置。"""
+
+        path = self.append_query("/api/open/qqBot/delete", {"id": int(config_id)})
+        self.execute_open("DELETE", path, None, None)
+
+
+def _with_default_send_type(request: QqBotSaveRequest) -> QqBotSaveRequest:
+    if request is None or request.sendType is not None:
+        return request
+    return replace(request, sendType=SEND_TYPE_QQ_GROUP)
+
+
+__all__ = ["QqBotApi", "SEND_TYPE_QQ_GROUP"]

{perk_pushplus_sdk-1.2.1 → perk_pushplus_sdk-1.2.2}/src/perk_pushplus/client.py

@@ -15,6 +15,7 @@ from .api import (
     MessageTokenApi,
     OpenMessageApi,
     PreApi,
+    QqBotApi,
     SettingApi,
     TopicApi,
     TopicUserApi,
@@ -76,6 +77,7 @@ class PushPlusClient:
         self.webhook = WebhookApi(config, self.http_requester, self.access_key_manager)
         self.channel = ChannelApi(config, self.http_requester, self.access_key_manager)
         self.claw_bot = ClawBotApi(config, self.http_requester, self.access_key_manager)
+        self.qq_bot = QqBotApi(config, self.http_requester, self.access_key_manager)
         self.setting = SettingApi(config, self.http_requester, self.access_key_manager)
         self.pre = PreApi(config, self.http_requester, self.access_key_manager)
         self.image = ImageApi(config, self.http_requester, self.access_key_manager)

{perk_pushplus_sdk-1.2.1 → perk_pushplus_sdk-1.2.2}/src/perk_pushplus/enums.py

@@ -42,6 +42,8 @@ class Channel(_StrCodeEnum):
     """App 渠道（安卓/鸿蒙/iOS）。"""
     CLAWBOT = "clawbot"
     """微信 ClawBot。"""
+    QQ = "qq"
+    """QQ 机器人；不带 option 发给自己，option 填配置编码则发到对应 QQ 群。"""
 
     @property
     def code(self) -> str:

{perk_pushplus_sdk-1.2.1 → perk_pushplus_sdk-1.2.2}/src/perk_pushplus/models/__init__.py

@@ -36,6 +36,14 @@ from .open_friend import FriendBlacklistItem, FriendItem, FriendQrCode
 from .open_webhook import WebhookItem, WebhookSaveRequest
 from .open_channel import CpItem, MailDetail, MailItem, MpItem
 from .open_clawbot import ClawBotInfo, ClawBotMessage, ClawBotQrCode
+from .open_qqbot import (
+    QqBotBindInfo,
+    QqBotBindLink,
+    QqBotInfo,
+    QqBotItem,
+    QqBotSaveRequest,
+    QqGroupItem,
+)
 from .open_setting import UserDefaultDetail, UserDefaultItem, UserDefaultSaveRequest
 from .open_pre import PreDetail, PreItem, PreSaveRequest, PreTestRequest
 from .open_image import ImageItem, ImageUploadResult, ImageUploadToken
@@ -97,6 +105,12 @@ __all__ = [
     "ClawBotQrCode",
     "ClawBotInfo",
     "ClawBotMessage",
+    "QqBotBindLink",
+    "QqBotInfo",
+    "QqBotBindInfo",
+    "QqGroupItem",
+    "QqBotItem",
+    "QqBotSaveRequest",
     "UserDefaultItem",
     "UserDefaultDetail",
     "UserDefaultSaveRequest",

perk_pushplus_sdk-1.2.2/src/perk_pushplus/models/open_qqbot.py

@@ -0,0 +1,107 @@
+"""开放接口 - QQ 机器人模型。"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+@dataclass
+class QqBotBindLink:
+    """QQ 机器人绑定链接与绑定码。"""
+
+    url: Optional[str] = None
+    """带参分享链接，用于生成扫码二维码；已绑定用户再次获取时可能为空。"""
+    bindCode: Optional[str] = None
+    """绑定码。已是好友时扫码收不到加好友事件，需私聊发送该码；认领 QQ 群也用此码。"""
+    expireSeconds: Optional[int] = None
+    """有效期秒数，默认 300。"""
+    botAppId: Optional[str] = None
+    """为当前用户分配的官方机器人 appId。"""
+    botName: Optional[str] = None
+    botAvatar: Optional[str] = None
+
+
+@dataclass
+class QqBotInfo:
+    """QQ 机器人详情。"""
+
+    botId: Optional[str] = None
+    username: Optional[str] = None
+    avatar: Optional[str] = None
+    appId: Optional[str] = None
+    shareUrl: Optional[str] = None
+    """官方分享链接，可用于拉机器人进群。"""
+
+
+@dataclass
+class QqBotBindInfo:
+    """QQ 机器人绑定状态。"""
+
+    isBind: Optional[int] = None
+    """0-未绑定，1-已绑定。"""
+    receiveStatus: Optional[int] = None
+    """1-可接收，0-用户已关闭单聊接收。"""
+    createTime: Optional[str] = None
+    botInfo: Optional[QqBotInfo] = None
+
+
+@dataclass
+class QqGroupItem:
+    """机器人已加入的 QQ 群。"""
+
+    id: Optional[int] = None
+    """群编号；新增渠道配置时作为 ``qqGroupId`` 使用。"""
+    groupOpenId: Optional[str] = None
+    groupRemark: Optional[str] = None
+    status: Optional[int] = None
+    """1-在群，2-群消息接收关闭。"""
+    groupName: Optional[str] = None
+    """群名称，接口未授权时为空。"""
+    groupFingerMemo: Optional[str] = None
+    groupClassText: Optional[str] = None
+    groupTags: Optional[List[str]] = None
+    groupMemberNum: Optional[int] = None
+    createTime: Optional[str] = None
+
+
+@dataclass
+class QqBotItem:
+    """QQ 机器人渠道配置列表项。"""
+
+    id: Optional[int] = None
+    qqName: Optional[str] = None
+    qqCode: Optional[str] = None
+    """配置编码；发送消息时作为 ``option`` 传入。"""
+    sendType: Optional[int] = None
+    """2-发到 QQ 群。"""
+    qqGroupId: Optional[int] = None
+    groupRemark: Optional[str] = None
+    groupOpenId: Optional[str] = None
+    groupName: Optional[str] = None
+    updateTime: Optional[str] = None
+
+
+@dataclass
+class QqBotSaveRequest:
+    """新增/修改 QQ 机器人渠道配置请求。"""
+
+    id: Optional[int] = None
+    """修改时必填。"""
+    qqName: Optional[str] = None
+    """配置名称，必填，最多 64 个字符。"""
+    qqCode: Optional[str] = None
+    """配置编码，新增必填；仅支持字母、数字、下划线和中划线，创建后不可修改。"""
+    sendType: Optional[int] = None
+    """发送类型；留空时 SDK 自动填 2（发到 QQ 群）。"""
+    qqGroupId: Optional[int] = None
+    """QQ 群编号，必填，取自 ``group_list`` 返回的 ``id``。"""
+
+
+__all__ = [
+    "QqBotBindLink",
+    "QqBotInfo",
+    "QqBotBindInfo",
+    "QqGroupItem",
+    "QqBotItem",
+    "QqBotSaveRequest",
+]

{perk_pushplus_sdk-1.2.1 → perk_pushplus_sdk-1.2.2}/src/perk_pushplus/models/open_user.py

@@ -53,6 +53,7 @@ class SendCount:
     cpSendCount: Optional[int] = None
     webhookSendCount: Optional[int] = None
     mailSendCount: Optional[int] = None
+    qqBotSendCount: Optional[int] = None
 
 
 __all__ = ["VipInfo", "UserInfo", "UserLimitTime", "SendCount"]

{perk_pushplus_sdk-1.2.1 → perk_pushplus_sdk-1.2.2}/src/perk_pushplus_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: perk-pushplus-sdk
-Version: 1.2.1
+Version: 1.2.2
 Summary: pushplus(推送加) 官方接口的 Python SDK，覆盖消息发送接口与全部开放接口。
 Author: perk-net
 License: Apache-2.0
@@ -35,7 +35,7 @@ Requires-Dist: responses>=0.23; extra == "dev"
 [pushplus(推送加)](https://www.pushplus.plus) 官方接口的 Python SDK，覆盖 **消息接口** 与 **全部开放接口**。
 
 - **消息接口**（`/send`、`/batchSend`）：单渠道 + 多渠道发送，含 Builder API。
-- **开放接口**（`/api/open/...` 与 `/push/api/open/...`）：用户、消息、消息 token、群组、群组用户、好友、webhook、渠道、ClawBot、功能设置、预处理信息、图片服务、push 表单、push 文档、push 表格。
+- **开放接口**（`/api/open/...` 与 `/push/api/open/...`）：用户、消息、消息 token、群组、群组用户、好友、webhook、渠道、ClawBot、QQ 机器人、功能设置、预处理信息、图片服务、push 表单、push 文档、push 表格。
 - **AccessKey 自动管理**：缓存 + 过期前自动刷新；`code=401` 自动刷新并重试一次。
 - **本地限流守卫**：命中 `code=900` 后按 token 短路同 token 后续发送，避免被服务端长期封禁。
 - **回调解析**：`message_complate`、`add_topic_user`、`add_friend` 三类回调统一解析。
@@ -168,6 +168,20 @@ topic_blacklist = client.topic_user.blacklist_list(TopicUserListQuery.of(1, 20,
 # webhook 渠道
 webhooks = client.webhook.list()
 
+# QQ 机器人：绑定 -> 认领群 -> 建配置 -> 发到群
+from perk_pushplus import QqBotSaveRequest
+link = client.qq_bot.get_bind_link()   # link.url 生成二维码，或私聊发送 link.bindCode
+bind = client.qq_bot.bot_info()        # bind.isBind == 1 表示已绑定
+qq_groups = client.qq_bot.group_list()
+client.qq_bot.add(QqBotSaveRequest(qqName="运维告警群", qqCode="ops-group", qqGroupId=qq_groups[0].id))
+client.send(SendRequest(
+    title="服务告警",
+    content="订单服务响应超时",
+    channel=Channel.QQ,
+    option="ops-group",  # 不传 option 则发给自己
+    template=Template.TXT,
+))
+
 # 设置
 client.setting.change_is_send(1)  # 启用发送
 

{perk_pushplus_sdk-1.2.1 → perk_pushplus_sdk-1.2.2}/src/perk_pushplus_sdk.egg-info/SOURCES.txt

@@ -25,6 +25,7 @@ src/perk_pushplus/api/message.py
 src/perk_pushplus/api/message_token.py
 src/perk_pushplus/api/open_message.py
 src/perk_pushplus/api/pre.py
+src/perk_pushplus/api/qqbot.py
 src/perk_pushplus/api/setting.py
 src/perk_pushplus/api/topic.py
 src/perk_pushplus/api/topic_user.py
@@ -42,6 +43,7 @@ src/perk_pushplus/models/open_friend.py
 src/perk_pushplus/models/open_image.py
 src/perk_pushplus/models/open_message.py
 src/perk_pushplus/models/open_pre.py
+src/perk_pushplus/models/open_qqbot.py
 src/perk_pushplus/models/open_setting.py
 src/perk_pushplus/models/open_token.py
 src/perk_pushplus/models/open_topic.py

{perk_pushplus_sdk-1.2.1 → perk_pushplus_sdk-1.2.2}/tests/test_open_api.py

@@ -292,3 +292,57 @@ def test_excel_import():
 
     imported = client.excel.import_excel(b"xlsx", "销售日报.xlsx")
     assert imported.docCode == "Sh3xY7kP"
+
+
+def test_qq_bot_bind_and_group_config():
+    req = ScriptedRequester()
+    req.push(
+        "/api/open/qqBot/getBindLink",
+        200,
+        _ok({"url": "https://qun.qq.com/qunpro/robot/share?robot_appid=1", "bindCode": "A1B2C3", "expireSeconds": 300}),
+    )
+    req.push(
+        "/api/open/qqBot/botInfo",
+        200,
+        _ok({"isBind": 1, "receiveStatus": 1, "botInfo": {"appId": "1", "username": "pushplus"}}),
+    )
+    req.push(
+        "/api/open/qqBot/groupList",
+        200,
+        _ok([{"id": 9, "groupOpenId": "OPEN-1", "status": 1, "groupName": "运维告警群", "groupTags": ["运维"]}]),
+    )
+    req.push("/api/open/qqBot/add", 200, _ok(None))
+    req.push(
+        "/api/open/qqBot/list",
+        200,
+        _ok({"pageNum": 1, "pageSize": 20, "total": 1, "pages": 1, "list": [{"id": 3, "qqCode": "ops-group", "sendType": 2, "qqGroupId": 9}]}),
+    )
+    req.push("/api/open/qqBot/delete", 200, _ok(None))
+    client = _build_client(req)
+
+    from perk_pushplus import QqBotSaveRequest
+
+    link = client.qq_bot.get_bind_link(refresh=True)
+    assert link.bindCode == "A1B2C3"
+    assert "refresh=true" in next(c for c in req.calls if "getBindLink" in c[1])[1]
+
+    bind = client.qq_bot.bot_info()
+    assert bind.isBind == 1
+    assert bind.botInfo is not None and bind.botInfo.username == "pushplus"
+
+    groups = client.qq_bot.group_list()
+    assert groups[0].id == 9
+    assert groups[0].groupTags == ["运维"]
+
+    client.qq_bot.add(QqBotSaveRequest(qqName="运维告警群", qqCode="ops-group", qqGroupId=9))
+    add_call = next(c for c in req.calls if "/api/open/qqBot/add" in c[1])
+    assert add_call[2]["access-key"] == "ak-1"
+    assert json.loads(add_call[3])["sendType"] == 2
+
+    page = client.qq_bot.list()
+    assert page.list[0].qqCode == "ops-group"
+
+    client.qq_bot.delete(3)
+    delete_call = next(c for c in req.calls if "/api/open/qqBot/delete" in c[1])
+    assert delete_call[0] == "DELETE"
+    assert "id=3" in delete_call[1]