💡 add permission docstring

docs/.vuepress/config.js

@@ -92,6 +92,10 @@ module.exports = context => ({
                   title: "nonebot.rule 模块",
                   path: "rule"
                 },
+                {
+                  title: "nonebot.permission 模块",
+                  path: "permission"
+                },
                 {
                   title: "nonebot.utils 模块",
                   path: "utils"

docs/api/README.md

@@ -22,6 +22,9 @@
     * [nonebot.rule](rule.html)
 
 
+    * [nonebot.permission](permission.html)
+
+
     * [nonebot.utils](utils.html)
 
 

docs/api/permission.md

@@ -0,0 +1,121 @@
+---
+contentSidebar: true
+sidebarDepth: 0
+---
+
+# NoneBot.permission 模块
+
+## 权限
+
+每个 `Matcher` 拥有一个 `Permission` ，其中是 **异步** `PermissionChecker` 的集合，只要有一个 `PermissionChecker` 检查结果为 `True` 时就会继续运行。
+
+:::tip 提示
+`PermissionChecker` 既可以是 async function 也可以是 sync function
+:::
+
+
+## `MESSAGE`
+
+
+* **说明**: 匹配任意 `message` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 message type 的 Matcher。
+
+
+## `NOTICE`
+
+
+* **说明**: 匹配任意 `notice` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 notice type 的 Matcher。
+
+
+## `REQUEST`
+
+
+* **说明**: 匹配任意 `request` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 request type 的 Matcher。
+
+
+## `METAEVENT`
+
+
+* **说明**: 匹配任意 `meta_event` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 meta_event type 的 Matcher。
+
+
+## `USER(*user, perm=<nonebot.permission.Permission object>)`
+
+
+* **说明**
+
+    在白名单内且满足 perm
+
+
+
+* **参数**
+
+    
+    * `*user: int`: 白名单
+
+
+    * `perm: Permission`: 需要同时满足的权限
+
+
+
+## `PRIVATE`
+
+
+* **说明**: 匹配任意私聊消息类型事件
+
+
+## `PRIVATE_FRIEND`
+
+
+* **说明**: 匹配任意好友私聊消息类型事件
+
+
+## `PRIVATE_GROUP`
+
+
+* **说明**: 匹配任意群临时私聊消息类型事件
+
+
+## `PRIVATE_OTHER`
+
+
+* **说明**: 匹配任意其他私聊消息类型事件
+
+
+## `GROUP`
+
+
+* **说明**: 匹配任意群聊消息类型事件
+
+
+## `GROUP_MEMBER`
+
+
+* **说明**: 匹配任意群员群聊消息类型事件
+
+:::warning 警告
+该权限通过 event.sender 进行判断且不包含管理员以及群主！
+:::
+
+
+## `GROUP_ADMIN`
+
+
+* **说明**: 匹配任意群管理员群聊消息类型事件
+
+
+## `GROUP_OWNER`
+
+
+* **说明**: 匹配任意群主群聊消息类型事件
+
+
+## `SUPERUSER`
+
+
+* **说明**: 匹配任意超级用户消息类型事件
+
+
+## `EVERYBODY`
+
+
+* **说明**: 匹配任意消息类型事件

docs/api/rule.md

@@ -7,7 +7,7 @@ sidebarDepth: 0
 
 ## 规则
 
-每个 `Matcher` 拥有一个 `Rule` ，其中是 `RuleChecker` 的集合，只有当所有 `RuleChecker` 检查结果为 `True` 时继续运行。
+每个 `Matcher` 拥有一个 `Rule` ，其中是 **异步** `RuleChecker` 的集合，只有当所有 `RuleChecker` 检查结果为 `True` 时继续运行。
 
 :::tip 提示
 `RuleChecker` 既可以是 async function 也可以是 sync function
@@ -88,3 +88,35 @@ Rule(async_function, run_sync(sync_function))
 
     
     * `bool`
+
+
+
+## `startswith(msg)`
+
+
+* **说明**
+
+    匹配消息开头
+
+
+
+* **参数**
+
+    
+    * `msg: str`: 消息开头字符串
+
+
+
+## `endswith(msg)`
+
+
+* **说明**
+
+    匹配消息结尾
+
+
+
+* **参数**
+
+    
+    * `msg: str`: 消息结尾字符串

docs_build/README.rst

@@ -8,5 +8,6 @@ NoneBot Api Reference
   - `nonebot.sched <sched.html>`_
   - `nonebot.log <log.html>`_
   - `nonebot.rule <rule.html>`_
+  - `nonebot.permission <permission.html>`_
   - `nonebot.utils <utils.html>`_
   - `nonebot.exception <exception.html>`_

docs_build/permission.rst

@@ -0,0 +1,11 @@
+---
+contentSidebar: true
+sidebarDepth: 0
+---
+
+NoneBot.permission 模块
+====================
+
+.. automodule:: nonebot.permission
+   :members:
+   :show-inheritance:

nonebot/permission.py

@@ -1,5 +1,15 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+"""
+权限
+====
+
+每个 ``Matcher`` 拥有一个 ``Permission`` ，其中是 **异步** ``PermissionChecker`` 的集合，只要有一个 ``PermissionChecker`` 检查结果为 ``True`` 时就会继续运行。
+
+\:\:\:tip 提示
+``PermissionChecker`` 既可以是 async function 也可以是 sync function
+\:\:\:
+"""
 
 import asyncio
 
@@ -12,9 +22,28 @@ class Permission:
 
     def __init__(self, *checkers: Callable[[Bot, Event],
                                            Awaitable[bool]]) -> None:
+        """
+        :参数:
+          * ``*checkers: Callable[[Bot, Event], Awaitable[bool]]``: **异步** PermissionChecker
+        """
         self.checkers = set(checkers)
+        """
+        :说明:
+          存储 ``PermissionChecker``
+        :类型:
+          * ``Set[Callable[[Bot, Event], Awaitable[bool]]]``
+        """
 
     async def __call__(self, bot: Bot, event: Event) -> bool:
+        """
+        :说明:
+          检查是否满足某个权限
+        :参数:
+          * ``bot: Bot``: Bot 对象
+          * ``event: Event``: Event 对象
+        :返回:
+          - ``bool``
+        """
         if not self.checkers:
             return True
         results = await asyncio.gather(
@@ -53,12 +82,31 @@ async def _metaevent(bot: Bot, event: Event) -> bool:
 
 
 MESSAGE = Permission(_message)
+"""
+- **说明**: 匹配任意 ``message`` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 message type 的 Matcher。
+"""
 NOTICE = Permission(_notice)
+"""
+- **说明**: 匹配任意 ``notice`` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 notice type 的 Matcher。
+"""
 REQUEST = Permission(_request)
+"""
+- **说明**: 匹配任意 ``request`` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 request type 的 Matcher。
+"""
 METAEVENT = Permission(_metaevent)
+"""
+- **说明**: 匹配任意 ``meta_event`` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 meta_event type 的 Matcher。
+"""
 
 
 def USER(*user: int, perm: Permission = Permission()):
+    """
+    :说明:
+      在白名单内且满足 perm
+    :参数:
+      * ``*user: int``: 白名单
+      * ``perm: Permission``: 需要同时满足的权限
+    """
 
     async def _user(bot: Bot, event: Event) -> bool:
         return event.type == "message" and event.user_id in user and await perm(
@@ -87,9 +135,21 @@ async def _private_other(bot: Bot, event: Event) -> bool:
 
 
 PRIVATE = Permission(_private)
+"""
+- **说明**: 匹配任意私聊消息类型事件
+"""
 PRIVATE_FRIEND = Permission(_private_friend)
+"""
+- **说明**: 匹配任意好友私聊消息类型事件
+"""
 PRIVATE_GROUP = Permission(_private_group)
+"""
+- **说明**: 匹配任意群临时私聊消息类型事件
+"""
 PRIVATE_OTHER = Permission(_private_other)
+"""
+- **说明**: 匹配任意其他私聊消息类型事件
+"""
 
 
 async def _group(bot: Bot, event: Event) -> bool:
@@ -112,9 +172,25 @@ async def _group_owner(bot: Bot, event: Event) -> bool:
 
 
 GROUP = Permission(_group)
+"""
+- **说明**: 匹配任意群聊消息类型事件
+"""
 GROUP_MEMBER = Permission(_group_member)
+"""
+- **说明**: 匹配任意群员群聊消息类型事件
+
+\:\:\:warning 警告
+该权限通过 event.sender 进行判断且不包含管理员以及群主！
+\:\:\:
+"""
 GROUP_ADMIN = Permission(_group_admin)
+"""
+- **说明**: 匹配任意群管理员群聊消息类型事件
+"""
 GROUP_OWNER = Permission(_group_owner)
+"""
+- **说明**: 匹配任意群主群聊消息类型事件
+"""
 
 
 async def _superuser(bot: Bot, event: Event) -> bool:
@@ -122,4 +198,10 @@ async def _superuser(bot: Bot, event: Event) -> bool:
 
 
 SUPERUSER = Permission(_superuser)
+"""
+- **说明**: 匹配任意超级用户消息类型事件
+"""
 EVERYBODY = MESSAGE
+"""
+- **说明**: 匹配任意消息类型事件
+"""

nonebot/rule.py

@@ -4,7 +4,7 @@
 规则
 ====
 
-每个 ``Matcher`` 拥有一个 ``Rule`` ，其中是 ``RuleChecker`` 的集合，只有当所有 ``RuleChecker`` 检查结果为 ``True`` 时继续运行。
+每个 ``Matcher`` 拥有一个 ``Rule`` ，其中是 **异步** ``RuleChecker`` 的集合，只有当所有 ``RuleChecker`` 检查结果为 ``True`` 时继续运行。
 
 \:\:\:tip 提示
 ``RuleChecker`` 既可以是 async function 也可以是 sync function