♻️ reorganize class and add bot hook di

nonebot/__init__.py

@@ -122,16 +122,16 @@ def get_asgi() -> Any:
 
 
 def get_bot(self_id: Optional[str] = None) -> Bot:
-    """获取一个连接到 NoneBot 的 {ref}`nonebot.adapters._bot.Bot` 对象。
+    """获取一个连接到 NoneBot 的 {ref}`nonebot.adapters.Bot` 对象。
 
     当提供 `self_id` 时，此函数是 `get_bots()[self_id]` 的简写；
-    当不提供时，返回一个 {ref}`nonebot.adapters._bot.Bot`。
+    当不提供时，返回一个 {ref}`nonebot.adapters.Bot`。
 
     参数:
-        self_id: 用来识别 {ref}`nonebot.adapters._bot.Bot` 的 {ref}`nonebot.adapters._bot.Bot.self_id` 属性
+        self_id: 用来识别 {ref}`nonebot.adapters.Bot` 的 {ref}`nonebot.adapters.Bot.self_id` 属性
 
     返回:
-        {ref}`nonebot.adapters._bot.Bot` 对象
+        {ref}`nonebot.adapters.Bot` 对象
 
     异常:
         KeyError: 对应 self_id 的 Bot 不存在
@@ -156,10 +156,10 @@ def get_bot(self_id: Optional[str] = None) -> Bot:
 
 
 def get_bots() -> Dict[str, Bot]:
-    """获取所有连接到 NoneBot 的 {ref}`nonebot.adapters._bot.Bot` 对象。
+    """获取所有连接到 NoneBot 的 {ref}`nonebot.adapters.Bot` 对象。
 
     返回:
