qqbotsdk-base-py 2.0.0__tar.gz → 2.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/PKG-INFO +1 -1
  2. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/pyproject.toml +1 -1
  3. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/pyproject.toml.orig +1 -1
  4. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/src/qqbotsdk/api/core.py +99 -1
  5. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/src/qqbotsdk/ws/intents.py +6 -0
  6. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/README.md +0 -0
  7. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/src/qqbotsdk/api/agent.md +0 -0
  8. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/src/qqbotsdk/api/auth.py +0 -0
  9. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/src/qqbotsdk/api/gateway.py +0 -0
  10. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/src/qqbotsdk/errors.py +0 -0
  11. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/src/qqbotsdk/model/agent.md +0 -0
  12. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/src/qqbotsdk/model/core.py +0 -0
  13. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/src/qqbotsdk/model/sub/messages.py +0 -0
  14. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/src/qqbotsdk/model/sub/upload.py +0 -0
  15. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/src/qqbotsdk/ws/__init__.py +0 -0
  16. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/src/qqbotsdk/ws/agent.md +0 -0
  17. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/src/qqbotsdk/ws/client.py +0 -0
  18. {qqbotsdk_base_py-2.0.0 → qqbotsdk_base_py-2.1.0}/src/qqbotsdk/ws/payload.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: qqbotsdk-base-py
3
- Version: 2.0.0
3
+ Version: 2.1.0
4
4
  Summary: QQ 官方机器人 SDK 基座包:模型基类、共享消息模型与 HTTP 会话
5
5
  Author: snowy-yang
6
6
  Author-email: snowy-yang <102860110+snowy-yang@users.noreply.github.com>
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "qqbotsdk-base-py"
3
- version = "2.0.0"
3
+ version = "2.1.0"
4
4
  description = "QQ 官方机器人 SDK 基座包:模型基类、共享消息模型与 HTTP 会话"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.12"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "qqbotsdk-base-py"
3
- version = "2.0.0"
3
+ version = "2.1.0"
4
4
  description = "QQ 官方机器人 SDK 基座包:模型基类、共享消息模型与 HTTP 会话"
5
5
  readme = "README.md"
