From fe35e8956b7c0ab3334878f95de833356b3c35eb Mon Sep 17 00:00:00 2001 From: yanyongyu Date: Mon, 14 Sep 2020 20:48:03 +0800 Subject: [PATCH] :bulb: add permission docstring --- docs/.vuepress/config.js | 4 ++ docs/api/README.md | 3 + docs/api/permission.md | 121 ++++++++++++++++++++++++++++++++++++++ docs/api/rule.md | 34 ++++++++++- docs_build/README.rst | 1 + docs_build/permission.rst | 11 ++++ nonebot/permission.py | 82 ++++++++++++++++++++++++++ nonebot/rule.py | 2 +- 8 files changed, 256 insertions(+), 2 deletions(-) create mode 100644 docs/api/permission.md create mode 100644 docs_build/permission.rst diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index c38ed27d..58b69554 100644 --- a/docs/.vuepress/config.js +++ b/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" diff --git a/docs/api/README.md b/docs/api/README.md index 71e3c247..2fa1066a 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -22,6 +22,9 @@ * [nonebot.rule](rule.html) + * [nonebot.permission](permission.html) + + * [nonebot.utils](utils.html) diff --git a/docs/api/permission.md b/docs/api/permission.md new file mode 100644 index 00000000..26d3cd34 --- /dev/null +++ b/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=)` + + +* **说明** + + 在白名单内且满足 perm + + + +* **参数** + + + * `*user: int`: 白名单 + + + * `perm: Permission`: 需要同时满足的权限 + + + +## `PRIVATE` + + +* **说明**: 匹配任意私聊消息类型事件 + + +## `PRIVATE_FRIEND` + + +* **说明**: 匹配任意好友私聊消息类型事件 + + +## `PRIVATE_GROUP` + + +* **说明**: 匹配任意群临时私聊消息类型事件 + + +## `PRIVATE_OTHER` + + +* **说明**: 匹配任意其他私聊消息类型事件 + + +## `GROUP` + + +* **说明**: 匹配任意群聊消息类型事件 + + +## `GROUP_MEMBER` + + +* **说明**: 匹配任意群员群聊消息类型事件 + +:::warning 警告 +该权限通过 event.sender 进行判断且不包含管理员以及群主！ +::: + + +## `GROUP_ADMIN` + + +* **说明**: 匹配任意群管理员群聊消息类型事件 + + +## `GROUP_OWNER` + + +* **说明**: 匹配任意群主群聊消息类型事件 + + +## `SUPERUSER` + + +* **说明**: 匹配任意超级用户消息类型事件 + + +## `EVERYBODY` + + +* **说明**: 匹配任意消息类型事件 diff --git a/docs/api/rule.md b/docs/api/rule.md index ad53a09f..269abc57 100644 --- a/docs/api/rule.md +++ b/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`: 消息结尾字符串 diff --git a/docs_build/README.rst b/docs_build/README.rst index 6ce28acd..cb726c38 100644 --- a/docs_build/README.rst +++ b/docs_build/README.rst @@ -8,5 +8,6 @@ NoneBot Api Reference - `nonebot.sched `_ - `nonebot.log `_ - `nonebot.rule `_ + - `nonebot.permission `_ - `nonebot.utils `_ - `nonebot.exception `_ diff --git a/docs_build/permission.rst b/docs_build/permission.rst new file mode 100644 index 00000000..15144a62 --- /dev/null +++ b/docs_build/permission.rst @@ -0,0 +1,11 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +NoneBot.permission 模块 +==================== + +.. automodule:: nonebot.permission + :members: + :show-inheritance: diff --git a/nonebot/permission.py b/nonebot/permission.py index 22a2c66b..1f43cf38 100644 --- a/nonebot/permission.py +++ b/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 +""" +- **说明**: 匹配任意消息类型事件 +""" diff --git a/nonebot/rule.py b/nonebot/rule.py index d2f33fcf..0b1b5cc0 100644 --- a/nonebot/rule.py +++ b/nonebot/rule.py @@ -4,7 +4,7 @@ 规则 ==== -每个 ``Matcher`` 拥有一个 ``Rule`` ，其中是 ``RuleChecker`` 的集合，只有当所有 ``RuleChecker`` 检查结果为 ``True`` 时继续运行。 +每个 ``Matcher`` 拥有一个 ``Rule`` ，其中是 **异步** ``RuleChecker`` 的集合，只有当所有 ``RuleChecker`` 检查结果为 ``True`` 时继续运行。 \:\:\:tip 提示 ``RuleChecker`` 既可以是 async function 也可以是 sync function