-        一个以 {ref}`nonebot.adapters._bot.Bot.self_id` 为键，{ref}`nonebot.adapters._bot.Bot` 对象为值的字典
+        一个以 {ref}`nonebot.adapters.Bot.self_id` 为键，{ref}`nonebot.adapters.Bot` 对象为值的字典
 
     异常:
         ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init <nonebot.init>` 尚未调用)
@@ -258,7 +258,6 @@ def run(*args: Any, **kwargs: Any) -> None:
     get_driver().run(*args, **kwargs)
 
 
-import nonebot.params as params
 from nonebot.plugin import on as on
 from nonebot.plugin import export as export
 from nonebot.plugin import require as require
@@ -283,3 +282,5 @@ from nonebot.plugin import on_shell_command as on_shell_command
 from nonebot.plugin import get_loaded_plugins as get_loaded_plugins
 from nonebot.plugin import load_builtin_plugin as load_builtin_plugin
 from nonebot.plugin import load_builtin_plugins as load_builtin_plugins
+
+__autodoc__ = {"internal": False}

nonebot/adapters/__init__.py

@@ -22,17 +22,18 @@ except ImportError:
 except Exception:
     pass
 
-from ._bot import Bot as Bot
+from nonebot.internal.bot import Bot as Bot
-from ._event import Event as Event
+from nonebot.internal.event import Event as Event
-from ._adapter import Adapter as Adapter
+from nonebot.internal.adapter import Adapter as Adapter
-from ._message import Message as Message
+from nonebot.internal.message import Message as Message
-from ._message import MessageSegment as MessageSegment
+from nonebot.internal.message import MessageSegment as MessageSegment
-from ._template import MessageTemplate as MessageTemplate
+from nonebot.internal.template import MessageTemplate as MessageTemplate
 
 __autodoc__ = {
-    "_bot": True,
+    "Bot": True,
-    "_event": True,
+    "Event": True,
-    "_adapter": True,
+    "Adapter": True,
-    "_message": True,
+    "Message": True,
-    "_template": True,
+    "MessageSegment": True,
+    "MessageTemplate": True,
 }

nonebot/drivers/__init__.py

@@ -7,259 +7,32 @@ FrontMatter:
     description: nonebot.drivers 模块
 """
 
-import abc
+from nonebot.internal.model import URL as URL
-import asyncio
+from nonebot.internal.driver import Driver as Driver
-from dataclasses import dataclass
+from nonebot.internal.model import Cookies as Cookies
-from contextlib import asynccontextmanager
+from nonebot.internal.model import Request as Request
-from typing import (
+from nonebot.internal.model import Response as Response
-    TYPE_CHECKING,
+from nonebot.internal.model import WebSocket as WebSocket
-    Any,
+from nonebot.internal.model import HTTPVersion as HTTPVersion
-    Set,
+from nonebot.internal.driver import ForwardMixin as ForwardMixin
-    Dict,
+from nonebot.internal.driver import ForwardDriver as ForwardDriver
-    Type,
+from nonebot.internal.driver import ReverseDriver as ReverseDriver
-    Callable,
+from nonebot.internal.driver import combine_driver as combine_driver
-    Awaitable,
+from nonebot.internal.model import HTTPServerSetup as HTTPServerSetup
-    AsyncGenerator,
+from nonebot.internal.model import WebSocketServerSetup as WebSocketServerSetup
-)
 
-from nonebot.log import logger
+__autodoc__ = {
-from nonebot.utils import escape_tag
+    "URL": True,
-from nonebot.config import Env, Config
+    "Driver": True,
-from nonebot.typing import T_BotConnectionHook, T_BotDisconnectionHook
+    "Cookies": True,
-
+    "Request": True,
-from ._model import URL as URL
+    "Response": True,
-from ._model import Request as Request
+    "WebSocket": True,
-from ._model import Response as Response
+    "HTTPVersion": True,
-from ._model import WebSocket as WebSocket
+    "ForwardMixin": True,
-from ._model import HTTPVersion as HTTPVersion
+    "ForwardDriver": True,
-
+    "ReverseDriver": True,
-if TYPE_CHECKING:
+    "combine_driver": True,
-    from nonebot.adapters import Bot, Adapter
+    "HTTPServerSetup": True,
-
+    "WebSocketServerSetup": True,
-
+}
-class Driver(abc.ABC):
-    """Driver 基类。
-
-    参数:
-        env: 包含环境信息的 Env 对象
-        config: 包含配置信息的 Config 对象
-    """
-
-    _adapters: Dict[str, "Adapter"] = {}
-    """已注册的适配器列表"""
-    _bot_connection_hook: Set[T_BotConnectionHook] = set()
-    """Bot 连接建立时执行的函数"""
-    _bot_disconnection_hook: Set[T_BotDisconnectionHook] = set()
-    """Bot 连接断开时执行的函数"""
-
-    def __init__(self, env: Env, config: Config):
-        self.env: str = env.environment
-        """环境名称"""
-        self.config: Config = config
-        """全局配置对象"""
-        self._clients: Dict[str, "Bot"] = {}
-
-    @property
-    def bots(self) -> Dict[str, "Bot"]:
-        """获取当前所有已连接的 Bot"""
-        return self._clients
-
-    def register_adapter(self, adapter: Type["Adapter"], **kwargs) -> None:
-        """注册一个协议适配器
-
-        参数:
-            adapter: 适配器类
-            kwargs: 其他传递给适配器的参数
-        """
-        name = adapter.get_name()
-        if name in self._adapters:
-            logger.opt(colors=True).debug(
-                f'Adapter "<y>{escape_tag(name)}</y>" already exists'
-            )
-            return
-        self._adapters[name] = adapter(self, **kwargs)
-        logger.opt(colors=True).debug(
-            f'Succeeded to load adapter "<y>{escape_tag(name)}</y>"'
-        )
-
-    @property
-    @abc.abstractmethod
-    def type(self) -> str:
-        """驱动类型名称"""
-        raise NotImplementedError
-
-    @property
-    @abc.abstractmethod
-    def logger(self):
-        """驱动专属 logger 日志记录器"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def run(self, *args, **kwargs):
-        """
-        启动驱动框架
-        """
-        logger.opt(colors=True).debug(
-            f"<g>Loaded adapters: {escape_tag(', '.join(self._adapters))}</g>"
-        )
-
-    @abc.abstractmethod
-    def on_startup(self, func: Callable) -> Callable:
-        """注册一个在驱动器启动时执行的函数"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def on_shutdown(self, func: Callable) -> Callable:
-        """注册一个在驱动器停止时执行的函数"""
-        raise NotImplementedError
-
-    def on_bot_connect(self, func: T_BotConnectionHook) -> T_BotConnectionHook:
-        """装饰一个函数使他在 bot 连接成功时执行。
-
-        钩子函数参数:
-
-        - bot: 当前连接上的 Bot 对象
-        """
-        self._bot_connection_hook.add(func)
-        return func
-
-    def on_bot_disconnect(self, func: T_BotDisconnectionHook) -> T_BotDisconnectionHook:
-        """装饰一个函数使他在 bot 连接断开时执行。
-
-        钩子函数参数:
-
-        - bot: 当前连接上的 Bot 对象
-        """
-        self._bot_disconnection_hook.add(func)
-        return func
-
-    def _bot_connect(self, bot: "Bot") -> None:
-        """在连接成功后，调用该函数来注册 bot 对象"""
-        if bot.self_id in self._clients:
-            raise RuntimeError(f"Duplicate bot connection with id {bot.self_id}")
-        self._clients[bot.self_id] = bot
-
-        async def _run_hook(bot: "Bot") -> None:
-            coros = list(map(lambda x: x(bot), self._bot_connection_hook))
-            if coros:
-                try:
-                    await asyncio.gather(*coros)
-                except Exception as e:
-                    logger.opt(colors=True, exception=e).error(
-                        "<r><bg #f8bbd0>Error when running WebSocketConnection hook. "
-                        "Running cancelled!</bg #f8bbd0></r>"
-                    )
-
-        asyncio.create_task(_run_hook(bot))
-
-    def _bot_disconnect(self, bot: "Bot") -> None:
-        """在连接断开后，调用该函数来注销 bot 对象"""
-        if bot.self_id in self._clients:
-            del self._clients[bot.self_id]
-
-        async def _run_hook(bot: "Bot") -> None:
-            coros = list(map(lambda x: x(bot), self._bot_disconnection_hook))
-            if coros:
-                try:
-                    await asyncio.gather(*coros)
-                except Exception as e:
-                    logger.opt(colors=True, exception=e).error(
-                        "<r><bg #f8bbd0>Error when running WebSocketDisConnection hook. "
-                        "Running cancelled!</bg #f8bbd0></r>"
-                    )
-
-        asyncio.create_task(_run_hook(bot))
-
-
-class ForwardMixin(abc.ABC):
-    """客户端混入基类。"""
-
-    @property
-    @abc.abstractmethod
-    def type(self) -> str:
-        """客户端驱动类型名称"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    async def request(self, setup: Request) -> Response:
-        """发送一个 HTTP 请求"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    @asynccontextmanager
-    async def websocket(self, setup: Request) -> AsyncGenerator[WebSocket, None]:
-        """发起一个 WebSocket 连接"""
-        raise NotImplementedError
-        yield  # used for static type checking's generator detection
-
-
-class ForwardDriver(Driver, ForwardMixin):
-    """客户端基类。将客户端框架封装，以满足适配器使用。"""
-
-
-class ReverseDriver(Driver):
-    """服务端基类。将后端框架封装，以满足适配器使用。"""
-
-    @property
-    @abc.abstractmethod
-    def server_app(self) -> Any:
-        """驱动 APP 对象"""
-        raise NotImplementedError
-
-    @property
-    @abc.abstractmethod
-    def asgi(self) -> Any:
-        """驱动 ASGI 对象"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def setup_http_server(self, setup: "HTTPServerSetup") -> None:
-        """设置一个 HTTP 服务器路由配置"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def setup_websocket_server(self, setup: "WebSocketServerSetup") -> None:
-        """设置一个 WebSocket 服务器路由配置"""
-        raise NotImplementedError
-
-
-def combine_driver(driver: Type[Driver], *mixins: Type[ForwardMixin]) -> Type[Driver]:
-    """将一个驱动器和多个混入类合并。"""
-    # check first
-    assert issubclass(driver, Driver), "`driver` must be subclass of Driver"
-    assert all(
-        map(lambda m: issubclass(m, ForwardMixin), mixins)
-    ), "`mixins` must be subclass of ForwardMixin"
-
-    if not mixins:
-        return driver
-
-    class CombinedDriver(*mixins, driver, ForwardDriver):  # type: ignore
-        @property
-        def type(self) -> str:
-            return (
-                driver.type.__get__(self)
-                + "+"
-                + "+".join(map(lambda x: x.type.__get__(self), mixins))
-            )
-
-    return CombinedDriver
-
-
-@dataclass
-class HTTPServerSetup:
-    """HTTP 服务器路由配置。"""
-
-    path: URL  # path should not be absolute, check it by URL.is_absolute() == False
-    method: str
-    name: str
-    handle_func: Callable[[Request], Awaitable[Response]]
-
-
-@dataclass
-class WebSocketServerSetup:
-    """WebSocket 服务器路由配置。"""
-
-    path: URL  # path should not be absolute, check it by URL.is_absolute() == False
-    name: str
-    handle_func: Callable[[WebSocket], Awaitable[Any]]

nonebot/drivers/fastapi.py

@@ -27,7 +27,7 @@ from nonebot.drivers import Request as BaseRequest
 from nonebot.drivers import WebSocket as BaseWebSocket
 from nonebot.drivers import ReverseDriver, HTTPServerSetup, WebSocketServerSetup
 
-from ._model import FileTypes
+from ..internal.model import FileTypes
 
 
 def catch_closed(func):

nonebot/drivers/quart.py

@@ -30,7 +30,7 @@ from nonebot.drivers import Request as BaseRequest
 from nonebot.drivers import WebSocket as BaseWebSocket
 from nonebot.drivers import ReverseDriver, HTTPServerSetup, WebSocketServerSetup
 
-from ._model import FileTypes
+from ..internal.model import FileTypes
 
 try:
     from quart import request as _request

nonebot/exception.py

@@ -202,7 +202,7 @@ class AdapterException(NoneBotException):
 class NoLogException(AdapterException):
     """指示 NoneBot 对当前 `Event` 进行处理但不显示 Log 信息。
 
-    可在 {ref}`nonebot.adapters._event.Event.get_log_string` 时抛出
+    可在 {ref}`nonebot.adapters.Event.get_log_string` 时抛出
     """
 
 

nonebot/internal/adapter.py

@@ -1,8 +1,3 @@
-"""
-FrontMatter:
-    sidebar_position: 1
-    description: nonebot.adapters._adapter 模块
-"""
 import abc
 from contextlib import asynccontextmanager
 from typing import Any, Dict, AsyncGenerator
@@ -19,7 +14,7 @@ from nonebot.drivers import (
     WebSocketServerSetup,
 )
 
-from ._bot import Bot
+from .bot import Bot
 
 
 class Adapter(abc.ABC):
@@ -36,7 +31,7 @@ class Adapter(abc.ABC):
         self.driver: Driver = driver
         """{ref}`nonebot.drivers.Driver` 实例"""
         self.bots: Dict[str, Bot] = {}
-        """本协议适配器已建立连接的 {ref}`nonebot.adapters._bot.Bot` 实例"""
+        """本协议适配器已建立连接的 {ref}`nonebot.adapters.Bot` 实例"""
 
     @classmethod
     @abc.abstractmethod
@@ -50,23 +45,23 @@ class Adapter(abc.ABC):
         return self.driver.config
 
     def bot_connect(self, bot: Bot) -> None:
-        """告知 NoneBot 建立了一个新的 {ref}`nonebot.adapters._bot.Bot` 连接。
+        """告知 NoneBot 建立了一个新的 {ref}`nonebot.adapters.Bot` 连接。
 
-        当有新的 {ref}`nonebot.adapters._bot.Bot` 实例连接建立成功时调用。
+        当有新的 {ref}`nonebot.adapters.Bot` 实例连接建立成功时调用。
 
         参数:
-            bot: {ref}`nonebot.adapters._bot.Bot` 实例
+            bot: {ref}`nonebot.adapters.Bot` 实例
         """
         self.driver._bot_connect(bot)
         self.bots[bot.self_id] = bot
 
     def bot_disconnect(self, bot: Bot) -> None:
-        """告知 NoneBot {ref}`nonebot.adapters._bot.Bot` 连接已断开。
+        """告知 NoneBot {ref}`nonebot.adapters.Bot` 连接已断开。
 
-        当有 {ref}`nonebot.adapters._bot.Bot` 实例连接断开时调用。
+        当有 {ref}`nonebot.adapters.Bot` 实例连接断开时调用。
 
         参数:
-            bot: {ref}`nonebot.adapters._bot.Bot` 实例
+            bot: {ref}`nonebot.adapters.Bot` 实例
         """
         self.driver._bot_disconnect(bot)
         self.bots.pop(bot.self_id, None)

nonebot/internal/bot.py

@@ -1,8 +1,3 @@
-"""
-FrontMatter:
-    sidebar_position: 2
-    description: nonebot.adapters._bot 模块
-"""
 import abc
 import asyncio
 from functools import partial
@@ -15,9 +10,9 @@ from nonebot.exception import MockApiException
 from nonebot.typing import T_CalledAPIHook, T_CallingAPIHook
 
 if TYPE_CHECKING:
-    from ._event import Event
+    from .event import Event
-    from ._adapter import Adapter
+    from .adapter import Adapter
-    from ._message import Message, MessageSegment
+    from .message import Message, MessageSegment
 
 
 class _ApiCall(Protocol):

nonebot/internal/driver.py

@@ -0,0 +1,233 @@
+import abc
+import asyncio
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any, Set, Dict, Type, Callable, AsyncGenerator
+
+from nonebot.log import logger
+from nonebot.utils import escape_tag
+from nonebot.config import Env, Config
+from nonebot.dependencies import Dependent
+from nonebot.typing import T_BotConnectionHook, T_BotDisconnectionHook
+
+from .params import BotParam, DependParam, DefaultParam
+from .model import Request, Response, WebSocket, HTTPServerSetup, WebSocketServerSetup
+
+if TYPE_CHECKING:
+    from .bot import Bot
+    from .adapter import Adapter
+
+
+BOT_HOOK_PARAMS = [DependParam, BotParam, DefaultParam]
+
+
+class Driver(abc.ABC):
+    """Driver 基类。
+
+    参数:
+        env: 包含环境信息的 Env 对象
+        config: 包含配置信息的 Config 对象
+    """
+
+    _adapters: Dict[str, "Adapter"] = {}
+    """已注册的适配器列表"""
+    _bot_connection_hook: Set[Dependent[Any]] = set()
+    """Bot 连接建立时执行的函数"""
+    _bot_disconnection_hook: Set[Dependent[Any]] = set()
+    """Bot 连接断开时执行的函数"""
+
+    def __init__(self, env: Env, config: Config):
+        self.env: str = env.environment
+        """环境名称"""
+        self.config: Config = config
+        """全局配置对象"""
+        self._clients: Dict[str, "Bot"] = {}
+
+    @property
+    def bots(self) -> Dict[str, "Bot"]:
+        """获取当前所有已连接的 Bot"""
+        return self._clients
+
+    def register_adapter(self, adapter: Type["Adapter"], **kwargs) -> None:
+        """注册一个协议适配器
+
+        参数:
+            adapter: 适配器类
+            kwargs: 其他传递给适配器的参数
+        """
+        name = adapter.get_name()
+        if name in self._adapters:
+            logger.opt(colors=True).debug(
+                f'Adapter "<y>{escape_tag(name)}</y>" already exists'
+            )
+            return
+        self._adapters[name] = adapter(self, **kwargs)
+        logger.opt(colors=True).debug(
+            f'Succeeded to load adapter "<y>{escape_tag(name)}</y>"'
+        )
+
+    @property
+    @abc.abstractmethod
+    def type(self) -> str:
+        """驱动类型名称"""
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def logger(self):
+        """驱动专属 logger 日志记录器"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def run(self, *args, **kwargs):
+        """
+        启动驱动框架
+        """
+        logger.opt(colors=True).debug(
+            f"<g>Loaded adapters: {escape_tag(', '.join(self._adapters))}</g>"
+        )
+
+    @abc.abstractmethod
+    def on_startup(self, func: Callable) -> Callable:
+        """注册一个在驱动器启动时执行的函数"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def on_shutdown(self, func: Callable) -> Callable:
+        """注册一个在驱动器停止时执行的函数"""
+        raise NotImplementedError
+
+    def on_bot_connect(self, func: T_BotConnectionHook) -> T_BotConnectionHook:
+        """装饰一个函数使他在 bot 连接成功时执行。
+
+        钩子函数参数:
+
+        - bot: 当前连接上的 Bot 对象
+        """
+        self._bot_connection_hook.add(
+            Dependent[Any].parse(call=func, allow_types=BOT_HOOK_PARAMS)
+        )
+        return func
+
+    def on_bot_disconnect(self, func: T_BotDisconnectionHook) -> T_BotDisconnectionHook:
+        """装饰一个函数使他在 bot 连接断开时执行。
+
+        钩子函数参数:
+
+        - bot: 当前连接上的 Bot 对象
+        """
+        self._bot_disconnection_hook.add(
+            Dependent[Any].parse(call=func, allow_types=BOT_HOOK_PARAMS)
+        )
+        return func
+
+    def _bot_connect(self, bot: "Bot") -> None:
+        """在连接成功后，调用该函数来注册 bot 对象"""
+        if bot.self_id in self._clients:
+            raise RuntimeError(f"Duplicate bot connection with id {bot.self_id}")
+        self._clients[bot.self_id] = bot
+
+        async def _run_hook(bot: "Bot") -> None:
+            coros = list(map(lambda x: x(bot=bot), self._bot_connection_hook))
+            if coros:
+                try:
+                    await asyncio.gather(*coros)
+                except Exception as e:
+                    logger.opt(colors=True, exception=e).error(
+                        "<r><bg #f8bbd0>Error when running WebSocketConnection hook. "
+                        "Running cancelled!</bg #f8bbd0></r>"
+                    )
+
+        asyncio.create_task(_run_hook(bot))
+
+    def _bot_disconnect(self, bot: "Bot") -> None:
+        """在连接断开后，调用该函数来注销 bot 对象"""
+        if bot.self_id in self._clients:
+            del self._clients[bot.self_id]
+
+        async def _run_hook(bot: "Bot") -> None:
+            coros = list(map(lambda x: x(bot=bot), self._bot_disconnection_hook))
+            if coros:
+                try:
+                    await asyncio.gather(*coros)
+                except Exception as e:
+                    logger.opt(colors=True, exception=e).error(
+                        "<r><bg #f8bbd0>Error when running WebSocketDisConnection hook. "
+                        "Running cancelled!</bg #f8bbd0></r>"
+                    )
+
+        asyncio.create_task(_run_hook(bot))
+
+
+class ForwardMixin(abc.ABC):
+    """客户端混入基类。"""
+
+    @property
+    @abc.abstractmethod
+    def type(self) -> str:
+        """客户端驱动类型名称"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def request(self, setup: Request) -> Response:
+        """发送一个 HTTP 请求"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    @asynccontextmanager
+    async def websocket(self, setup: Request) -> AsyncGenerator[WebSocket, None]:
+        """发起一个 WebSocket 连接"""
+        raise NotImplementedError
+        yield  # used for static type checking's generator detection
+
+
+class ForwardDriver(Driver, ForwardMixin):
+    """客户端基类。将客户端框架封装，以满足适配器使用。"""
+
+
+class ReverseDriver(Driver):
+    """服务端基类。将后端框架封装，以满足适配器使用。"""
+
+    @property
+    @abc.abstractmethod
+    def server_app(self) -> Any:
+        """驱动 APP 对象"""
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def asgi(self) -> Any:
+        """驱动 ASGI 对象"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def setup_http_server(self, setup: "HTTPServerSetup") -> None:
+        """设置一个 HTTP 服务器路由配置"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def setup_websocket_server(self, setup: "WebSocketServerSetup") -> None:
+        """设置一个 WebSocket 服务器路由配置"""
+        raise NotImplementedError
+
+
+def combine_driver(driver: Type[Driver], *mixins: Type[ForwardMixin]) -> Type[Driver]:
+    """将一个驱动器和多个混入类合并。"""
+    # check first
+    assert issubclass(driver, Driver), "`driver` must be subclass of Driver"
+    assert all(
+        map(lambda m: issubclass(m, ForwardMixin), mixins)
+    ), "`mixins` must be subclass of ForwardMixin"
+
+    if not mixins:
+        return driver
+
+    class CombinedDriver(*mixins, driver, ForwardDriver):  # type: ignore
+        @property
+        def type(self) -> str:
+            return (
+                driver.type.__get__(self)
+                + "+"
+                + "+".join(map(lambda x: x.type.__get__(self), mixins))
+            )
+
+    return CombinedDriver

nonebot/internal/event.py

@@ -1,15 +1,10 @@
-"""
-FrontMatter:
-    sidebar_position: 3
-    description: nonebot.adapters._event 模块
-"""
 import abc
 
 from pydantic import BaseModel
 
 from nonebot.utils import DataclassEncoder
 
-from ._message import Message
+from .message import Message
 
 
 class Event(abc.ABC, BaseModel):

nonebot/internal/matcher.py

@@ -0,0 +1,724 @@
+from types import ModuleType
+from datetime import datetime
+from contextvars import ContextVar
+from collections import defaultdict
+from contextlib import AsyncExitStack
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    List,
+    Type,
+    Union,
+    TypeVar,
+    Callable,
+    NoReturn,
+    Optional,
+)
+
+from nonebot.log import logger
+from nonebot.dependencies import Dependent
+from nonebot.consts import (
+    ARG_KEY,
+    RECEIVE_KEY,
+    REJECT_TARGET,
+    LAST_RECEIVE_KEY,
+    REJECT_CACHE_TARGET,
+)
+from nonebot.typing import (
+    Any,
+    T_State,
+    T_Handler,
+    T_TypeUpdater,
+    T_DependencyCache,
+    T_PermissionUpdater,
+)
+from nonebot.exception import (
+    TypeMisMatch,
+    PausedException,
+    StopPropagation,
+    SkippedException,
+    FinishedException,
+    RejectedException,
+)
+
+from .bot import Bot
+from .rule import Rule
+from .event import Event
+from .template import MessageTemplate
+from .permission import USER, Permission
+from .message import Message, MessageSegment
+from .params import (
+    Depends,
+    ArgParam,
+    BotParam,
+    EventParam,
+    StateParam,
+    DependParam,
+    DefaultParam,
+    MatcherParam,
+)
+
+if TYPE_CHECKING:
+    from nonebot.plugin import Plugin
+
+T = TypeVar("T")
+
+matchers: Dict[int, List[Type["Matcher"]]] = defaultdict(list)
+"""用于存储当前所有的事件响应器"""
+current_bot: ContextVar[Bot] = ContextVar("current_bot")
+current_event: ContextVar[Event] = ContextVar("current_event")
+current_matcher: ContextVar["Matcher"] = ContextVar("current_matcher")
+current_handler: ContextVar[Dependent] = ContextVar("current_handler")
+
+
+class MatcherMeta(type):
+    if TYPE_CHECKING:
+        module: Optional[str]
+        plugin_name: Optional[str]
+        module_name: Optional[str]
+        module_prefix: Optional[str]
+        type: str
+        rule: Rule
+        permission: Permission
+        handlers: List[T_Handler]
+        priority: int
+        block: bool
+        temp: bool
+        expire_time: Optional[datetime]
+
+    def __repr__(self) -> str:
+        return (
+            f"<Matcher from {self.module_name or 'unknown'}, "
+            f"type={self.type}, priority={self.priority}, "
+            f"temp={self.temp}>"
+        )
+
+    def __str__(self) -> str:
+        return repr(self)
+
+
+class Matcher(metaclass=MatcherMeta):
+    """事件响应器类"""
+
+    plugin: Optional["Plugin"] = None
+    """事件响应器所在插件"""
+    module: Optional[ModuleType] = None
+    """事件响应器所在插件模块"""
+    plugin_name: Optional[str] = None
+    """事件响应器所在插件名"""
+    module_name: Optional[str] = None
+    """事件响应器所在点分割插件模块路径"""
+
+    type: str = ""
+    """事件响应器类型"""
+    rule: Rule = Rule()
+    """事件响应器匹配规则"""
+    permission: Permission = Permission()
+    """事件响应器触发权限"""
+    handlers: List[Dependent[Any]] = []
+    """事件响应器拥有的事件处理函数列表"""
+    priority: int = 1
+    """事件响应器优先级"""
+    block: bool = False
+    """事件响应器是否阻止事件传播"""
+    temp: bool = False
+    """事件响应器是否为临时"""
+    expire_time: Optional[datetime] = None
+    """事件响应器过期时间点"""
+
+    _default_state: T_State = {}
+    """事件响应器默认状态"""
+
+    _default_type_updater: Optional[Dependent[str]] = None
+    """事件响应器类型更新函数"""
+    _default_permission_updater: Optional[Dependent[Permission]] = None
+    """事件响应器权限更新函数"""
+
+    HANDLER_PARAM_TYPES = [
+        DependParam,
+        BotParam,
+        EventParam,
+        StateParam,
+        ArgParam,
+        MatcherParam,
+        DefaultParam,
+    ]
+
+    def __init__(self):
+        self.handlers = self.handlers.copy()
+        self.state = self._default_state.copy()
+
+    def __repr__(self) -> str:
+        return (
+            f"<Matcher from {self.module_name or 'unknown'}, type={self.type}, "
+            f"priority={self.priority}, temp={self.temp}>"
+        )
+
+    def __str__(self) -> str:
+        return repr(self)
+
+    @classmethod
+    def new(
+        cls,
+        type_: str = "",
+        rule: Optional[Rule] = None,
+        permission: Optional[Permission] = None,
+        handlers: Optional[List[Union[T_Handler, Dependent[Any]]]] = None,
+        temp: bool = False,
+        priority: int = 1,
+        block: bool = False,
+        *,
+        plugin: Optional["Plugin"] = None,
+        module: Optional[ModuleType] = None,
+        expire_time: Optional[datetime] = None,
+        default_state: Optional[T_State] = None,
+        default_type_updater: Optional[Union[T_TypeUpdater, Dependent[str]]] = None,
+        default_permission_updater: Optional[
+            Union[T_PermissionUpdater, Dependent[Permission]]
+        ] = None,
+    ) -> Type["Matcher"]:
+        """
+        创建一个新的事件响应器，并存储至 `matchers <#matchers>`_
+
+        参数:
+            type_: 事件响应器类型，与 `event.get_type()` 一致时触发，空字符串表示任意
+            rule: 匹配规则
+            permission: 权限
+            handlers: 事件处理函数列表
+            temp: 是否为临时事件响应器，即触发一次后删除
+            priority: 响应优先级
+            block: 是否阻止事件向更低优先级的响应器传播
+            plugin: 事件响应器所在插件
+            module: 事件响应器所在模块
+            default_state: 默认状态 `state`
+            expire_time: 事件响应器最终有效时间点，过时即被删除
+
+        返回:
+            Type[Matcher]: 新的事件响应器类
+        """
+        NewMatcher = type(
+            "Matcher",
+            (Matcher,),
+            {
+                "plugin": plugin,
+                "module": module,
+                "plugin_name": plugin and plugin.name,
+                "module_name": module and module.__name__,
+                "type": type_,
+                "rule": rule or Rule(),
+                "permission": permission or Permission(),
+                "handlers": [
+                    handler
+                    if isinstance(handler, Dependent)
+                    else Dependent[Any].parse(
+                        call=handler, allow_types=cls.HANDLER_PARAM_TYPES
+                    )
+                    for handler in handlers
+                ]
+                if handlers
+                else [],
+                "temp": temp,
+                "expire_time": expire_time,
+                "priority": priority,
+                "block": block,
+                "_default_state": default_state or {},
+                "_default_type_updater": (
+                    default_type_updater
+                    if isinstance(default_type_updater, Dependent)
+                    else default_type_updater
+                    and Dependent[str].parse(
+                        call=default_type_updater, allow_types=cls.HANDLER_PARAM_TYPES
+                    )
+                ),
+                "_default_permission_updater": (
+                    default_permission_updater
+                    if isinstance(default_permission_updater, Dependent)
+                    else default_permission_updater
+                    and Dependent[Permission].parse(
+                        call=default_permission_updater,
+                        allow_types=cls.HANDLER_PARAM_TYPES,
+                    )
+                ),
+            },
+        )
+
+        logger.trace(f"Define new matcher {NewMatcher}")
+
+        matchers[priority].append(NewMatcher)
+
+        return NewMatcher
+
+    @classmethod
+    async def check_perm(
+        cls,
+        bot: Bot,
+        event: Event,
+        stack: Optional[AsyncExitStack] = None,
+        dependency_cache: Optional[T_DependencyCache] = None,
+    ) -> bool:
+        """检查是否满足触发权限
+
+        参数:
+            bot: Bot 对象
+            event: 上报事件
+            stack: 异步上下文栈
+            dependency_cache: 依赖缓存
+
+        返回:
+            是否满足权限
+        """
+        event_type = event.get_type()
+        return event_type == (cls.type or event_type) and await cls.permission(
+            bot, event, stack, dependency_cache
+        )
+
+    @classmethod
+    async def check_rule(
+        cls,
+        bot: Bot,
+        event: Event,
+        state: T_State,
+        stack: Optional[AsyncExitStack] = None,
+        dependency_cache: Optional[T_DependencyCache] = None,
+    ) -> bool:
+        """检查是否满足匹配规则
+
+        参数:
+            bot: Bot 对象
+            event: 上报事件
+            state: 当前状态
+            stack: 异步上下文栈
+            dependency_cache: 依赖缓存
+
+        返回:
+            是否满足匹配规则
+        """
+        event_type = event.get_type()
+        return event_type == (cls.type or event_type) and await cls.rule(
+            bot, event, state, stack, dependency_cache
+        )
+
+    @classmethod
+    def type_updater(cls, func: T_TypeUpdater) -> T_TypeUpdater:
+        """装饰一个函数来更改当前事件响应器的默认响应事件类型更新函数
+
+        参数:
+            func: 响应事件类型更新函数
+        """
+        cls._default_type_updater = Dependent[str].parse(
+            call=func, allow_types=cls.HANDLER_PARAM_TYPES
+        )
+        return func
+
+    @classmethod
+    def permission_updater(cls, func: T_PermissionUpdater) -> T_PermissionUpdater:
+        """装饰一个函数来更改当前事件响应器的默认会话权限更新函数
+
+        参数:
+            func: 会话权限更新函数
+        """
+        cls._default_permission_updater = Dependent[Permission].parse(
+            call=func, allow_types=cls.HANDLER_PARAM_TYPES
+        )
+        return func
+
+    @classmethod
+    def append_handler(
+        cls, handler: T_Handler, parameterless: Optional[List[Any]] = None
+    ) -> Dependent[Any]:
+        handler_ = Dependent[Any].parse(
+            call=handler,
+            parameterless=parameterless,
+            allow_types=cls.HANDLER_PARAM_TYPES,
+        )
+        cls.handlers.append(handler_)
+        return handler_
+
+    @classmethod
+    def handle(
+        cls, parameterless: Optional[List[Any]] = None
+    ) -> Callable[[T_Handler], T_Handler]:
+        """装饰一个函数来向事件响应器直接添加一个处理函数
+
+        参数:
+            parameterless: 非参数类型依赖列表
+        """
+
+        def _decorator(func: T_Handler) -> T_Handler:
+            cls.append_handler(func, parameterless=parameterless)
+            return func
+
+        return _decorator
+
+    @classmethod
+    def receive(
+        cls, id: str = "", parameterless: Optional[List[Any]] = None
+    ) -> Callable[[T_Handler], T_Handler]:
+        """装饰一个函数来指示 NoneBot 在接收用户新的一条消息后继续运行该函数
+
+        参数:
+            id: 消息 ID
+            parameterless: 非参数类型依赖列表
+        """
+
+        async def _receive(event: Event, matcher: "Matcher") -> Union[None, NoReturn]:
+            matcher.set_target(RECEIVE_KEY.format(id=id))
+            if matcher.get_target() == RECEIVE_KEY.format(id=id):
+                matcher.set_receive(id, event)
+                return
+            if matcher.get_receive(id, ...) is not ...:
+                return
+            await matcher.reject()
+
+        _parameterless = [Depends(_receive), *(parameterless or [])]
+
+        def _decorator(func: T_Handler) -> T_Handler:
+
+            if cls.handlers and cls.handlers[-1].call is func:
+                func_handler = cls.handlers[-1]
+                for depend in reversed(_parameterless):
+                    func_handler.prepend_parameterless(depend)
+            else:
+                cls.append_handler(func, parameterless=_parameterless)
+
+            return func
+
+        return _decorator
+
+    @classmethod
+    def got(
+        cls,
+        key: str,
+        prompt: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
+        parameterless: Optional[List[Any]] = None,
+    ) -> Callable[[T_Handler], T_Handler]:
+        """装饰一个函数来指示 NoneBot 获取一个参数 `key`
+
+        当要获取的 `key` 不存在时接收用户新的一条消息再运行该函数，如果 `key` 已存在则直接继续运行
+
+        参数:
+            key: 参数名
+            prompt: 在参数不存在时向用户发送的消息
+            parameterless: 非参数类型依赖列表
+        """
+
+        async def _key_getter(event: Event, matcher: "Matcher"):
+            matcher.set_target(ARG_KEY.format(key=key))
+            if matcher.get_target() == ARG_KEY.format(key=key):
+                matcher.set_arg(key, event.get_message())
+                return
+            if matcher.get_arg(key, ...) is not ...:
+                return
+            await matcher.reject(prompt)
+
+        _parameterless = [
+            Depends(_key_getter),
+            *(parameterless or []),
+        ]
+
+        def _decorator(func: T_Handler) -> T_Handler:
+
+            if cls.handlers and cls.handlers[-1].call is func:
+                func_handler = cls.handlers[-1]
+                for depend in reversed(_parameterless):
+                    func_handler.prepend_parameterless(depend)
+            else:
+                cls.append_handler(func, parameterless=_parameterless)
+
+            return func
+
+        return _decorator
+
+    @classmethod
+    async def send(
+        cls,
+        message: Union[str, Message, MessageSegment, MessageTemplate],
+        **kwargs: Any,
+    ) -> Any:
+        """发送一条消息给当前交互用户
+
+        参数:
+            message: 消息内容
+            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
+        """
+        bot = current_bot.get()
+        event = current_event.get()
+        state = current_matcher.get().state
+        if isinstance(message, MessageTemplate):
+            _message = message.format(**state)
+        else:
+            _message = message
+        return await bot.send(event=event, message=_message, **kwargs)
+
+    @classmethod
+    async def finish(
+        cls,
+        message: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
+        **kwargs,
+    ) -> NoReturn:
+        """发送一条消息给当前交互用户并结束当前事件响应器
+
+        参数:
+            message: 消息内容
+            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
+        """
+        if message is not None:
+            await cls.send(message, **kwargs)
+        raise FinishedException
+
+    @classmethod
+    async def pause(
+        cls,
+        prompt: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
+        **kwargs,
+    ) -> NoReturn:
+        """发送一条消息给当前交互用户并暂停事件响应器，在接收用户新的一条消息后继续下一个处理函数
+
+        参数:
+            prompt: 消息内容
+            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
+        """
+        if prompt is not None:
+            await cls.send(prompt, **kwargs)
+        raise PausedException
+
+    @classmethod
+    async def reject(
+        cls,
+        prompt: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
+        **kwargs,
+    ) -> NoReturn:
+        """最近使用 `got` / `receive` 接收的消息不符合预期，
+        发送一条消息给当前交互用户并将当前事件处理流程中断在当前位置，在接收用户新的一个事件后从头开始执行当前处理函数
+
+        参数:
+            prompt: 消息内容
+            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
+        """
+        if prompt is not None:
+            await cls.send(prompt, **kwargs)
+        raise RejectedException
+
+    @classmethod
+    async def reject_arg(
+        cls,
+        key: str,
+        prompt: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
+        **kwargs,
+    ) -> NoReturn:
+        """最近使用 `got` 接收的消息不符合预期，
+        发送一条消息给当前交互用户并将当前事件处理流程中断在当前位置，在接收用户新的一条消息后从头开始执行当前处理函数
+
+        参数:
+            key: 参数名
+            prompt: 消息内容
+            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
+        """
+        matcher = current_matcher.get()
+        matcher.set_target(ARG_KEY.format(key=key))
+        if prompt is not None:
+            await cls.send(prompt, **kwargs)
+        raise RejectedException
+
+    @classmethod
+    async def reject_receive(
+        cls,
+        id: str = "",
+        prompt: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
+        **kwargs,
+    ) -> NoReturn:
+        """最近使用 `receive` 接收的消息不符合预期，
+        发送一条消息给当前交互用户并将当前事件处理流程中断在当前位置，在接收用户新的一个事件后从头开始执行当前处理函数
+
+        参数:
+            id: 消息 id
+            prompt: 消息内容
+            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
+        """
+        matcher = current_matcher.get()
+        matcher.set_target(RECEIVE_KEY.format(id=id))
+        if prompt is not None:
+            await cls.send(prompt, **kwargs)
+        raise RejectedException
+
+    @classmethod
+    def skip(cls) -> NoReturn:
+        """跳过当前事件处理函数，继续下一个处理函数
+
+        通常在事件处理函数的依赖中使用。
+        """
+        raise SkippedException
+
+    def get_receive(self, id: str, default: T = None) -> Union[Event, T]:
+        """获取一个 `receive` 事件
+
+        如果没有找到对应的事件，返回 `default` 值
+        """
+        return self.state.get(RECEIVE_KEY.format(id=id), default)
+
+    def set_receive(self, id: str, event: Event) -> None:
+        """设置一个 `receive` 事件"""
+        self.state[RECEIVE_KEY.format(id=id)] = event
+        self.state[LAST_RECEIVE_KEY] = event
+
+    def get_last_receive(self, default: T = None) -> Union[Event, T]:
+        """获取最近一次 `receive` 事件
+
+        如果没有事件，返回 `default` 值
+        """
+        return self.state.get(LAST_RECEIVE_KEY, default)
+
+    def get_arg(self, key: str, default: T = None) -> Union[Message, T]:
+        """获取一个 `got` 消息
+
+        如果没有找到对应的消息，返回 `default` 值
+        """
+        return self.state.get(ARG_KEY.format(key=key), default)
+
+    def set_arg(self, key: str, message: Message) -> None:
+        """设置一个 `got` 消息"""
+        self.state[ARG_KEY.format(key=key)] = message
+
+    def set_target(self, target: str, cache: bool = True) -> None:
+        if cache:
+            self.state[REJECT_CACHE_TARGET] = target
+        else:
+            self.state[REJECT_TARGET] = target
+
+    def get_target(self, default: T = None) -> Union[str, T]:
+        return self.state.get(REJECT_TARGET, default)
+
+    def stop_propagation(self):
+        """阻止事件传播"""
+        self.block = True
+
+    async def update_type(self, bot: Bot, event: Event) -> str:
+        updater = self.__class__._default_type_updater
+        if not updater:
+            return "message"
+        return await updater(bot=bot, event=event, state=self.state, matcher=self)
+
+    async def update_permission(self, bot: Bot, event: Event) -> Permission:
+        updater = self.__class__._default_permission_updater
+        if not updater:
+            return USER(event.get_session_id(), perm=self.permission)
+        return await updater(bot=bot, event=event, state=self.state, matcher=self)
+
+    async def resolve_reject(self):
+        handler = current_handler.get()
+        self.handlers.insert(0, handler)
+        if REJECT_CACHE_TARGET in self.state:
+            self.state[REJECT_TARGET] = self.state[REJECT_CACHE_TARGET]
+
+    async def simple_run(
+        self,
+        bot: Bot,
+        event: Event,
+        state: T_State,
+        stack: Optional[AsyncExitStack] = None,
+        dependency_cache: Optional[T_DependencyCache] = None,
+    ):
+        logger.trace(
+            f"Matcher {self} run with incoming args: "
+            f"bot={bot}, event={event}, state={state}"
+        )
+        b_t = current_bot.set(bot)
+        e_t = current_event.set(event)
+        m_t = current_matcher.set(self)
+        try:
+            # Refresh preprocess state
+            self.state.update(state)
+
+            while self.handlers:
+                handler = self.handlers.pop(0)
+                current_handler.set(handler)
+                logger.debug(f"Running handler {handler}")
+                try:
+                    await handler(
+                        matcher=self,
+                        bot=bot,
+                        event=event,
+                        state=self.state,
+                        stack=stack,
+                        dependency_cache=dependency_cache,
+                    )
+                except TypeMisMatch as e:
+                    logger.debug(
+                        f"Handler {handler} param {e.param.name} value {e.value} "
+                        f"mismatch type {e.param._type_display()}, skipped"
+                    )
+                except SkippedException as e:
+                    logger.debug(f"Handler {handler} skipped")
+        except StopPropagation:
+            self.block = True
+        finally:
+            logger.info(f"Matcher {self} running complete")
+            current_bot.reset(b_t)
+            current_event.reset(e_t)
+            current_matcher.reset(m_t)
+
+    # 运行handlers
+    async def run(
+        self,
+        bot: Bot,
+        event: Event,
+        state: T_State,
+        stack: Optional[AsyncExitStack] = None,
+        dependency_cache: Optional[T_DependencyCache] = None,
+    ):
+        try:
+            await self.simple_run(bot, event, state, stack, dependency_cache)
+
+        except RejectedException:
+            await self.resolve_reject()
+            type_ = await self.update_type(bot, event)
+            permission = await self.update_permission(bot, event)
+
+            Matcher.new(
+                type_,
+                Rule(),
+                permission,
+                self.handlers,
+                temp=True,
+                priority=0,
+                block=True,
+                plugin=self.plugin,
+                module=self.module,
+                expire_time=datetime.now() + bot.config.session_expire_timeout,
+                default_state=self.state,
+                default_type_updater=self.__class__._default_type_updater,
+                default_permission_updater=self.__class__._default_permission_updater,
+            )
+        except PausedException:
+            type_ = await self.update_type(bot, event)
+            permission = await self.update_permission(bot, event)
+
+            Matcher.new(
+                type_,
+                Rule(),
+                permission,
+                self.handlers,
+                temp=True,
+                priority=0,
+                block=True,
+                plugin=self.plugin,
+                module=self.module,
+                expire_time=datetime.now() + bot.config.session_expire_timeout,
+                default_state=self.state,
+                default_type_updater=self.__class__._default_type_updater,
+                default_permission_updater=self.__class__._default_permission_updater,
+            )
+        except FinishedException:
+            pass
+
+
+__autodoc__ = {
+    "MatcherMeta": False,
+    "Matcher.get_target": False,
+    "Matcher.set_target": False,
+    "Matcher.update_type": False,
+    "Matcher.update_permission": False,
+    "Matcher.resolve_reject": False,
+    "Matcher.simple_run": False,
+}

nonebot/internal/message.py

@@ -1,8 +1,3 @@
-"""
-FrontMatter:
-    sidebar_position: 4
-    description: nonebot.adapters._message 模块
-"""
 import abc
 from copy import deepcopy
 from dataclasses import field, asdict, dataclass
@@ -22,7 +17,7 @@ from typing import (
 
 from pydantic import parse_obj_as
 
-from ._template import MessageTemplate
+from .template import MessageTemplate
 
 T = TypeVar("T")
 TMS = TypeVar("TMS", bound="MessageSegment")

nonebot/internal/model.py

@@ -1,5 +1,6 @@
 import abc
 from enum import Enum
+from dataclasses import dataclass
 from http.cookiejar import Cookie, CookieJar
 from typing import (
     IO,
@@ -9,8 +10,10 @@ from typing import (
     Tuple,
     Union,
     Mapping,
+    Callable,
     Iterator,
     Optional,
+    Awaitable,
     MutableMapping,
 )
 
@@ -314,3 +317,22 @@ class Cookies(MutableMapping):
         )
 
         return f"<Cookies [{cookies_repr}]>"
+
+
+@dataclass
+class HTTPServerSetup:
+    """HTTP 服务器路由配置。"""
+
+    path: URL  # path should not be absolute, check it by URL.is_absolute() == False
+    method: str
+    name: str
+    handle_func: Callable[[Request], Awaitable[Response]]
+
+
+@dataclass
+class WebSocketServerSetup:
+    """WebSocket 服务器路由配置。"""
+
+    path: URL  # path should not be absolute, check it by URL.is_absolute() == False
+    name: str
+    handle_func: Callable[[WebSocket], Awaitable[Any]]

nonebot/internal/params.py

@@ -0,0 +1,378 @@
+import asyncio
+import inspect
+import warnings
+from typing_extensions import Literal
+from typing import TYPE_CHECKING, Any, Callable, Optional, cast
+from contextlib import AsyncExitStack, contextmanager, asynccontextmanager
+
+from pydantic.fields import Required, Undefined, ModelField
+
+from nonebot.log import logger
+from nonebot.exception import TypeMisMatch
+from nonebot.dependencies.utils import check_field_type
+from nonebot.dependencies import Param, Dependent, CustomConfig
+from nonebot.typing import T_State, T_Handler, T_DependencyCache
+from nonebot.utils import (
+    get_name,
+    run_sync,
+    is_gen_callable,
+    run_sync_ctx_manager,
+    is_async_gen_callable,
+    is_coroutine_callable,
+    generic_check_issubclass,
+)
+
+if TYPE_CHECKING:
+    from nonebot.matcher import Matcher
+    from nonebot.adapters import Bot, Event
+
+
+class DependsInner:
+    def __init__(
+        self,
+        dependency: Optional[T_Handler] = None,
+        *,
+        use_cache: bool = True,
+    ) -> None:
+        self.dependency = dependency
+        self.use_cache = use_cache
+
+    def __repr__(self) -> str:
+        dep = get_name(self.dependency)
+        cache = "" if self.use_cache else ", use_cache=False"
+        return f"{self.__class__.__name__}({dep}{cache})"
+
+
+def Depends(
+    dependency: Optional[T_Handler] = None,
+    *,
+    use_cache: bool = True,
+) -> Any:
+    """子依赖装饰器
+
+    参数:
+        dependency: 依赖函数。默认为参数的类型注释。
+        use_cache: 是否使用缓存。默认为 `True`。
+
+    用法:
+        ```python
+        def depend_func() -> Any:
+            return ...
+
+        def depend_gen_func():
+            try:
+                yield ...
+            finally:
+                ...
+
+        async def handler(param_name: Any = Depends(depend_func), gen: Any = Depends(depend_gen_func)):
+            ...
+        ```
+    """
+    return DependsInner(dependency, use_cache=use_cache)
+
+
+class DependParam(Param):
+    """子依赖参数"""
+
+    @classmethod
+    def _check_param(
+        cls,
+        dependent: Dependent,
+        name: str,
+        param: inspect.Parameter,
+    ) -> Optional["DependParam"]:
+        if isinstance(param.default, DependsInner):
+            dependency: T_Handler
+            if param.default.dependency is None:
+                assert param.annotation is not param.empty, "Dependency cannot be empty"
+                dependency = param.annotation
+            else:
+                dependency = param.default.dependency
+            sub_dependent = Dependent[Any].parse(
+                call=dependency,
+                allow_types=dependent.allow_types,
+            )
+            dependent.pre_checkers.extend(sub_dependent.pre_checkers)
+            sub_dependent.pre_checkers.clear()
+            return cls(
+                Required, use_cache=param.default.use_cache, dependent=sub_dependent
+            )
+
+    @classmethod
+    def _check_parameterless(
+        cls, dependent: "Dependent", value: Any
+    ) -> Optional["Param"]:
+        if isinstance(value, DependsInner):
+            assert value.dependency, "Dependency cannot be empty"
+            dependent = Dependent[Any].parse(
+                call=value.dependency, allow_types=dependent.allow_types
+            )
+            return cls(Required, use_cache=value.use_cache, dependent=dependent)
+
+    async def _solve(
+        self,
+        stack: Optional[AsyncExitStack] = None,
+        dependency_cache: Optional[T_DependencyCache] = None,
+        **kwargs: Any,
+    ) -> Any:
+        use_cache: bool = self.extra["use_cache"]
+        dependency_cache = {} if dependency_cache is None else dependency_cache
+
+        sub_dependent: Dependent = self.extra["dependent"]
+        sub_dependent.call = cast(Callable[..., Any], sub_dependent.call)
+        call = sub_dependent.call
+
+        # solve sub dependency with current cache
+        sub_values = await sub_dependent.solve(
+            stack=stack,
+            dependency_cache=dependency_cache,
+            **kwargs,
+        )
+
+        # run dependency function
+        task: asyncio.Task[Any]
+        if use_cache and call in dependency_cache:
+            solved = await dependency_cache[call]
+        elif is_gen_callable(call) or is_async_gen_callable(call):
+            assert isinstance(
+                stack, AsyncExitStack
+            ), "Generator dependency should be called in context"
+            if is_gen_callable(call):
+                cm = run_sync_ctx_manager(contextmanager(call)(**sub_values))
+            else:
+                cm = asynccontextmanager(call)(**sub_values)
+            task = asyncio.create_task(stack.enter_async_context(cm))
+            dependency_cache[call] = task
+            solved = await task
+        elif is_coroutine_callable(call):
+            task = asyncio.create_task(call(**sub_values))
+            dependency_cache[call] = task
+            solved = await task
+        else:
+            task = asyncio.create_task(run_sync(call)(**sub_values))
+            dependency_cache[call] = task
+            solved = await task
+
+        return solved
+
+
+class _BotChecker(Param):
+    async def _solve(self, bot: "Bot", **kwargs: Any) -> Any:
+        field: ModelField = self.extra["field"]
+        try:
+            return check_field_type(field, bot)
+        except TypeMisMatch:
+            logger.debug(
+                f"Bot type {type(bot)} not match "
+                f"annotation {field._type_display()}, ignored"
+            )
+            raise
+
+
+class BotParam(Param):
+    """{ref}`nonebot.adapters.Bot` 参数"""
+
+    @classmethod
+    def _check_param(
+        cls, dependent: Dependent, name: str, param: inspect.Parameter
+    ) -> Optional["BotParam"]:
+        from nonebot.adapters import Bot
+
+        if param.default == param.empty:
+            if generic_check_issubclass(param.annotation, Bot):
+                if param.annotation is not Bot:
+                    dependent.pre_checkers.append(
+                        _BotChecker(
+                            Required,
+                            field=ModelField(
+                                name=name,
+                                type_=param.annotation,
+                                class_validators=None,
+                                model_config=CustomConfig,
+                                default=None,
+                                required=True,
+                            ),
+                        )
+                    )
+                return cls(Required)
+            elif param.annotation == param.empty and name == "bot":
+                return cls(Required)
+
+    async def _solve(self, bot: "Bot", **kwargs: Any) -> Any:
+        return bot
+
+
+class _EventChecker(Param):
+    async def _solve(self, event: "Event", **kwargs: Any) -> Any:
+        field: ModelField = self.extra["field"]
+        try:
+            return check_field_type(field, event)
+        except TypeMisMatch:
+            logger.debug(
+                f"Event type {type(event)} not match "
+                f"annotation {field._type_display()}, ignored"
+            )
+            raise
+
+
+class EventParam(Param):
+    """{ref}`nonebot.adapters.Event` 参数"""
+
+    @classmethod
+    def _check_param(
+        cls, dependent: Dependent, name: str, param: inspect.Parameter
+    ) -> Optional["EventParam"]:
+        from nonebot.adapters import Event
+
+        if param.default == param.empty:
+            if generic_check_issubclass(param.annotation, Event):
+                if param.annotation is not Event:
+                    dependent.pre_checkers.append(
+                        _EventChecker(
+                            Required,
+                            field=ModelField(
+                                name=name,
+                                type_=param.annotation,
+                                class_validators=None,
+                                model_config=CustomConfig,
+                                default=None,
+                                required=True,
+                            ),
+                        )
+                    )
+                return cls(Required)
+            elif param.annotation == param.empty and name == "event":
+                return cls(Required)
+
+    async def _solve(self, event: "Event", **kwargs: Any) -> Any:
+        return event
+
+
+class StateInner(T_State):
+    ...
+
+
+def State() -> T_State:
+    """**Deprecated**: 事件处理状态参数，请直接使用 {ref}`nonebot.typing.T_State`"""
+    warnings.warn("State() is deprecated, use `T_State` instead", DeprecationWarning)
+    return StateInner()
+
+
+class StateParam(Param):
+    """事件处理状态参数"""
+
+    @classmethod
+    def _check_param(
+        cls, dependent: Dependent, name: str, param: inspect.Parameter
+    ) -> Optional["StateParam"]:
+        if isinstance(param.default, StateInner):
+            return cls(Required)
+        elif param.default == param.empty:
+            if param.annotation is T_State:
+                return cls(Required)
+            elif param.annotation == param.empty and name == "state":
+                return cls(Required)
+
+    async def _solve(self, state: T_State, **kwargs: Any) -> Any:
+        return state
+
+
+class MatcherParam(Param):
+    """事件响应器实例参数"""
+
+    @classmethod
+    def _check_param(
+        cls, dependent: Dependent, name: str, param: inspect.Parameter
+    ) -> Optional["MatcherParam"]:
+        from nonebot.matcher import Matcher
+
+        if generic_check_issubclass(param.annotation, Matcher) or (
+            param.annotation == param.empty and name == "matcher"
+        ):
+            return cls(Required)
+
+    async def _solve(self, matcher: "Matcher", **kwargs: Any) -> Any:
+        return matcher
+
+
+class ArgInner:
+    def __init__(
+        self, key: Optional[str], type: Literal["message", "str", "plaintext"]
+    ) -> None:
+        self.key = key
+        self.type = type
+
+
+def Arg(key: Optional[str] = None) -> Any:
+    """`got` 的 Arg 参数消息"""
+    return ArgInner(key, "message")
+
+
+def ArgStr(key: Optional[str] = None) -> str:
+    """`got` 的 Arg 参数消息文本"""
+    return ArgInner(key, "str")  # type: ignore
+
+
+def ArgPlainText(key: Optional[str] = None) -> str:
+    """`got` 的 Arg 参数消息纯文本"""
+    return ArgInner(key, "plaintext")  # type: ignore
+
+
+class ArgParam(Param):
+    """`got` 的 Arg 参数"""
+
+    @classmethod
+    def _check_param(
+        cls, dependent: Dependent, name: str, param: inspect.Parameter
+    ) -> Optional["ArgParam"]:
+        if isinstance(param.default, ArgInner):
+            return cls(Required, key=param.default.key or name, type=param.default.type)
+
+    async def _solve(self, matcher: "Matcher", **kwargs: Any) -> Any:
+        message = matcher.get_arg(self.extra["key"])
+        if message is None:
+            return message
+        if self.extra["type"] == "message":
+            return message
+        elif self.extra["type"] == "str":
+            return str(message)
+        else:
+            return message.extract_plain_text()
+
+
+class ExceptionParam(Param):
+    """`run_postprocessor` 的异常参数"""
+
+    @classmethod
+    def _check_param(
+        cls, dependent: Dependent, name: str, param: inspect.Parameter
+    ) -> Optional["ExceptionParam"]:
+        if generic_check_issubclass(param.annotation, Exception) or (
+            param.annotation == param.empty and name == "exception"
+        ):
+            return cls(Required)
+
+    async def _solve(self, exception: Optional[Exception] = None, **kwargs: Any) -> Any:
+        return exception
+
+
+class DefaultParam(Param):
+    """默认值参数"""
+
+    @classmethod
+    def _check_param(
+        cls, dependent: Dependent, name: str, param: inspect.Parameter
+    ) -> Optional["DefaultParam"]:
+        if param.default != param.empty:
+            return cls(param.default)
+
+    async def _solve(self, **kwargs: Any) -> Any:
+        return Undefined
+
+
+__autodoc__ = {
+    "DependsInner": False,
+    "StateInner": False,
+    "ArgInner": False,
+}

nonebot/internal/permission.py

@@ -0,0 +1,133 @@
+import asyncio
+from contextlib import AsyncExitStack
+from typing import Any, Set, Tuple, Union, NoReturn, Optional, Coroutine
+
+from nonebot.adapters import Bot, Event
+from nonebot.dependencies import Dependent
+from nonebot.exception import SkippedException
+from nonebot.typing import T_DependencyCache, T_PermissionChecker
+
+from .params import BotParam, EventParam, DependParam, DefaultParam
+
+
+async def _run_coro_with_catch(coro: Coroutine[Any, Any, Any]):
+    try:
+        return await coro
+    except SkippedException:
+        return False
+
+
+class Permission:
+    """{ref}`nonebot.matcher.Matcher` 权限类。
+
+    当事件传递时，在 {ref}`nonebot.matcher.Matcher` 运行前进行检查。
+
+    参数:
+        checkers: PermissionChecker
+
+    用法:
+        ```python
+        Permission(async_function) | sync_function
+        # 等价于
+        Permission(async_function, sync_function)
+        ```
+    """
+
+    __slots__ = ("checkers",)
+
+    HANDLER_PARAM_TYPES = [
+        DependParam,
+        BotParam,
+        EventParam,
+        DefaultParam,
+    ]
+
+    def __init__(self, *checkers: Union[T_PermissionChecker, Dependent[bool]]) -> None:
+        self.checkers: Set[Dependent[bool]] = set(
+            checker
+            if isinstance(checker, Dependent)
+            else Dependent[bool].parse(
+                call=checker, allow_types=self.HANDLER_PARAM_TYPES
+            )
+            for checker in checkers
+        )
+        """存储 `PermissionChecker`"""
+
+    async def __call__(
+        self,
+        bot: Bot,
+        event: Event,
+        stack: Optional[AsyncExitStack] = None,
+        dependency_cache: Optional[T_DependencyCache] = None,
+    ) -> bool:
+        """检查是否满足某个权限
+
+        参数:
+            bot: Bot 对象
+            event: Event 对象
+            stack: 异步上下文栈
+            dependency_cache: 依赖缓存
+        """
+        if not self.checkers:
+            return True
+        results = await asyncio.gather(
+            *(
+                _run_coro_with_catch(
+                    checker(
+                        bot=bot,
+                        event=event,
+                        stack=stack,
+                        dependency_cache=dependency_cache,
+                    )
+                )
+                for checker in self.checkers
+            ),
+        )
+        return any(results)
+
+    def __and__(self, other) -> NoReturn:
+        raise RuntimeError("And operation between Permissions is not allowed.")
+
+    def __or__(
+        self, other: Optional[Union["Permission", T_PermissionChecker]]
+    ) -> "Permission":
+        if other is None:
+            return self
+        elif isinstance(other, Permission):
+            return Permission(*self.checkers, *other.checkers)
+        else:
+            return Permission(*self.checkers, other)
+
+
+class User:
+    """检查当前事件是否属于指定会话
+
+    参数:
+        users: 会话 ID 元组
+        perm: 需同时满足的权限
+    """
+
+    __slots__ = ("users", "perm")
+
+    def __init__(
+        self, users: Tuple[str, ...], perm: Optional[Permission] = None
+    ) -> None:
+        self.users = users
+        self.perm = perm
+
+    async def __call__(self, bot: Bot, event: Event) -> bool:
+        return bool(
+            event.get_session_id() in self.users
+            and (self.perm is None or await self.perm(bot, event))
+        )
+
+
+def USER(*users: str, perm: Optional[Permission] = None):
+    """匹配当前事件属于指定会话
+
+    参数:
+        user: 会话白名单
+        perm: 需要同时满足的权限
+    """
+
+    return Permission(User(users, perm))

nonebot/internal/rule.py

@@ -0,0 +1,95 @@
+import asyncio
+from contextlib import AsyncExitStack
+from typing import Set, Union, NoReturn, Optional
+
+from nonebot.adapters import Bot, Event
+from nonebot.dependencies import Dependent
+from nonebot.exception import SkippedException
+from nonebot.typing import T_State, T_RuleChecker, T_DependencyCache
+
+from .params import BotParam, EventParam, StateParam, DependParam, DefaultParam
+
+
+class Rule:
+    """{ref}`nonebot.matcher.Matcher` 规则类。
+
+    当事件传递时，在 {ref}`nonebot.matcher.Matcher` 运行前进行检查。
+
+    参数:
+        *checkers: RuleChecker
+
+    用法:
+        ```python
+        Rule(async_function) & sync_function
+        # 等价于
+        Rule(async_function, sync_function)
+        ```
+    """
+
+    __slots__ = ("checkers",)
+
+    HANDLER_PARAM_TYPES = [
+        DependParam,
+        BotParam,
+        EventParam,
+        StateParam,
+        DefaultParam,
+    ]
+
+    def __init__(self, *checkers: Union[T_RuleChecker, Dependent[bool]]) -> None:
+        self.checkers: Set[Dependent[bool]] = set(
+            checker
+            if isinstance(checker, Dependent)
+            else Dependent[bool].parse(
+                call=checker, allow_types=self.HANDLER_PARAM_TYPES
+            )
+            for checker in checkers
+        )
+        """存储 `RuleChecker`"""
+
+    async def __call__(
+        self,
+        bot: Bot,
+        event: Event,
+        state: T_State,
+        stack: Optional[AsyncExitStack] = None,
+        dependency_cache: Optional[T_DependencyCache] = None,
+    ) -> bool:
+        """检查是否符合所有规则
+
+        参数:
+            bot: Bot 对象
+            event: Event 对象
+            state: 当前 State
+            stack: 异步上下文栈
+            dependency_cache: 依赖缓存
+        """
+        if not self.checkers:
+            return True
+        try:
+            results = await asyncio.gather(
+                *(
+                    checker(
+                        bot=bot,
+                        event=event,
+                        state=state,
+                        stack=stack,
+                        dependency_cache=dependency_cache,
+                    )
+                    for checker in self.checkers
+                )
+            )
+        except SkippedException:
+            return False
+        return all(results)
+
+    def __and__(self, other: Optional[Union["Rule", T_RuleChecker]]) -> "Rule":
+        if other is None:
+            return self
+        elif isinstance(other, Rule):
+            return Rule(*self.checkers, *other.checkers)
+        else:
+            return Rule(*self.checkers, other)
+
+    def __or__(self, other) -> NoReturn:
+        raise RuntimeError("Or operation between rules is not allowed.")

nonebot/internal/template.py

@@ -1,8 +1,3 @@
-"""
-FrontMatter:
-    sidebar_position: 5
-    description: nonebot.adapters._template 模块
-"""
 import inspect
 import functools
 from string import Formatter
@@ -26,7 +21,7 @@ from typing import (
 )
 
 if TYPE_CHECKING:
-    from . import Message, MessageSegment
+    from .message import Message, MessageSegment
 
 TM = TypeVar("TM", bound="Message")
 TF = TypeVar("TF", str, "Message")

nonebot/matcher.py

@@ -5,697 +5,14 @@ FrontMatter:
     description: nonebot.matcher 模块
 """
 