6
6
  authors = [
@@ -22,6 +22,7 @@ import asyncio
22
22
  import os
23
23
  import random
24
24
  from collections.abc import Awaitable, Callable, Generator, Mapping
25
+ from contextlib import contextmanager
25
26
  from types import TracebackType
26
27
  from typing import Any, Final, cast
27
28
  from urllib.parse import urlparse
@@ -434,7 +435,100 @@ class QQBotSession:
434
435
  await self.close()
435
436
 
436
437
 
437
- session = QQBotSession()
438
+ # 默认会话: 未注入时所有请求都走它
439
+ _DEFAULT_SESSION: Final = QQBotSession()
440
+
441
+ # 当前注入的会话; None 表示用默认会话
442
+ _injected_session: QQBotSession | None = None
443
+
444
+
445
+ class _SessionRouter:
446
+ """``session`` 的转发实现: 每次调用都重新解析当前生效的会话.
447
+
448
+ 模块级 ``session`` 必须是**稳定的转发层**而不是会话本身: 业务模块的
449
+ ``from ... import session`` 在 import 期就把名字绑死了, 如果 ``session`` 是会话
450
+ 实例, 注入就要去改各模块的模块属性(打补丁), 测起来很脆. 这里让名字稳定不变,
451
+ 真正的会话由 :func:`set_session` 换, 所有 import 过它的模块自动看到新会话.
452
+ """
453
+
454
+ __slots__ = ()
455
+
456
+ def __getattr__(self, name: str) -> Any:
457
+ """未显式定义的属性一律转发到当前生效的会话.
458
+
459
+ 注意这是「转发引用」: ``session.some_attr = x`` 只会写到本代理上, 不会写到
460
+ 真正的会话. 需要改内部状态请用 :func:`get_session` 拿真实会话.
461
+ """
462
+ return getattr(resolve_session(), name)
463
+
464
+ def _ensure(self) -> ClientSession:
465
+ """确保当前会话的连接池已创建, 返回底层 ``ClientSession``."""
466
+ session = resolve_session()
467
+ return session._ensure() # pyright: ignore[reportPrivateUsage]
468
+
469
+ async def __aenter__(self) -> ClientSession:
470
+ return self._ensure()
471
+
472
+ async def __aexit__(self, *_exc: object) -> None:
473
+ return None
474
+
475
+
476
+ def resolve_session() -> QQBotSession:
477
+ """返回当前生效的会话对象: 注入了就用注入的, 否则用模块级默认单例."""
478
+ return _DEFAULT_SESSION if _injected_session is None else _injected_session
479
+
480
+
481
+ def get_session() -> QQBotSession:
482
+ """返回当前生效的会话对象, 供需要改内部状态(例如测试)的场景使用."""
483
+ return resolve_session()
484
+
485
+
486
+ @contextmanager
487
+ def use_session(session: QQBotSession) -> Generator[QQBotSession]:
488
+ """在 ``with`` 块内让所有 ``qqbotsdk`` 请求改走指定会话, 退出后还原.
489
+
490
+ 用于单测: 构造一个指向本地假服务端的会话传进来, 业务模块与 ``ctx.api`` 都会
491
+ 自动用它, 不会误连真实域名.
492
+
493
+ Args:
494
+ session: 要临时启用的会话对象.
495
+
496
+ Yields:
497
+ 传入的会话对象本身.
498
+ """
499
+ set_session(session)
500
+ try:
501
+ yield session
502
+ finally:
503
+ reset_session()
504
+
505
+
506
+ def set_session(session: QQBotSession | None) -> None:
507
+ """替换全局会话(传 None 表示恢复默认单例).
508
+
509
+ Args:
510
+ session: 新的会话对象, 或 None.
511
+
512
+ Notes:
513
+ 被替换掉的会话不会被自动关闭, 调用方自己决定何时 ``await it.close()``.
514
+ """
515
+ global _injected_session
516
+ _injected_session = session
517
+
518
+
519
+ def reset_session() -> None:
520
+ """恢复默认单例, 供测试夹具收尾使用(不关闭任何会话)."""
521
+ global _injected_session
522
+ _injected_session = None
523
+
524
+
525
+ session = _SessionRouter()
526
+ """当前生效会话的转发入口, 用法与 ``aiohttp.ClientSession`` 一致.
527
+
528
+ ``from qqbotsdk.api.core import session`` 拿到的就是这个对象; 它本身不持有连接,
529
+ 真正的会话由 :func:`get_session` / :func:`set_session` 决定, 因此测试里可以整体
530
+ 换成假服务端上的会话.
531
+ """
438
532
 
439
533
  __all__ = [
440
534
  "BASE_URL",
@@ -445,5 +539,9 @@ __all__ = [
445
539
  "RETRY_TOTAL_WAIT_SECONDS",
446
540
  "QQBotResponse",
447
541
  "QQBotSession",
542
+ "get_session",
543
+ "reset_session",
448
544
  "session",
545
+ "set_session",
546
+ "use_session",
449
547
  ]
@@ -6,6 +6,11 @@ Intents 是一个位掩码, 在 Identify 时上报给网关, 声明机器人希
6
6
  from qqbotsdk.ws import Intents
7
7
 
8
8
  intents = Intents.GROUP_AND_C2C_EVENT | Intents.PUBLIC_GUILD_MESSAGES
9
+
10
+ ``GROUP_MEMBER_EVENT`` (1<<24) 没有出现在官方「事件订阅与通知」的总表里, 但
11
+ ``GROUP_MEMBER_ADD`` 与 ``GROUP_JOIN_REQUEST`` 两篇事件文档标注的 intent 都是它;
12
+ 官方 Python SDK (botpy) 至今也没有这一位. 需要群成员进出 / 入群申请事件时显式
13
+ 订阅它.
9
14
  """
10
15
 
11
16
  from enum import IntFlag
@@ -20,6 +25,7 @@ class Intents(IntFlag):
20
25
  GUILD_MESSAGES = 1 << 9
21
26
  GUILD_MESSAGE_REACTIONS = 1 << 10
22
27
  DIRECT_MESSAGE = 1 << 12
28
+ GROUP_MEMBER_EVENT = 1 << 24
23
29
  GROUP_AND_C2C_EVENT = 1 << 25
24
30
  INTERACTION = 1 << 26
25
31
  MESSAGE_AUDIT = 1 << 27