💡 add rule utils docstring

nonebot/__init__.py

@@ -136,7 +136,7 @@ def init(*, _env_file: Optional[str] = None, **kwargs):
 
     :返回:
 
-      - `None`
+      - ``None``
 
     :用法:
 
@@ -192,7 +192,7 @@ def run(host: Optional[str] = None,
 
     :返回:
 
-      - `None`
+      - ``None``
 
     :用法:
 

nonebot/permission.py

@@ -4,14 +4,15 @@
 import asyncio
 
 from nonebot.utils import run_sync
-from nonebot.typing import Bot, Event, Union, NoReturn, PermissionChecker
+from nonebot.typing import Bot, Event, Union, NoReturn, Callable, Awaitable, PermissionChecker
 
 
 class Permission:
     __slots__ = ("checkers",)
 
-    def __init__(self, *checkers: PermissionChecker) -> None:
-        self.checkers = list(checkers)
+    def __init__(self, *checkers: Callable[[Bot, Event],
+                                           Awaitable[bool]]) -> None:
+        self.checkers = set(checkers)
 
     async def __call__(self, bot: Bot, event: Event) -> bool:
         if not self.checkers:
@@ -25,13 +26,13 @@ class Permission:
 
     def __or__(self, other: Union["Permission",
                                   PermissionChecker]) -> "Permission":
-        checkers = [*self.checkers]
+        checkers = self.checkers.copy()
         if isinstance(other, Permission):
-            checkers.extend(other.checkers)
+            checkers |= other.checkers
         elif asyncio.iscoroutinefunction(other):
-            checkers.append(other)
+            checkers.add(other)
         else:
-            checkers.append(run_sync(other))
+            checkers.add(run_sync(other))
         return Permission(*checkers)
 
 

nonebot/plugin.py

@@ -151,8 +151,6 @@ def on_command(cmd: Union[str, Tuple[str, ...]],
 
     async def _strip_cmd(bot, event, state: dict):
         message = event.message
-        print(message[0].data)
-        print(state["_prefix"])
         event.message = message.__class__(
             str(message)[len(state["_prefix"]["raw_command"]):].strip())
 

nonebot/rule.py

@@ -1,5 +1,15 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+"""
+规则
+====
+
+每个 ``Matcher`` 拥有一个 ``Rule`` ，其中是 ``RuleChecker`` 的集合，只有当所有 ``RuleChecker`` 检查结果为 ``True`` 时继续运行。
+
+\:\:\:tip 提示
+``RuleChecker`` 既可以是 async function 也可以是 sync function
+\:\:\:
+"""
 
 import re
 import asyncio
@@ -10,28 +20,62 @@ from pygtrie import CharTrie
 from nonebot import get_driver
 from nonebot.log import logger
 from nonebot.utils import run_sync
-from nonebot.typing import Bot, Any, Dict, Event, Union, Tuple, NoReturn, RuleChecker
+from nonebot.typing import Bot, Any, Dict, Event, Union, Tuple, NoReturn, Callable, Awaitable, RuleChecker
 
 
 class Rule:
+    """
+    :说明:
+      ``Matcher`` 规则类，当事件传递时，在 ``Matcher`` 运行前进行检查。
+    :示例:
+
+    .. code-block:: python
+
+        Rule(async_function) & sync_function
+        # 等价于
+        from nonebot.utils import run_sync
+        Rule(async_function, run_sync(sync_function))
+    """
     __slots__ = ("checkers",)
 
-    def __init__(self, *checkers: RuleChecker) -> None:
-        self.checkers = list(checkers)
+    def __init__(
+            self, *checkers: Callable[[Bot, Event, dict],
+                                      Awaitable[bool]]) -> None:
+        """
+        :参数:
+          * ``*checkers: Callable[[Bot, Event, dict], Awaitable[bool]]``: **异步** RuleChecker
+        """
+        self.checkers = set(checkers)
+        """
+        :说明:
+          存储 ``RuleChecker``
+        :类型:
+          * ``Set[Callable[[Bot, Event, dict], Awaitable[bool]]]``
+        """
 
     async def __call__(self, bot: Bot, event: Event, state: dict) -> bool:
+        """
+        :说明:
+          检查是否符合所有规则
+        :参数:
+          * ``bot: Bot``: Bot 对象
+          * ``event: Event``: Event 对象
+          * ``state: dict``: 当前 State
+        :返回:
+          - ``bool``
+        """
         results = await asyncio.gather(
             *map(lambda c: c(bot, event, state), self.checkers))
         return all(results)
 
     def __and__(self, other: Union["Rule", RuleChecker]) -> "Rule":
-        checkers = [*self.checkers]
+        checkers = self.checkers.copy()
         if isinstance(other, Rule):
-            checkers.extend(other.checkers)
+            checkers |= other.checkers
         elif asyncio.iscoroutinefunction(other):
-            checkers.append(other)
+            checkers.add(other)  # type: ignore
         else:
-            checkers.append(run_sync(other))
+            checkers.add(run_sync(other))
         return Rule(*checkers)
 
     def __or__(self, other) -> NoReturn:

nonebot/typing.py

@@ -46,7 +46,7 @@ def overrides(InterfaceClass: object):
 
 Driver = TypeVar("Driver", bound="BaseDriver")
 """
-:类型: `BaseDriver`
+:类型: ``BaseDriver``
 
 :说明:
 
@@ -54,7 +54,7 @@ Driver = TypeVar("Driver", bound="BaseDriver")
 """
 WebSocket = TypeVar("WebSocket", bound="BaseWebSocket")
 """
-:类型: `BaseWebSocket`
+:类型: ``BaseWebSocket``
 
 :说明:
 
@@ -63,7 +63,7 @@ WebSocket = TypeVar("WebSocket", bound="BaseWebSocket")
 
 Bot = TypeVar("Bot", bound="BaseBot")
 """
-:类型: `BaseBot`
+:类型: ``BaseBot``
 
 :说明:
 
@@ -71,7 +71,7 @@ Bot = TypeVar("Bot", bound="BaseBot")
 """
 Event = TypeVar("Event", bound="BaseEvent")
 """
-:类型: `BaseEvent`
+:类型: ``BaseEvent``
 
 :说明:
 
@@ -79,7 +79,7 @@ Event = TypeVar("Event", bound="BaseEvent")
 """
 Message = TypeVar("Message", bound="BaseMessage")
 """
-:类型: `BaseMessage`
+:类型: ``BaseMessage``
 
 :说明:
 
@@ -87,7 +87,7 @@ Message = TypeVar("Message", bound="BaseMessage")
 """
 MessageSegment = TypeVar("MessageSegment", bound="BaseMessageSegment")
 """
-:类型: `BaseMessageSegment`
+:类型: ``BaseMessageSegment``
 
 :说明:
 
@@ -97,7 +97,7 @@ MessageSegment = TypeVar("MessageSegment", bound="BaseMessageSegment")
 PreProcessor = Callable[[Bot, Event, dict], Union[Awaitable[None],
                                                   Awaitable[NoReturn]]]
 """
-:类型: `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]`
+:类型: ``Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]``
 
 :说明:
 
@@ -106,7 +106,7 @@ PreProcessor = Callable[[Bot, Event, dict], Union[Awaitable[None],
 
 Matcher = TypeVar("Matcher", bound="MatcherClass")
 """
-:类型: `Matcher`
+:类型: ``Matcher``
 
 :说明:
 
@@ -114,15 +114,15 @@ Matcher = TypeVar("Matcher", bound="MatcherClass")
 """
 Rule = TypeVar("Rule", bound="RuleClass")
 """
-:类型: `Rule`
+:类型: ``Rule``
 
 :说明:
 
   Rule 即判断是否响应事件的处理类。内部存储 RuleChecker ，返回全为 True 则响应事件。
 """
-RuleChecker = Callable[[Bot, Event, dict], Awaitable[bool]]
+RuleChecker = Callable[[Bot, Event, dict], Union[bool, Awaitable[bool]]]
 """
-:类型: `Callable[[Bot, Event, dict], Awaitable[bool]]`
+:类型: ``Callable[[Bot, Event, dict], Union[bool, Awaitable[bool]]]``
 
 :说明:
 
@@ -130,15 +130,15 @@ RuleChecker = Callable[[Bot, Event, dict], Awaitable[bool]]
 """
 Permission = TypeVar("Permission", bound="PermissionClass")
 """
-:类型: `Permission`
+:类型: ``Permission``
 
 :说明:
 
   Permission 即判断是否响应消息的处理类。内部存储 PermissionChecker ，返回只要有一个 True 则响应消息。
 """
-PermissionChecker = Callable[[Bot, Event], Awaitable[bool]]
+PermissionChecker = Callable[[Bot, Event], Union[bool, Awaitable[bool]]]
 """
-:类型: `Callable[[Bot, Event], Awaitable[bool]]`
+:类型: ``Callable[[Bot, Event], Union[bool, Awaitable[bool]]]``
 
 :说明:
 
@@ -147,7 +147,7 @@ PermissionChecker = Callable[[Bot, Event], Awaitable[bool]]
 Handler = Callable[[Bot, Event, dict], Union[Awaitable[None],
                                              Awaitable[NoReturn]]]
 """
-:类型: `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]`
+:类型: ``Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]``
 
 :说明:
 
@@ -156,7 +156,7 @@ Handler = Callable[[Bot, Event, dict], Union[Awaitable[None],
 ArgsParser = Callable[[Bot, Event, dict], Union[Awaitable[None],
                                                 Awaitable[NoReturn]]]
 """
-:类型: `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]`
+:类型: ``Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]``
 
 :说明:
 

nonebot/utils.py

@@ -16,7 +16,7 @@ def run_sync(func: Callable[..., Any]) -> Callable[..., Awaitable[Any]]:
     :参数:
       * ``func: Callable[..., Any]``: 被装饰的同步函数
     :返回:
-      - Callable[..., Awaitable[Any]]
+      - ``Callable[..., Awaitable[Any]]``
     """
 
     @wraps(func)
@@ -31,10 +31,8 @@ def run_sync(func: Callable[..., Any]) -> Callable[..., Awaitable[Any]]:
 
 class DataclassEncoder(json.JSONEncoder):
     """
-    :类型:
-      ``json.JSONEncoder``
     :说明:
-      ``JSONEncoder`` used when encoding ``Message`` (List of dataclasses)
+      在JSON序列化 ``Message`` (List[Dataclass]) 时使用的 ``JSONEncoder``
     """
 
     @overrides(json.JSONEncoder)