✨ Feature: 新增事件类型过滤 rule (#1183)

nonebot/plugin/__init__.py

@@ -16,6 +16,7 @@
 - `on_command` => {ref}``on_command` <nonebot.plugin.on.on_command>`
 - `on_shell_command` => {ref}``on_shell_command` <nonebot.plugin.on.on_shell_command>`
 - `on_regex` => {ref}``on_regex` <nonebot.plugin.on.on_regex>`
+- `on_type` => {ref}``on_type` <nonebot.plugin.on.on_type>`
 - `CommandGroup` => {ref}``CommandGroup` <nonebot.plugin.on.CommandGroup>`
 - `Matchergroup` => {ref}``MatcherGroup` <nonebot.plugin.on.MatcherGroup>`
 - `load_plugin` => {ref}``load_plugin` <nonebot.plugin.load.load_plugin>`
@@ -105,6 +106,7 @@ def get_available_plugin_names() -> Set[str]:
 
 from .on import on as on
 from .manager import PluginManager
+from .on import on_type as on_type
 from .load import require as require
 from .on import on_regex as on_regex
 from .plugin import Plugin as Plugin

nonebot/plugin/on.py

@@ -10,6 +10,7 @@ from types import ModuleType
 from datetime import datetime, timedelta
 from typing import Any, Set, Dict, List, Type, Tuple, Union, Optional
 
+from nonebot.adapters import Event
 from nonebot.matcher import Matcher
 from nonebot.permission import Permission
 from nonebot.dependencies import Dependent
@@ -19,6 +20,7 @@ from nonebot.rule import (
     ArgumentParser,
     regex,
     command,
+    is_type,
     keyword,
     endswith,
     fullmatch,
@@ -437,6 +439,30 @@ def on_regex(
     return on_message(regex(pattern, flags) & rule, **kwargs, _depth=_depth + 1)
 
 
+def on_type(
+    types: Union[Type[Event], Tuple[Type[Event]]],
+    rule: Optional[Union[Rule, T_RuleChecker]] = None,
+    *,
+    _depth: int = 0,
+    **kwargs,
+) -> Type[Matcher]:
+    """注册一个事件响应器，并且当事件为指定类型时响应。
+
+    参数:
+        types: 事件类型
+        rule: 事件响应规则
+        permission: 事件响应权限
+        handlers: 事件处理函数列表
+        temp: 是否为临时事件响应器（仅执行一次）
+        expire_time: 事件响应器最终有效时间点，过时即被删除
+        priority: 事件响应器优先级
+        block: 是否阻止事件向更低优先级传递
+        state: 默认 state
+    """
+    event_types = types if isinstance(types, tuple) else (types,)
+    return on(rule=is_type(*event_types) & rule, **kwargs, _depth=_depth + 1)
+
+
 class CommandGroup:
     """命令组，用于声明一组有相同名称前缀的命令。
 
@@ -593,6 +619,7 @@ class MatcherGroup:
         final_kwargs = self.base_kwargs.copy()
         final_kwargs.update(kwargs)
         final_kwargs.pop("type", None)
+        final_kwargs.pop("permission", None)
         matcher = on_notice(**final_kwargs, _depth=1)
         self.matchers.append(matcher)
         return matcher
@@ -612,6 +639,7 @@ class MatcherGroup:
         final_kwargs = self.base_kwargs.copy()
         final_kwargs.update(kwargs)
         final_kwargs.pop("type", None)
+        final_kwargs.pop("permission", None)
         matcher = on_request(**final_kwargs, _depth=1)
         self.matchers.append(matcher)
         return matcher
@@ -794,3 +822,26 @@ class MatcherGroup:
         matcher = on_regex(pattern, flags=flags, **final_kwargs, _depth=1)
         self.matchers.append(matcher)
         return matcher
+
+    def on_type(
+        self, types: Union[Type[Event], Tuple[Type[Event]]], **kwargs
+    ) -> Type[Matcher]:
+        """注册一个事件响应器，并且当事件为指定类型时响应。
+
+        参数:
+            types: 事件类型
+            rule: 事件响应规则
+            permission: 事件响应权限
+            handlers: 事件处理函数列表
+            temp: 是否为临时事件响应器（仅执行一次）
+            expire_time: 事件响应器最终有效时间点，过时即被删除
+            priority: 事件响应器优先级
+            block: 是否阻止事件向更低优先级传递
+            state: 默认 state
+        """
+        final_kwargs = self.base_kwargs.copy()
+        final_kwargs.update(kwargs)
+        final_kwargs.pop("type", None)
+        matcher = on_type(types, **final_kwargs, _depth=1)
+        self.matchers.append(matcher)
+        return matcher

nonebot/plugin/on.pyi

@@ -2,6 +2,7 @@ import re
 from datetime import datetime, timedelta
 from typing import Set, List, Type, Tuple, Union, Optional
 
+from nonebot.adapters import Event
 from nonebot.matcher import Matcher
 from nonebot.permission import Permission
 from nonebot.dependencies import Dependent
@@ -152,6 +153,18 @@ def on_regex(
     block: bool = ...,
     state: Optional[T_State] = ...,
 ) -> Type[Matcher]: ...
+def on_type(
+    types: Union[Type[Event], Tuple[Type[Event]]],
+    rule: Optional[Union[Rule, T_RuleChecker]] = ...,
+    *,
+    permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
+    handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+    temp: bool = ...,
+    expire_time: Optional[Union[datetime, timedelta]] = ...,
+    priority: int = ...,
+    block: bool = ...,
+    state: Optional[T_State] = ...,
+) -> Type[Matcher]: ...
 
 class CommandGroup:
     def __init__(
@@ -171,8 +184,8 @@ class CommandGroup:
         self,
         cmd: Union[str, Tuple[str, ...]],
         *,
-        aliases: Optional[Set[Union[str, Tuple[str, ...]]]],
         rule: Optional[Union[Rule, T_RuleChecker]] = ...,
+        aliases: Optional[Set[Union[str, Tuple[str, ...]]]] = ...,
         permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
         handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
         temp: bool = ...,
@@ -186,7 +199,7 @@ class CommandGroup:
         cmd: Union[str, Tuple[str, ...]],
         *,
         rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        aliases: Optional[Set[Union[str, Tuple[str, ...]]]],
+        aliases: Optional[Set[Union[str, Tuple[str, ...]]]] = ...,
         parser: Optional[ArgumentParser] = ...,
         permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
         handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
@@ -367,3 +380,16 @@ class MatcherGroup:
         block: bool = ...,
         state: Optional[T_State] = ...,
     ) -> Type[Matcher]: ...
+    def on_type(
+        self,
+        types: Union[Type[Event], Tuple[Type[Event]]],
+        *,
+        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
+        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
+        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        temp: bool = ...,
+        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        priority: int = ...,
+        block: bool = ...,
+        state: Optional[T_State] = ...,
+    ) -> Type[Matcher]: ...