-from types import ModuleType
+from nonebot.internal.matcher import Matcher as Matcher
-from datetime import datetime
+from nonebot.internal.matcher import matchers as matchers
-from contextvars import ContextVar
+from nonebot.internal.matcher import current_bot as current_bot
-from collections import defaultdict
+from nonebot.internal.matcher import current_event as current_event
-from contextlib import AsyncExitStack
+from nonebot.internal.matcher import current_handler as current_handler
-from typing import (
+from nonebot.internal.matcher import current_matcher as current_matcher
-    TYPE_CHECKING,
-    Any,
-    Dict,
-    List,
-    Type,
-    Union,
-    TypeVar,
-    Callable,
-    NoReturn,
-    Optional,
-)
-
-from nonebot import params
-from nonebot.rule import Rule
-from nonebot.log import logger
-from nonebot.dependencies import Dependent
-from nonebot.permission import USER, Permission
-from nonebot.adapters import Bot, Event, Message, MessageSegment, MessageTemplate
-from nonebot.consts import (
-    ARG_KEY,
-    RECEIVE_KEY,
-    REJECT_TARGET,
-    LAST_RECEIVE_KEY,
-    REJECT_CACHE_TARGET,
-)
-from nonebot.typing import (
-    Any,
-    T_State,
-    T_Handler,
-    T_TypeUpdater,
-    T_DependencyCache,
-    T_PermissionUpdater,
-)
-from nonebot.exception import (
-    TypeMisMatch,
-    PausedException,
-    StopPropagation,
-    SkippedException,
-    FinishedException,
-    RejectedException,
-)
-
-if TYPE_CHECKING:
-    from nonebot.plugin import Plugin
-
-T = TypeVar("T")
-
-matchers: Dict[int, List[Type["Matcher"]]] = defaultdict(list)
-"""用于存储当前所有的事件响应器"""
-current_bot: ContextVar[Bot] = ContextVar("current_bot")
-current_event: ContextVar[Event] = ContextVar("current_event")
-current_matcher: ContextVar["Matcher"] = ContextVar("current_matcher")
-current_handler: ContextVar[Dependent] = ContextVar("current_handler")
-
-
-class MatcherMeta(type):
-    if TYPE_CHECKING:
-        module: Optional[str]
-        plugin_name: Optional[str]
-        module_name: Optional[str]
-        module_prefix: Optional[str]
-        type: str
-        rule: Rule
-        permission: Permission
-        handlers: List[T_Handler]
-        priority: int
-        block: bool
-        temp: bool
-        expire_time: Optional[datetime]
-
-    def __repr__(self) -> str:
-        return (
-            f"<Matcher from {self.module_name or 'unknown'}, "
-            f"type={self.type}, priority={self.priority}, "
-            f"temp={self.temp}>"
-        )
-
-    def __str__(self) -> str:
-        return repr(self)
-
-
-class Matcher(metaclass=MatcherMeta):
-    """事件响应器类"""
-
-    plugin: Optional["Plugin"] = None
-    """事件响应器所在插件"""
-    module: Optional[ModuleType] = None
-    """事件响应器所在插件模块"""
-    plugin_name: Optional[str] = None
-    """事件响应器所在插件名"""
-    module_name: Optional[str] = None
-    """事件响应器所在点分割插件模块路径"""
-
-    type: str = ""
-    """事件响应器类型"""
-    rule: Rule = Rule()
-    """事件响应器匹配规则"""
-    permission: Permission = Permission()
-    """事件响应器触发权限"""
-    handlers: List[Dependent[Any]] = []
-    """事件响应器拥有的事件处理函数列表"""
-    priority: int = 1
-    """事件响应器优先级"""
-    block: bool = False
-    """事件响应器是否阻止事件传播"""
-    temp: bool = False
-    """事件响应器是否为临时"""
-    expire_time: Optional[datetime] = None
-    """事件响应器过期时间点"""
-
-    _default_state: T_State = {}
-    """事件响应器默认状态"""
-
-    _default_type_updater: Optional[Dependent[str]] = None
-    """事件响应器类型更新函数"""
-    _default_permission_updater: Optional[Dependent[Permission]] = None
-    """事件响应器权限更新函数"""
-
-    HANDLER_PARAM_TYPES = [
-        params.DependParam,
-        params.BotParam,
-        params.EventParam,
-        params.StateParam,
-        params.ArgParam,
-        params.MatcherParam,
-        params.DefaultParam,
-    ]
-
-    def __init__(self):
-        self.handlers = self.handlers.copy()
-        self.state = self._default_state.copy()
-
-    def __repr__(self) -> str:
-        return (
-            f"<Matcher from {self.module_name or 'unknown'}, type={self.type}, "
-            f"priority={self.priority}, temp={self.temp}>"
-        )
-
-    def __str__(self) -> str:
-        return repr(self)
-
-    @classmethod
-    def new(
-        cls,
-        type_: str = "",
-        rule: Optional[Rule] = None,
-        permission: Optional[Permission] = None,
-        handlers: Optional[List[Union[T_Handler, Dependent[Any]]]] = None,
-        temp: bool = False,
-        priority: int = 1,
-        block: bool = False,
-        *,
-        plugin: Optional["Plugin"] = None,
-        module: Optional[ModuleType] = None,
-        expire_time: Optional[datetime] = None,
-        default_state: Optional[T_State] = None,
-        default_type_updater: Optional[T_TypeUpdater] = None,
-        default_permission_updater: Optional[T_PermissionUpdater] = None,
-    ) -> Type["Matcher"]:
-        """
-        创建一个新的事件响应器，并存储至 `matchers <#matchers>`_
-
-        参数:
-            type_: 事件响应器类型，与 `event.get_type()` 一致时触发，空字符串表示任意
-            rule: 匹配规则
-            permission: 权限
-            handlers: 事件处理函数列表
-            temp: 是否为临时事件响应器，即触发一次后删除
-            priority: 响应优先级
-            block: 是否阻止事件向更低优先级的响应器传播
-            plugin: 事件响应器所在插件
-            module: 事件响应器所在模块
-            default_state: 默认状态 `state`
-            expire_time: 事件响应器最终有效时间点，过时即被删除
-
-        返回:
-            Type[Matcher]: 新的事件响应器类
-        """
-        NewMatcher = type(
-            "Matcher",
-            (Matcher,),
-            {
-                "plugin": plugin,
-                "module": module,
-                "plugin_name": plugin and plugin.name,
-                "module_name": module and module.__name__,
-                "type": type_,
-                "rule": rule or Rule(),
-                "permission": permission or Permission(),
-                "handlers": [
-                    handler
-                    if isinstance(handler, Dependent)
-                    else Dependent[Any].parse(
-                        call=handler, allow_types=cls.HANDLER_PARAM_TYPES
-                    )
-                    for handler in handlers
-                ]
-                if handlers
-                else [],
-                "temp": temp,
-                "expire_time": expire_time,
-                "priority": priority,
-                "block": block,
-                "_default_state": default_state or {},
-                "_default_type_updater": default_type_updater,
-                "_default_permission_updater": default_permission_updater,
-            },
-        )
-
-        logger.trace(f"Define new matcher {NewMatcher}")
-
-        matchers[priority].append(NewMatcher)
-
-        return NewMatcher
-
-    @classmethod
-    async def check_perm(
-        cls,
-        bot: Bot,
-        event: Event,
-        stack: Optional[AsyncExitStack] = None,
-        dependency_cache: Optional[T_DependencyCache] = None,
-    ) -> bool:
-        """检查是否满足触发权限
-
-        参数:
-            bot: Bot 对象
-            event: 上报事件
-            stack: 异步上下文栈
-            dependency_cache: 依赖缓存
-
-        返回:
-            是否满足权限
-        """
-        event_type = event.get_type()
-        return event_type == (cls.type or event_type) and await cls.permission(
-            bot, event, stack, dependency_cache
-        )
-
-    @classmethod
-    async def check_rule(
-        cls,
-        bot: Bot,
-        event: Event,
-        state: T_State,
-        stack: Optional[AsyncExitStack] = None,
-        dependency_cache: Optional[T_DependencyCache] = None,
-    ) -> bool:
-        """检查是否满足匹配规则
-
-        参数:
-            bot: Bot 对象
-            event: 上报事件
-            state: 当前状态
-            stack: 异步上下文栈
-            dependency_cache: 依赖缓存
-
-        返回:
-            是否满足匹配规则
-        """
-        event_type = event.get_type()
-        return event_type == (cls.type or event_type) and await cls.rule(
-            bot, event, state, stack, dependency_cache
-        )
-
-    @classmethod
-    def type_updater(cls, func: T_TypeUpdater) -> T_TypeUpdater:
-        """装饰一个函数来更改当前事件响应器的默认响应事件类型更新函数
-
-        参数:
-            func: 响应事件类型更新函数
-        """
-        cls._default_type_updater = Dependent[str].parse(
-            call=func, allow_types=cls.HANDLER_PARAM_TYPES
-        )
-        return func
-
-    @classmethod
-    def permission_updater(cls, func: T_PermissionUpdater) -> T_PermissionUpdater:
-        """装饰一个函数来更改当前事件响应器的默认会话权限更新函数
-
-        参数:
-            func: 会话权限更新函数
-        """
-        cls._default_permission_updater = Dependent[Permission].parse(
-            call=func, allow_types=cls.HANDLER_PARAM_TYPES
-        )
-        return func
-
-    @classmethod
-    def append_handler(
-        cls, handler: T_Handler, parameterless: Optional[List[Any]] = None
-    ) -> Dependent[Any]:
-        handler_ = Dependent[Any].parse(
-            call=handler,
-            parameterless=parameterless,
-            allow_types=cls.HANDLER_PARAM_TYPES,
-        )
-        cls.handlers.append(handler_)
-        return handler_
-
-    @classmethod
-    def handle(
-        cls, parameterless: Optional[List[Any]] = None
-    ) -> Callable[[T_Handler], T_Handler]:
-        """装饰一个函数来向事件响应器直接添加一个处理函数
-
-        参数:
-            parameterless: 非参数类型依赖列表
-        """
-
-        def _decorator(func: T_Handler) -> T_Handler:
-            cls.append_handler(func, parameterless=parameterless)
-            return func
-
-        return _decorator
-
-    @classmethod
-    def receive(
-        cls, id: str = "", parameterless: Optional[List[Any]] = None
-    ) -> Callable[[T_Handler], T_Handler]:
-        """装饰一个函数来指示 NoneBot 在接收用户新的一条消息后继续运行该函数
-
-        参数:
-            id: 消息 ID
-            parameterless: 非参数类型依赖列表
-        """
-
-        async def _receive(event: Event, matcher: "Matcher") -> Union[None, NoReturn]:
-            matcher.set_target(RECEIVE_KEY.format(id=id))
-            if matcher.get_target() == RECEIVE_KEY.format(id=id):
-                matcher.set_receive(id, event)
-                return
-            if matcher.get_receive(id, ...) is not ...:
-                return
-            await matcher.reject()
-
-        _parameterless = [params.Depends(_receive), *(parameterless or [])]
-
-        def _decorator(func: T_Handler) -> T_Handler:
-
-            if cls.handlers and cls.handlers[-1].call is func:
-                func_handler = cls.handlers[-1]
-                for depend in reversed(_parameterless):
-                    func_handler.prepend_parameterless(depend)
-            else:
-                cls.append_handler(func, parameterless=_parameterless)
-
-            return func
-
-        return _decorator
-
-    @classmethod
-    def got(
-        cls,
-        key: str,
-        prompt: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
-        parameterless: Optional[List[Any]] = None,
-    ) -> Callable[[T_Handler], T_Handler]:
-        """装饰一个函数来指示 NoneBot 获取一个参数 `key`
-
-        当要获取的 `key` 不存在时接收用户新的一条消息再运行该函数，如果 `key` 已存在则直接继续运行
-
-        参数:
-            key: 参数名
-            prompt: 在参数不存在时向用户发送的消息
-            parameterless: 非参数类型依赖列表
-        """
-
-        async def _key_getter(event: Event, matcher: "Matcher"):
-            matcher.set_target(ARG_KEY.format(key=key))
-            if matcher.get_target() == ARG_KEY.format(key=key):
-                matcher.set_arg(key, event.get_message())
-                return
-            if matcher.get_arg(key, ...) is not ...:
-                return
-            await matcher.reject(prompt)
-
-        _parameterless = [
-            params.Depends(_key_getter),
-            *(parameterless or []),
-        ]
-
-        def _decorator(func: T_Handler) -> T_Handler:
-
-            if cls.handlers and cls.handlers[-1].call is func:
-                func_handler = cls.handlers[-1]
-                for depend in reversed(_parameterless):
-                    func_handler.prepend_parameterless(depend)
-            else:
-                cls.append_handler(func, parameterless=_parameterless)
-
-            return func
-
-        return _decorator
-
-    @classmethod
-    async def send(
-        cls,
-        message: Union[str, Message, MessageSegment, MessageTemplate],
-        **kwargs: Any,
-    ) -> Any:
-        """发送一条消息给当前交互用户
-
-        参数:
-            message: 消息内容
-            kwargs: {ref}`nonebot.adapters._bot.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
-        """
-        bot = current_bot.get()
-        event = current_event.get()
-        state = current_matcher.get().state
-        if isinstance(message, MessageTemplate):
-            _message = message.format(**state)
-        else:
-            _message = message
-        return await bot.send(event=event, message=_message, **kwargs)
-
-    @classmethod
-    async def finish(
-        cls,
-        message: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
-        **kwargs,
-    ) -> NoReturn:
-        """发送一条消息给当前交互用户并结束当前事件响应器
-
-        参数:
-            message: 消息内容
-            kwargs: {ref}`nonebot.adapters._bot.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
-        """
-        if message is not None:
-            await cls.send(message, **kwargs)
-        raise FinishedException
-
-    @classmethod
-    async def pause(
-        cls,
-        prompt: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
-        **kwargs,
-    ) -> NoReturn:
-        """发送一条消息给当前交互用户并暂停事件响应器，在接收用户新的一条消息后继续下一个处理函数
-
-        参数:
-            prompt: 消息内容
-            kwargs: {ref}`nonebot.adapters._bot.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
-        """
-        if prompt is not None:
-            await cls.send(prompt, **kwargs)
-        raise PausedException
-
-    @classmethod
-    async def reject(
-        cls,
-        prompt: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
-        **kwargs,
-    ) -> NoReturn:
-        """最近使用 `got` / `receive` 接收的消息不符合预期，
-        发送一条消息给当前交互用户并将当前事件处理流程中断在当前位置，在接收用户新的一个事件后从头开始执行当前处理函数
-
-        参数:
-            prompt: 消息内容
-            kwargs: {ref}`nonebot.adapters._bot.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
-        """
-        if prompt is not None:
-            await cls.send(prompt, **kwargs)
-        raise RejectedException
-
-    @classmethod
-    async def reject_arg(
-        cls,
-        key: str,
-        prompt: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
-        **kwargs,
-    ) -> NoReturn:
-        """最近使用 `got` 接收的消息不符合预期，
-        发送一条消息给当前交互用户并将当前事件处理流程中断在当前位置，在接收用户新的一条消息后从头开始执行当前处理函数
-
-        参数:
-            key: 参数名
-            prompt: 消息内容
-            kwargs: {ref}`nonebot.adapters._bot.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
-        """
-        matcher = current_matcher.get()
-        matcher.set_target(ARG_KEY.format(key=key))
-        if prompt is not None:
-            await cls.send(prompt, **kwargs)
-        raise RejectedException
-
-    @classmethod
-    async def reject_receive(
-        cls,
-        id: str = "",
-        prompt: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
-        **kwargs,
-    ) -> NoReturn:
-        """最近使用 `receive` 接收的消息不符合预期，
-        发送一条消息给当前交互用户并将当前事件处理流程中断在当前位置，在接收用户新的一个事件后从头开始执行当前处理函数
-
-        参数:
-            id: 消息 id
-            prompt: 消息内容
-            kwargs: {ref}`nonebot.adapters._bot.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
-        """
-        matcher = current_matcher.get()
-        matcher.set_target(RECEIVE_KEY.format(id=id))
-        if prompt is not None:
-            await cls.send(prompt, **kwargs)
-        raise RejectedException
-
-    @classmethod
-    def skip(cls) -> NoReturn:
-        """跳过当前事件处理函数，继续下一个处理函数
-
-        通常在事件处理函数的依赖中使用。
-        """
-        raise SkippedException
-
-    def get_receive(self, id: str, default: T = None) -> Union[Event, T]:
-        """获取一个 `receive` 事件
-
-        如果没有找到对应的事件，返回 `default` 值
-        """
-        return self.state.get(RECEIVE_KEY.format(id=id), default)
-
-    def set_receive(self, id: str, event: Event) -> None:
-        """设置一个 `receive` 事件"""
-        self.state[RECEIVE_KEY.format(id=id)] = event
-        self.state[LAST_RECEIVE_KEY] = event
-
-    def get_last_receive(self, default: T = None) -> Union[Event, T]:
-        """获取最近一次 `receive` 事件
-
-        如果没有事件，返回 `default` 值
-        """
-        return self.state.get(LAST_RECEIVE_KEY, default)
-
-    def get_arg(self, key: str, default: T = None) -> Union[Message, T]:
-        """获取一个 `got` 消息
-
-        如果没有找到对应的消息，返回 `default` 值
-        """
-        return self.state.get(ARG_KEY.format(key=key), default)
-
-    def set_arg(self, key: str, message: Message) -> None:
-        """设置一个 `got` 消息"""
-        self.state[ARG_KEY.format(key=key)] = message
-
-    def set_target(self, target: str, cache: bool = True) -> None:
-        if cache:
-            self.state[REJECT_CACHE_TARGET] = target
-        else:
-            self.state[REJECT_TARGET] = target
-
-    def get_target(self, default: T = None) -> Union[str, T]:
-        return self.state.get(REJECT_TARGET, default)
-
-    def stop_propagation(self):
-        """阻止事件传播"""
-        self.block = True
-
-    async def update_type(self, bot: Bot, event: Event) -> str:
-        updater = self.__class__._default_type_updater
-        if not updater:
-            return "message"
-        return await updater(bot=bot, event=event, state=self.state, matcher=self)
-
-    async def update_permission(self, bot: Bot, event: Event) -> Permission:
-        updater = self.__class__._default_permission_updater
-        if not updater:
-            return USER(event.get_session_id(), perm=self.permission)
-        return await updater(bot=bot, event=event, state=self.state, matcher=self)
-
-    async def resolve_reject(self):
-        handler = current_handler.get()
-        self.handlers.insert(0, handler)
-        if REJECT_CACHE_TARGET in self.state:
-            self.state[REJECT_TARGET] = self.state[REJECT_CACHE_TARGET]
-
-    async def simple_run(
-        self,
-        bot: Bot,
-        event: Event,
-        state: T_State,
-        stack: Optional[AsyncExitStack] = None,
-        dependency_cache: Optional[T_DependencyCache] = None,
-    ):
-        logger.trace(
-            f"Matcher {self} run with incoming args: "
-            f"bot={bot}, event={event}, state={state}"
-        )
-        b_t = current_bot.set(bot)
-        e_t = current_event.set(event)
-        m_t = current_matcher.set(self)
-        try:
-            # Refresh preprocess state
-            self.state.update(state)
-
-            while self.handlers:
-                handler = self.handlers.pop(0)
-                current_handler.set(handler)
-                logger.debug(f"Running handler {handler}")
-                try:
-                    await handler(
-                        matcher=self,
-                        bot=bot,
-                        event=event,
-                        state=self.state,
-                        stack=stack,
-                        dependency_cache=dependency_cache,
-                    )
-                except TypeMisMatch as e:
-                    logger.debug(
-                        f"Handler {handler} param {e.param.name} value {e.value} "
-                        f"mismatch type {e.param._type_display()}, skipped"
-                    )
-                except SkippedException as e:
-                    logger.debug(f"Handler {handler} skipped")
-        except StopPropagation:
-            self.block = True
-        finally:
-            logger.info(f"Matcher {self} running complete")
-            current_bot.reset(b_t)
-            current_event.reset(e_t)
-            current_matcher.reset(m_t)
-
-    # 运行handlers
-    async def run(
-        self,
-        bot: Bot,
-        event: Event,
-        state: T_State,
-        stack: Optional[AsyncExitStack] = None,
-        dependency_cache: Optional[T_DependencyCache] = None,
-    ):
-        try:
-            await self.simple_run(bot, event, state, stack, dependency_cache)
-
-        except RejectedException:
-            await self.resolve_reject()
-            type_ = await self.update_type(bot, event)
-            permission = await self.update_permission(bot, event)
-
-            Matcher.new(
-                type_,
-                Rule(),
-                permission,
-                self.handlers,
-                temp=True,
-                priority=0,
-                block=True,
-                plugin=self.plugin,
-                module=self.module,
-                expire_time=datetime.now() + bot.config.session_expire_timeout,
-                default_state=self.state,
-                default_type_updater=self.__class__._default_type_updater,
-                default_permission_updater=self.__class__._default_permission_updater,
-            )
-        except PausedException:
-            type_ = await self.update_type(bot, event)
-            permission = await self.update_permission(bot, event)
-
-            Matcher.new(
-                type_,
-                Rule(),
-                permission,
-                self.handlers,
-                temp=True,
-                priority=0,
-                block=True,
-                plugin=self.plugin,
-                module=self.module,
-                expire_time=datetime.now() + bot.config.session_expire_timeout,
-                default_state=self.state,
-                default_type_updater=self.__class__._default_type_updater,
-                default_permission_updater=self.__class__._default_permission_updater,
-            )
-        except FinishedException:
-            pass
-
 
 __autodoc__ = {
-    "MatcherMeta": False,
+    "Matcher": True,
-    "Matcher.get_target": False,
+    "matchers": True,
-    "Matcher.set_target": False,
-    "Matcher.update_type": False,
-    "Matcher.update_permission": False,
-    "Matcher.resolve_reject": False,
-    "Matcher.simple_run": False,
 }

nonebot/message.py

@@ -12,7 +12,6 @@ from datetime import datetime
 from contextlib import AsyncExitStack
 from typing import TYPE_CHECKING, Any, Set, Dict, Type, Optional, Coroutine
 
-from nonebot import params
 from nonebot.log import logger
 from nonebot.rule import TrieRule
 from nonebot.utils import escape_tag
@@ -32,6 +31,16 @@ from nonebot.typing import (
     T_EventPreProcessor,
     T_EventPostProcessor,
 )
+from nonebot.internal.params import (
+    ArgParam,
+    BotParam,
+    EventParam,
+    StateParam,
+    DependParam,
+    DefaultParam,
+    MatcherParam,
+    ExceptionParam,
+)
 
 if TYPE_CHECKING:
     from nonebot.adapters import Bot, Event
@@ -42,30 +51,30 @@ _run_preprocessors: Set[Dependent[Any]] = set()
 _run_postprocessors: Set[Dependent[Any]] = set()
 
 EVENT_PCS_PARAMS = [
-    params.DependParam,
+    DependParam,
-    params.BotParam,
+    BotParam,
-    params.EventParam,
+    EventParam,
-    params.StateParam,
+    StateParam,
-    params.DefaultParam,
+    DefaultParam,
 ]
 RUN_PREPCS_PARAMS = [
-    params.DependParam,
+    DependParam,
-    params.BotParam,
+    BotParam,
-    params.EventParam,
+    EventParam,
-    params.StateParam,
+    StateParam,
-    params.ArgParam,
+    ArgParam,
-    params.MatcherParam,
+    MatcherParam,
-    params.DefaultParam,
+    DefaultParam,
 ]
 RUN_POSTPCS_PARAMS = [
-    params.DependParam,
+    DependParam,
-    params.ExceptionParam,
+    ExceptionParam,
-    params.BotParam,
+    BotParam,
-    params.EventParam,
+    EventParam,
-    params.StateParam,
+    StateParam,
-    params.ArgParam,
+    ArgParam,
-    params.MatcherParam,
+    MatcherParam,
-    params.DefaultParam,
+    DefaultParam,
 ]
 
 

nonebot/params.py

@@ -5,21 +5,24 @@ FrontMatter:
     description: nonebot.params 模块
 """
 
-import asyncio
+from typing import Any, Dict, List, Tuple, Optional
-import inspect
-import warnings
-from typing_extensions import Literal
-from typing import Any, Dict, List, Tuple, Callable, Optional, cast
-from contextlib import AsyncExitStack, contextmanager, asynccontextmanager
 
-from pydantic.fields import Required, Undefined, ModelField
+from nonebot.typing import T_State
-
+from nonebot.matcher import Matcher
-from nonebot.log import logger
+from nonebot.adapters import Event, Message
-from nonebot.exception import TypeMisMatch
+from nonebot.internal.params import Arg as Arg
-from nonebot.adapters import Bot, Event, Message
+from nonebot.internal.params import State as State
-from nonebot.dependencies.utils import check_field_type
+from nonebot.internal.params import ArgStr as ArgStr
-from nonebot.dependencies import Param, Dependent, CustomConfig
+from nonebot.internal.params import Depends as Depends
-from nonebot.typing import T_State, T_Handler, T_DependencyCache
+from nonebot.internal.params import ArgParam as ArgParam
+from nonebot.internal.params import BotParam as BotParam
+from nonebot.internal.params import EventParam as EventParam
+from nonebot.internal.params import StateParam as StateParam
+from nonebot.internal.params import DependParam as DependParam
+from nonebot.internal.params import ArgPlainText as ArgPlainText
+from nonebot.internal.params import DefaultParam as DefaultParam
+from nonebot.internal.params import MatcherParam as MatcherParam
+from nonebot.internal.params import ExceptionParam as ExceptionParam
 from nonebot.consts import (
     CMD_KEY,
     PREFIX_KEY,
@@ -31,233 +34,6 @@ from nonebot.consts import (
     REGEX_GROUP,
     REGEX_MATCHED,
 )
-from nonebot.utils import (
-    get_name,
-    run_sync,
-    is_gen_callable,
-    run_sync_ctx_manager,
-    is_async_gen_callable,
-    is_coroutine_callable,
-    generic_check_issubclass,
-)
-
-
-class DependsInner:
-    def __init__(
-        self,
-        dependency: Optional[T_Handler] = None,
-        *,
-        use_cache: bool = True,
-    ) -> None:
-        self.dependency = dependency
-        self.use_cache = use_cache
-
-    def __repr__(self) -> str:
-        dep = get_name(self.dependency)
-        cache = "" if self.use_cache else ", use_cache=False"
-        return f"{self.__class__.__name__}({dep}{cache})"
-
-
-def Depends(
-    dependency: Optional[T_Handler] = None,
-    *,
-    use_cache: bool = True,
-) -> Any:
-    """子依赖装饰器
-
-    参数:
-        dependency: 依赖函数。默认为参数的类型注释。
-        use_cache: 是否使用缓存。默认为 `True`。
-
-    用法:
-        ```python
-        def depend_func() -> Any:
-            return ...
-
-        def depend_gen_func():
-            try:
-                yield ...
-            finally:
-                ...
-
-        async def handler(param_name: Any = Depends(depend_func), gen: Any = Depends(depend_gen_func)):
-            ...
-        ```
-    """
-    return DependsInner(dependency, use_cache=use_cache)
-
-
-class DependParam(Param):
-    """子依赖参数"""
-
-    @classmethod
-    def _check_param(
-        cls,
-        dependent: Dependent,
-        name: str,
-        param: inspect.Parameter,
-    ) -> Optional["DependParam"]:
-        if isinstance(param.default, DependsInner):
-            dependency: T_Handler
-            if param.default.dependency is None:
-                assert param.annotation is not param.empty, "Dependency cannot be empty"
-                dependency = param.annotation
-            else:
-                dependency = param.default.dependency
-            sub_dependent = Dependent[Any].parse(
-                call=dependency,
-                allow_types=dependent.allow_types,
-            )
-            dependent.pre_checkers.extend(sub_dependent.pre_checkers)
-            sub_dependent.pre_checkers.clear()
-            return cls(
-                Required, use_cache=param.default.use_cache, dependent=sub_dependent
-            )
-
-    @classmethod
-    def _check_parameterless(
-        cls, dependent: "Dependent", value: Any
-    ) -> Optional["Param"]:
-        if isinstance(value, DependsInner):
-            assert value.dependency, "Dependency cannot be empty"
-            dependent = Dependent[Any].parse(
-                call=value.dependency, allow_types=dependent.allow_types
-            )
-            return cls(Required, use_cache=value.use_cache, dependent=dependent)
-
-    async def _solve(
-        self,
-        stack: Optional[AsyncExitStack] = None,
-        dependency_cache: Optional[T_DependencyCache] = None,
-        **kwargs: Any,
-    ) -> Any:
-        use_cache: bool = self.extra["use_cache"]
-        dependency_cache = {} if dependency_cache is None else dependency_cache
-
-        sub_dependent: Dependent = self.extra["dependent"]
-        sub_dependent.call = cast(Callable[..., Any], sub_dependent.call)
-        call = sub_dependent.call
-
-        # solve sub dependency with current cache
-        sub_values = await sub_dependent.solve(
-            stack=stack,
-            dependency_cache=dependency_cache,
-            **kwargs,
-        )
-
-        # run dependency function
-        task: asyncio.Task[Any]
-        if use_cache and call in dependency_cache:
-            solved = await dependency_cache[call]
-        elif is_gen_callable(call) or is_async_gen_callable(call):
-            assert isinstance(
-                stack, AsyncExitStack
-            ), "Generator dependency should be called in context"
-            if is_gen_callable(call):
-                cm = run_sync_ctx_manager(contextmanager(call)(**sub_values))
-            else:
-                cm = asynccontextmanager(call)(**sub_values)
-            task = asyncio.create_task(stack.enter_async_context(cm))
-            dependency_cache[call] = task
-            solved = await task
-        elif is_coroutine_callable(call):
-            task = asyncio.create_task(call(**sub_values))
-            dependency_cache[call] = task
-            solved = await task
-        else:
-            task = asyncio.create_task(run_sync(call)(**sub_values))
-            dependency_cache[call] = task
-            solved = await task
-
-        return solved
-
-
-class _BotChecker(Param):
-    async def _solve(self, bot: Bot, **kwargs: Any) -> Any:
-        field: ModelField = self.extra["field"]
-        try:
-            return check_field_type(field, bot)
-        except TypeMisMatch:
-            logger.debug(
-                f"Bot type {type(bot)} not match "
-                f"annotation {field._type_display()}, ignored"
-            )
-            raise
-
-
-class BotParam(Param):
-    """{ref}`nonebot.adapters._bot.Bot` 参数"""
-
-    @classmethod
-    def _check_param(
-        cls, dependent: Dependent, name: str, param: inspect.Parameter
-    ) -> Optional["BotParam"]:
-        if param.default == param.empty:
-            if generic_check_issubclass(param.annotation, Bot):
-                if param.annotation is not Bot:
-                    dependent.pre_checkers.append(
-                        _BotChecker(
-                            Required,
-                            field=ModelField(
-                                name=name,
-                                type_=param.annotation,
-                                class_validators=None,
-                                model_config=CustomConfig,
-                                default=None,
-                                required=True,
-                            ),
-                        )
-                    )
-                return cls(Required)
-            elif param.annotation == param.empty and name == "bot":
-                return cls(Required)
-
-    async def _solve(self, bot: Bot, **kwargs: Any) -> Any:
-        return bot
-
-
-class _EventChecker(Param):
-    async def _solve(self, event: Event, **kwargs: Any) -> Any:
-        field: ModelField = self.extra["field"]
-        try:
-            return check_field_type(field, event)
-        except TypeMisMatch:
-            logger.debug(
-                f"Event type {type(event)} not match "
-                f"annotation {field._type_display()}, ignored"
-            )
-            raise
-
-
-class EventParam(Param):
-    """{ref}`nonebot.adapters._event.Event` 参数"""
-
-    @classmethod
-    def _check_param(
-        cls, dependent: Dependent, name: str, param: inspect.Parameter
-    ) -> Optional["EventParam"]:
-        if param.default == param.empty:
-            if generic_check_issubclass(param.annotation, Event):
-                if param.annotation is not Event:
-                    dependent.pre_checkers.append(
-                        _EventChecker(
-                            Required,
-                            field=ModelField(
-                                name=name,
-                                type_=param.annotation,
-                                class_validators=None,
-                                model_config=CustomConfig,
-                                default=None,
-                                required=True,
-                            ),
-                        )
-                    )
-                return cls(Required)
-            elif param.annotation == param.empty and name == "event":
-                return cls(Required)
-
-    async def _solve(self, event: Event, **kwargs: Any) -> Any:
-        return event
 
 
 async def _event_type(event: Event) -> str:
@@ -265,7 +41,7 @@ async def _event_type(event: Event) -> str:
 
 
 def EventType() -> str:
-    """{ref}`nonebot.adapters._event.Event` 类型参数"""
+    """{ref}`nonebot.adapters.Event` 类型参数"""
     return Depends(_event_type)
 
 
@@ -274,7 +50,7 @@ async def _event_message(event: Event) -> Message:
 
 
 def EventMessage() -> Any:
-    """{ref}`nonebot.adapters._event.Event` 消息参数"""
+    """{ref}`nonebot.adapters.Event` 消息参数"""
     return Depends(_event_message)
 
 
@@ -283,7 +59,7 @@ async def _event_plain_text(event: Event) -> str:
 
 
 def EventPlainText() -> str:
-    """{ref}`nonebot.adapters._event.Event` 纯文本消息参数"""
+    """{ref}`nonebot.adapters.Event` 纯文本消息参数"""
     return Depends(_event_plain_text)
 
 
@@ -292,39 +68,10 @@ async def _event_to_me(event: Event) -> bool:
 
 
 def EventToMe() -> bool:
-    """{ref}`nonebot.adapters._event.Event` `to_me` 参数"""
+    """{ref}`nonebot.adapters.Event` `to_me` 参数"""
     return Depends(_event_to_me)
 
 
-class StateInner(T_State):
-    ...
-
-
-def State() -> T_State:
-    """**Deprecated**: 事件处理状态参数，请直接使用 {ref}`nonebot.typing.T_State`"""
-    warnings.warn("State() is deprecated, use `T_State` instead", DeprecationWarning)
-    return StateInner()
-
-
-class StateParam(Param):
-    """事件处理状态参数"""
-
-    @classmethod
-    def _check_param(
-        cls, dependent: Dependent, name: str, param: inspect.Parameter
-    ) -> Optional["StateParam"]:
-        if isinstance(param.default, StateInner):
-            return cls(Required)
-        elif param.default == param.empty:
-            if param.annotation is T_State:
-                return cls(Required)
-            elif param.annotation == param.empty and name == "state":
-                return cls(Required)
-
-    async def _solve(self, state: T_State, **kwargs: Any) -> Any:
-        return state
-
-
 def _command(state: T_State) -> Message:
     return state[PREFIX_KEY][CMD_KEY]
 
@@ -397,22 +144,6 @@ def RegexDict() -> Dict[str, Any]:
     return Depends(_regex_dict, use_cache=False)
 
 
-class MatcherParam(Param):
-    """事件响应器实例参数"""
-
-    @classmethod
-    def _check_param(
-        cls, dependent: Dependent, name: str, param: inspect.Parameter
-    ) -> Optional["MatcherParam"]:
-        if generic_check_issubclass(param.annotation, Matcher) or (
-            param.annotation == param.empty and name == "matcher"
-        ):
-            return cls(Required)
-
-    async def _solve(self, matcher: "Matcher", **kwargs: Any) -> Any:
-        return matcher
-
-
 def Received(id: Optional[str] = None, default: Any = None) -> Any:
     """`receive` 事件参数"""
 
@@ -431,85 +162,18 @@ def LastReceived(default: Any = None) -> Any:
     return Depends(_last_received, use_cache=False)
 
 
-class ArgInner:
-    def __init__(
-        self, key: Optional[str], type: Literal["message", "str", "plaintext"]
-    ) -> None:
-        self.key = key
-        self.type = type
-
-
-def Arg(key: Optional[str] = None) -> Any:
-    """`got` 的 Arg 参数消息"""
-    return ArgInner(key, "message")
-
-
-def ArgStr(key: Optional[str] = None) -> str:
-    """`got` 的 Arg 参数消息文本"""
-    return ArgInner(key, "str")  # type: ignore
-
-
-def ArgPlainText(key: Optional[str] = None) -> str:
-    """`got` 的 Arg 参数消息纯文本"""
-    return ArgInner(key, "plaintext")  # type: ignore
-
-
-class ArgParam(Param):
-    """`got` 的 Arg 参数"""
-
-    @classmethod
-    def _check_param(
-        cls, dependent: Dependent, name: str, param: inspect.Parameter
-    ) -> Optional["ArgParam"]:
-        if isinstance(param.default, ArgInner):
-            return cls(Required, key=param.default.key or name, type=param.default.type)
-
-    async def _solve(self, matcher: "Matcher", **kwargs: Any) -> Any:
-        message = matcher.get_arg(self.extra["key"])
-        if message is None:
-            return message
-        if self.extra["type"] == "message":
-            return message
-        elif self.extra["type"] == "str":
-            return str(message)
-        else:
-            return message.extract_plain_text()
-
-
-class ExceptionParam(Param):
-    """`run_postprocessor` 的异常参数"""
-
-    @classmethod
-    def _check_param(
-        cls, dependent: Dependent, name: str, param: inspect.Parameter
-    ) -> Optional["ExceptionParam"]:
-        if generic_check_issubclass(param.annotation, Exception) or (
-            param.annotation == param.empty and name == "exception"
-        ):
-            return cls(Required)
-
-    async def _solve(self, exception: Optional[Exception] = None, **kwargs: Any) -> Any:
-        return exception
-
-
-class DefaultParam(Param):
-    """默认值参数"""
-
-    @classmethod
-    def _check_param(
-        cls, dependent: Dependent, name: str, param: inspect.Parameter
-    ) -> Optional["DefaultParam"]:
-        if param.default != param.empty:
-            return cls(param.default)
-
-    async def _solve(self, **kwargs: Any) -> Any:
-        return Undefined
-
-
-from nonebot.matcher import Matcher
-
 __autodoc__ = {
-    "DependsInner": False,
+    "Arg": True,
-    "StateInner": False,
+    "State": True,
-    "ArgInner": False,
+    "ArgStr": True,
+    "Depends": True,
+    "ArgParam": True,
+    "BotParam": True,
+    "EventParam": True,
+    "StateParam": True,
+    "DependParam": True,
+    "ArgPlainText": True,
+    "DefaultParam": True,
+    "MatcherParam": True,
+    "ExceptionParam": True,
 }

nonebot/permission.py

@@ -8,104 +8,11 @@ FrontMatter:
     description: nonebot.permission 模块
 """
 
-import asyncio
+from nonebot.params import EventType
-from contextlib import AsyncExitStack
-from typing import Any, Set, Tuple, Union, NoReturn, Optional, Coroutine
-
 from nonebot.adapters import Bot, Event
-from nonebot.dependencies import Dependent
+from nonebot.internal.permission import USER as USER
-from nonebot.exception import SkippedException
+from nonebot.internal.permission import User as User
-from nonebot.typing import T_DependencyCache, T_PermissionChecker
+from nonebot.internal.permission import Permission as Permission
-from nonebot.params import BotParam, EventType, EventParam, DependParam, DefaultParam
-
-
-async def _run_coro_with_catch(coro: Coroutine[Any, Any, Any]):
-    try:
-        return await coro
-    except SkippedException:
-        return False
-
-
-class Permission:
-    """{ref}`nonebot.matcher.Matcher` 权限类。
-
-    当事件传递时，在 {ref}`nonebot.matcher.Matcher` 运行前进行检查。
-
-    参数:
-        checkers: PermissionChecker
-
-    用法:
-        ```python
-        Permission(async_function) | sync_function
-        # 等价于
-        Permission(async_function, sync_function)
-        ```
-    """
-
-    __slots__ = ("checkers",)
-
-    HANDLER_PARAM_TYPES = [
-        DependParam,
-        BotParam,
-        EventParam,
-        DefaultParam,
-    ]
-
-    def __init__(self, *checkers: Union[T_PermissionChecker, Dependent[bool]]) -> None:
-        self.checkers: Set[Dependent[bool]] = set(
-            checker
-            if isinstance(checker, Dependent)
-            else Dependent[bool].parse(
-                call=checker, allow_types=self.HANDLER_PARAM_TYPES
-            )
-            for checker in checkers
-        )
-        """存储 `PermissionChecker`"""
-
-    async def __call__(
-        self,
-        bot: Bot,
-        event: Event,
-        stack: Optional[AsyncExitStack] = None,
-        dependency_cache: Optional[T_DependencyCache] = None,
-    ) -> bool:
-        """检查是否满足某个权限
-
-        参数:
-            bot: Bot 对象
-            event: Event 对象
-            stack: 异步上下文栈
-            dependency_cache: 依赖缓存
-        """
-        if not self.checkers:
-            return True
-        results = await asyncio.gather(
-            *(
-                _run_coro_with_catch(
-                    checker(
-                        bot=bot,
-                        event=event,
-                        stack=stack,
-                        dependency_cache=dependency_cache,
-                    )
-                )
-                for checker in self.checkers
-            ),
-        )
-        return any(results)
-
-    def __and__(self, other) -> NoReturn:
-        raise RuntimeError("And operation between Permissions is not allowed.")
-
-    def __or__(
-        self, other: Optional[Union["Permission", T_PermissionChecker]]
-    ) -> "Permission":
-        if other is None:
-            return self
-        elif isinstance(other, Permission):
-            return Permission(*self.checkers, *other.checkers)
-        else:
-            return Permission(*self.checkers, other)
 
 
 class Message:
@@ -166,40 +73,6 @@ METAEVENT: Permission = Permission(MetaEvent())
 """
 
 
-class User:
-    """检查当前事件是否属于指定会话
-
-    参数:
-        users: 会话 ID 元组
-        perm: 需同时满足的权限
-    """
-
-    __slots__ = ("users", "perm")
-
-    def __init__(
-        self, users: Tuple[str, ...], perm: Optional[Permission] = None
-    ) -> None:
-        self.users = users
-        self.perm = perm
-
-    async def __call__(self, bot: Bot, event: Event) -> bool:
-        return bool(
-            event.get_session_id() in self.users
-            and (self.perm is None or await self.perm(bot, event))
-        )
-
-
-def USER(*users: str, perm: Optional[Permission] = None):
-    """匹配当前事件属于指定会话
-
-    参数:
-        user: 会话白名单
-        perm: 需要同时满足的权限
-    """
-
-    return Permission(User(users, perm))
-
-
 class SuperUser:
     """检查当前事件是否是消息事件且属于超级管理员"""
 
@@ -216,4 +89,9 @@ class SuperUser:
 SUPERUSER: Permission = Permission(SuperUser())
 """匹配任意超级用户消息类型事件"""
 
-__autodoc__ = {"Permission.__call__": True}
+__autodoc__ = {
+    "Permission": True,
+    "Permission.__call__": True,
+    "User": True,
+    "USER": True,
+}

nonebot/rule.py

@@ -10,22 +10,28 @@ FrontMatter:
 
 import re
 import shlex
-import asyncio
 from itertools import product
 from argparse import Namespace
-from contextlib import AsyncExitStack
 from typing_extensions import TypedDict
 from argparse import ArgumentParser as ArgParser
-from typing import Any, Set, List, Tuple, Union, NoReturn, Optional, Sequence
+from typing import Any, List, Tuple, Union, Optional, Sequence
 
 from pygtrie import CharTrie
 
 from nonebot import get_driver
 from nonebot.log import logger
-from nonebot.dependencies import Dependent
+from nonebot.typing import T_State
-from nonebot.exception import ParserExit, SkippedException
+from nonebot.exception import ParserExit
+from nonebot.internal.rule import Rule as Rule
 from nonebot.adapters import Bot, Event, Message, MessageSegment
-from nonebot.typing import T_State, T_RuleChecker, T_DependencyCache
+from nonebot.params import (
+    Command,
+    EventToMe,
+    EventType,
+    CommandArg,
+    EventMessage,
+    EventPlainText,
+)
 from nonebot.consts import (
     CMD_KEY,
     PREFIX_KEY,
@@ -37,19 +43,6 @@ from nonebot.consts import (
     REGEX_GROUP,
     REGEX_MATCHED,
 )
-from nonebot.params import (
-    Command,
-    BotParam,
-    EventToMe,
-    EventType,
-    CommandArg,
-    EventParam,
-    StateParam,
-    DependParam,
-    DefaultParam,
-    EventMessage,
-    EventPlainText,
-)
 
 CMD_RESULT = TypedDict(
     "CMD_RESULT",
@@ -61,91 +54,6 @@ CMD_RESULT = TypedDict(
 )
 
 
-class Rule:
-    """{ref}`nonebot.matcher.Matcher` 规则类。
-
-    当事件传递时，在 {ref}`nonebot.matcher.Matcher` 运行前进行检查。
-
-    参数:
-        *checkers: RuleChecker
-
-    用法:
-        ```python
-        Rule(async_function) & sync_function
-        # 等价于
-        Rule(async_function, sync_function)
-        ```
-    """
-
-    __slots__ = ("checkers",)
-
-    HANDLER_PARAM_TYPES = [
-        DependParam,
-        BotParam,
-        EventParam,
-        StateParam,
-        DefaultParam,
-    ]
-
-    def __init__(self, *checkers: Union[T_RuleChecker, Dependent[bool]]) -> None:
-        self.checkers: Set[Dependent[bool]] = set(
-            checker
-            if isinstance(checker, Dependent)
-            else Dependent[bool].parse(
-                call=checker, allow_types=self.HANDLER_PARAM_TYPES
-            )
-            for checker in checkers
-        )
-        """存储 `RuleChecker`"""
-
-    async def __call__(
-        self,
-        bot: Bot,
-        event: Event,
-        state: T_State,
-        stack: Optional[AsyncExitStack] = None,
-        dependency_cache: Optional[T_DependencyCache] = None,
-    ) -> bool:
-        """检查是否符合所有规则
-
-        参数:
-            bot: Bot 对象
-            event: Event 对象
-            state: 当前 State
-            stack: 异步上下文栈
-            dependency_cache: 依赖缓存
-        """
-        if not self.checkers:
-            return True
-        try:
-            results = await asyncio.gather(
-                *(
-                    checker(
-                        bot=bot,
-                        event=event,
-                        state=state,
-                        stack=stack,
-                        dependency_cache=dependency_cache,
-                    )
-                    for checker in self.checkers
-                )
-            )
-        except SkippedException:
-            return False
-        return all(results)
-
-    def __and__(self, other: Optional[Union["Rule", T_RuleChecker]]) -> "Rule":
-        if other is None:
-            return self
-        elif isinstance(other, Rule):
-            return Rule(*self.checkers, *other.checkers)
-        else:
-            return Rule(*self.checkers, other)
-
-    def __or__(self, other) -> NoReturn:
-        raise RuntimeError("Or operation between rules is not allowed.")
-
-
 class TrieRule:
     prefix: CharTrie = CharTrie()
 
@@ -551,6 +459,7 @@ def to_me() -> Rule:
 
 
 __autodoc__ = {
+    "Rule": True,
     "Rule.__call__": True,
     "TrieRule": False,
     "ArgumentParser.exit": False,

website/src/pages/changelog.md

@@ -14,6 +14,8 @@ description: Changelog
 - 修改 `load_builtin_plugins` 函数，使其能够支持加载多个内置插件
 - 新增 `load_builtin_plugin` 函数，用于加载单个内置插件
 - 修改 `Message` 和 `MessageSegment` 类，完善 typing，转移 Mapping 构建支持至 pydantic validate
+- 调整项目结构，分离内部定义与用户接口
+- 修改 `Bot Connection Hook` 支持依赖注入
 
 ## v2.0.0b1