From 5989c3fecd929b061e96d75ece020abdeb69a139 Mon Sep 17 00:00:00 2001 From: AkiraXie Date: Thu, 20 May 2021 20:20:51 +0800 Subject: [PATCH 1/4] :memo: update permission doc --- docs/advanced/overloaded-handlers.md | 4 +- docs/advanced/permission.md | 91 ++++++++++++++++++++++++++++ 2 files changed, 93 insertions(+), 2 deletions(-) diff --git a/docs/advanced/overloaded-handlers.md b/docs/advanced/overloaded-handlers.md index 1895727b..3d78def2 100644 --- a/docs/advanced/overloaded-handlers.md +++ b/docs/advanced/overloaded-handlers.md @@ -12,7 +12,7 @@ ::: -下面，我们会以 `CQHTTP` 中的 `消息事件` 中的 `群聊消息事件` 和 `私聊消息事件` 为例，对该机制的应用进行简单的介绍。 +下面，我们会以 `CQHTTP` 中的 `群聊消息事件` 和 `私聊消息事件` 为例，对该机制的应用进行简单的介绍。 ## 一个例子 @@ -61,4 +61,4 @@ async def _(bot: Bot, event: PrivateMessageEvent): await matcher.send("私聊消息事件响应成功！") ``` -只有触发事件符合的函数才会触发装饰器。 +只有触发事件符合的函数才会触发装饰器。 \ No newline at end of file diff --git a/docs/advanced/permission.md b/docs/advanced/permission.md index 7190bcdd..b49c0981 100644 --- a/docs/advanced/permission.md +++ b/docs/advanced/permission.md @@ -1 +1,92 @@ # 权限控制 + +**权限控制**是机器人在实际应用中需要解决的重点问题之一，`Nonebot `提供了十分完善且灵活的权限控制机制——` Permission `机制，这个机制与` Rule `。接下来我们将对这个机制进行简单的说明。 + +## 应用 + +如同` Rule `一样, ` Permission `可以在[注册事件响应器](../guide/creating-a-matcher)时添加` permission `参数来加以应用，这样` Nonebot `会在事件响应时检测事件主体的权限。下面我们以` SUPERUSER `为例，对该机制的应用做一下介绍。 + +```python +from nonebot.permission import SUPERUSER +from nonebot.adapters import Bot +from nonebot import on_command + +matcher = on_command('测试超管', permission=SUPERUSER) + + +@matcher.handle() +async def _(bot: Bot): + await matcher.send("超管命令测试成功") + + +@matcher.got("key1", "超管提问") +async def _(bot: Bot, event: Event): + await matcher.send("超管命令got成功") +``` + +在这段代码中，我们事件响应器指定了` SUPERUSER `这样一个权限，那么机器人只会响应超级管理员的` 测试超管 `命令，并且会响应该超级管理员的连续对话。 + +::: tip 提示 + +在这里需要强调的是，` Permission `与` Rule `的表现并不相同，` Rule `只会在初次响应时生效，在余下的对话中并没有限制事件；但是` Permission `会持续生效，在连续对话中会一直对事件主体加以限制。 + +::: + +## 进阶 + +` Permission `除了可以在注册事件响应器时加以应用，还可以在编写事件处理函数` handler `时主动调用，我们可以利用这个特性在一个` handler `里对不同权限的事件主体进行区别响应，下面我们以 ` CQHTTP `中的` GROUP_ADMIN `(普通管理员非群主)和` GROUP_OWNER `为例，说明下怎么进行主动调用。 + +```python +from nonebot.adapters.cqhttp import Bot +from nonebot.adapters.cqhttp.event import GroupMessageEvent +from nonebot.adapters.cqhttp.permission import GROUP_ADMIN, GROUP_OWNER +from nonebot import on_command + +matcher = on_command("测试权限") + + +@matcher.handle() +async def _(bot: Bot, event: GroupMessageEvent): + if await GROUP_ADMIN(bot, event): + await matcher.send("管理员测试成功") + elif await GROUP_OWNER(bot, event): + await matcher.send("群主测试成功") + else: + await matcher.send("群员测试成功") + +``` + +在这段代码里，我们并没有对命令的权限指定，这个命令会响应所有在群聊中的` 测试权限 `命令，但是在` handler `里，我们对两个` Permission `进行主动调用，从而可以对不同的角色进行不同的响应。 + +## 自定义 + +如同` Rule `一样, ` Permission `也是由非负数个` PermissionChecker `组成的，但只需其中一个返回` True `时就会匹配成功。下面则是` PermissionChecker `和` Permission `示例： + +```python +from nonebot.permission import Permission +from nonebot.adapters import Bot, Event + +async def async_checker(bot: Bot, event: Event) -> bool: + return True + +def sync_checker(bot: Bot, event: Event) -> bool: + return True + +def check(arg1, arg2): + + async def _checker(bot: Bot, event: Event) -> bool: + return bool(arg1 + arg2) + + return Permission(_checker) +``` + +`Permission` 和 `PermissionChecker` 之间可以使用 `或 |` 互相组合： + +```python +from nonebot.permission import Permission + +Permission(async_checker1) | sync_checker | async_checker2 +``` + +同样地，如果想用` Permission(*checkers) ` 包裹构造` Permission `，函数必须是异步的；但是在利用` 或 | `符号连接构造时，` Nonebot `会自动包裹同步函数为异步函数。 + From ca21fb8202963b589a8e2e6b59efead8305665cb Mon Sep 17 00:00:00 2001 From: AkiraXie Date: Thu, 20 May 2021 20:28:11 +0800 Subject: [PATCH 2/4] :memo: fix typo --- .DS_Store | Bin 0 -> 6148 bytes docs/.DS_Store | Bin 0 -> 6148 bytes docs/advanced/permission.md | 2 +- 3 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 .DS_Store create mode 100644 docs/.DS_Store diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..e7172bd4b252760cafb5721804cece7a728ba4e9 GIT binary patch literal 6148 zcmeHK-HsA56h37^2G$=;Oxzojx$zDO=&p$uCM*jVBx;Npy->q4Ko)jqr-T`nAY!=p z3G~8O@Hu<{9pV1PQP~ADG`a7}5##o4)LN{uF?DG`vF}%UsNrp47hd|Q3^{BQ z)FTOWsK0ZK)AfJSIL@1fBhOd3uinTXhEcivU8FYBnM+y6$vgQg`8TbBoVKD)Gzn{+ z@hg6M+KC39$v>CUKh1Z%7sLLvUAVC)gQznM`eQ{N_WFRlemM+!a$1vwvghH#NY06qJ^_~-x540!CP4} z!1B`i99vo$h39unBEKY%n?Oq7A}rh)#$iUZIu50By#1?S&ER8j55ew&UxG_ICO^St z&Ewo0J;UtmQk@KjUwtf!=$V$2M&{_Wf}*VAR!S%3USq@R9n|6 zcRm4piG7ZJf_3a3gFLVl9{xBcF8lAjVg1_03+MooYk07xvPMz|{8}raHu%rG?=wmaRX=%-v+wIAuBG+Fw-|QWqfBiQ8KKXHF9t8w0T*lT||H(Br<{tFI?`NsbPSHns zB?QrfgqFK0TtCq>jcXZBVF(E#i)SOn=EISX4r!Z^wiZS@1>+9P3VeiJeAl}09(4=O z?LKk~R$Sh}g+W&VSKL5`qxt=572s|kQqTKbn9egC-Tjw5*_F9GI7z-K26;@3OR=gdX25rR~ cSd5`hQ3KUuEv(`Qn)?wj7+mED{8s{h0jl%HA^-pY literal 0 HcmV?d00001 diff --git a/docs/advanced/permission.md b/docs/advanced/permission.md index b49c0981..01ca02e5 100644 --- a/docs/advanced/permission.md +++ b/docs/advanced/permission.md @@ -1,6 +1,6 @@ # 权限控制 -**权限控制**是机器人在实际应用中需要解决的重点问题之一，`Nonebot `提供了十分完善且灵活的权限控制机制——` Permission `机制，这个机制与` Rule `。接下来我们将对这个机制进行简单的说明。 +**权限控制**是机器人在实际应用中需要解决的重点问题之一，`Nonebot `提供了十分完善且灵活的权限控制机制——` Permission `机制。接下来我们将对这个机制进行简单的说明。 ## 应用 From 00dc72b6c4f39212364e8fc08d15cc9f22f9a9e3 Mon Sep 17 00:00:00 2001 From: StarHeartHunt Date: Thu, 20 May 2021 22:41:54 +0800 Subject: [PATCH 3/4] :fire: remove .DS_Store --- .DS_Store | Bin 6148 -> 0 bytes docs/.DS_Store | Bin 6148 -> 0 bytes 2 files changed, 0 insertions(+), 0 deletions(-) delete mode 100644 .DS_Store delete mode 100644 docs/.DS_Store diff --git a/.DS_Store b/.DS_Store deleted file mode 100644 index e7172bd4b252760cafb5721804cece7a728ba4e9..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6148 zcmeHK-HsA56h37^2G$=;Oxzojx$zDO=&p$uCM*jVBx;Npy->q4Ko)jqr-T`nAY!=p z3G~8O@Hu<{9pV1PQP~ADG`a7}5##o4)LN{uF?DG`vF}%UsNrp47hd|Q3^{BQ z)FTOWsK0ZK)AfJSIL@1fBhOd3uinTXhEcivU8FYBnM+y6$vgQg`8TbBoVKD)Gzn{+ z@hg6M+KC39$v>CUKh1Z%7sLLvUAVC)gQznM`eQ{N_WFRlemM+!a$1vwvghH#NY06qJ^_~-x540!CP4} z!1B`i99vo$h39unBEKY%n?Oq7A}rh)#$iUZIu50By#1?S&ER8j55ew&UxG_ICO^St z&Ewo0J;UtmQk@KjUwtf!=$V$2M&{_Wf}*VAR!S%3USq@R9n|6 zcRm4piG7ZJf_3a3gFLVl9{xBcF8lAjVg1_03+MooYk07xvPMz|{8}raHu%rG?=wmaRX=%-v+wIAuBG+Fw-|QWqfBiQ8KKXHF9t8w0T*lT||H(Br<{tFI?`NsbPSHns zB?QrfgqFK0TtCq>jcXZBVF(E#i)SOn=EISX4r!Z^wiZS@1>+9P3VeiJeAl}09(4=O z?LKk~R$Sh}g+W&VSKL5`qxt=572s|kQqTKbn9egC-Tjw5*_F9GI7z-K26;@3OR=gdX25rR~ cSd5`hQ3KUuEv(`Qn)?wj7+mED{8s{h0jl%HA^-pY From 01678005f076e884511e97b4b9686b6edb6eefda Mon Sep 17 00:00:00 2001 From: StarHeartHunt Date: Thu, 20 May 2021 22:45:35 +0800 Subject: [PATCH 4/4] :art: reformat docs --- docs/advanced/overloaded-handlers.md | 2 +- docs/advanced/permission.md | 40 +++++++++++++--------------- docs/guide/loading-a-plugin.md | 4 +-- 3 files changed, 22 insertions(+), 24 deletions(-) diff --git a/docs/advanced/overloaded-handlers.md b/docs/advanced/overloaded-handlers.md index 3d78def2..47fea384 100644 --- a/docs/advanced/overloaded-handlers.md +++ b/docs/advanced/overloaded-handlers.md @@ -61,4 +61,4 @@ async def _(bot: Bot, event: PrivateMessageEvent): await matcher.send("私聊消息事件响应成功！") ``` -只有触发事件符合的函数才会触发装饰器。 \ No newline at end of file +只有触发事件符合的函数才会触发装饰器。 diff --git a/docs/advanced/permission.md b/docs/advanced/permission.md index 01ca02e5..63c84535 100644 --- a/docs/advanced/permission.md +++ b/docs/advanced/permission.md @@ -1,17 +1,17 @@ # 权限控制 -**权限控制**是机器人在实际应用中需要解决的重点问题之一，`Nonebot `提供了十分完善且灵活的权限控制机制——` Permission `机制。接下来我们将对这个机制进行简单的说明。 +**权限控制**是机器人在实际应用中需要解决的重点问题之一，`Nonebot` 提供了十分完善且灵活的权限控制机制—— `Permission` 机制。接下来我们将对这个机制进行简单的说明。 ## 应用 -如同` Rule `一样, ` Permission `可以在[注册事件响应器](../guide/creating-a-matcher)时添加` permission `参数来加以应用，这样` Nonebot `会在事件响应时检测事件主体的权限。下面我们以` SUPERUSER `为例，对该机制的应用做一下介绍。 +如同 `Rule` 一样, `Permission` 可以在[注册事件响应器](../guide/creating-a-matcher)时添加 `permission` 参数来加以应用，这样 `Nonebot` 会在事件响应时检测事件主体的权限。下面我们以 `SUPERUSER` 为例，对该机制的应用做一下介绍。 ```python from nonebot.permission import SUPERUSER from nonebot.adapters import Bot from nonebot import on_command -matcher = on_command('测试超管', permission=SUPERUSER) +matcher = on_command("测试超管", permission=SUPERUSER) @matcher.handle() @@ -24,27 +24,26 @@ async def _(bot: Bot, event: Event): await matcher.send("超管命令got成功") ``` -在这段代码中，我们事件响应器指定了` SUPERUSER `这样一个权限，那么机器人只会响应超级管理员的` 测试超管 `命令，并且会响应该超级管理员的连续对话。 +在这段代码中，我们事件响应器指定了 `SUPERUSER` 这样一个权限，那么机器人只会响应超级管理员的 `测试超管` 命令，并且会响应该超级管理员的连续对话。 ::: tip 提示 -在这里需要强调的是，` Permission `与` Rule `的表现并不相同，` Rule `只会在初次响应时生效，在余下的对话中并没有限制事件；但是` Permission `会持续生效，在连续对话中会一直对事件主体加以限制。 +在这里需要强调的是，`Permission` 与 `Rule` 的表现并不相同， `Rule` 只会在初次响应时生效，在余下的对话中并没有限制事件；但是 `Permission` 会持续生效，在连续对话中会一直对事件主体加以限制。 ::: ## 进阶 -` Permission `除了可以在注册事件响应器时加以应用，还可以在编写事件处理函数` handler `时主动调用，我们可以利用这个特性在一个` handler `里对不同权限的事件主体进行区别响应，下面我们以 ` CQHTTP `中的` GROUP_ADMIN `(普通管理员非群主)和` GROUP_OWNER `为例，说明下怎么进行主动调用。 +`Permission` 除了可以在注册事件响应器时加以应用，还可以在编写事件处理函数 `handler` 时主动调用，我们可以利用这个特性在一个 `handler` 里对不同权限的事件主体进行区别响应，下面我们以 `CQHTTP` 中的 `GROUP_ADMIN` (普通管理员非群主)和 `GROUP_OWNER` 为例，说明下怎么进行主动调用。 ```python -from nonebot.adapters.cqhttp import Bot -from nonebot.adapters.cqhttp.event import GroupMessageEvent -from nonebot.adapters.cqhttp.permission import GROUP_ADMIN, GROUP_OWNER from nonebot import on_command +from nonebot.adapters.cqhttp import Bot +from nonebot.adapters.cqhttp import GroupMessageEvent +from nonebot.adapters.cqhttp import GROUP_ADMIN, GROUP_OWNER matcher = on_command("测试权限") - @matcher.handle() async def _(bot: Bot, event: GroupMessageEvent): if await GROUP_ADMIN(bot, event): @@ -53,31 +52,31 @@ async def _(bot: Bot, event: GroupMessageEvent): await matcher.send("群主测试成功") else: await matcher.send("群员测试成功") - + ``` -在这段代码里，我们并没有对命令的权限指定，这个命令会响应所有在群聊中的` 测试权限 `命令，但是在` handler `里，我们对两个` Permission `进行主动调用，从而可以对不同的角色进行不同的响应。 +在这段代码里，我们并没有对命令的权限指定，这个命令会响应所有在群聊中的 `测试权限` 命令，但是在 `handler` 里，我们对两个 `Permission` 进行主动调用，从而可以对不同的角色进行不同的响应。 ## 自定义 -如同` Rule `一样, ` Permission `也是由非负数个` PermissionChecker `组成的，但只需其中一个返回` True `时就会匹配成功。下面则是` PermissionChecker `和` Permission `示例： +如同 `Rule` 一样, `Permission` 也是由非负数个 `PermissionChecker` 组成的，但只需其中一个返回 `True` 时就会匹配成功。下面则是 `PermissionChecker` 和 `Permission` 示例： ```python -from nonebot.permission import Permission from nonebot.adapters import Bot, Event +from nonebot.permission import Permission async def async_checker(bot: Bot, event: Event) -> bool: - return True + return True def sync_checker(bot: Bot, event: Event) -> bool: - return True + return True def check(arg1, arg2): - async def _checker(bot: Bot, event: Event) -> bool: - return bool(arg1 + arg2) + async def _checker(bot: Bot, event: Event) -> bool: + return bool(arg1 + arg2) - return Permission(_checker) + return Permission(_checker) ``` `Permission` 和 `PermissionChecker` 之间可以使用 `或 |` 互相组合： @@ -88,5 +87,4 @@ from nonebot.permission import Permission Permission(async_checker1) | sync_checker | async_checker2 ``` -同样地，如果想用` Permission(*checkers) ` 包裹构造` Permission `，函数必须是异步的；但是在利用` 或 | `符号连接构造时，` Nonebot `会自动包裹同步函数为异步函数。 - +同样地，如果想用 `Permission(*checkers)` 包裹构造 `Permission` ，函数必须是异步的；但是在利用 `或 |` 符号连接构造时， `Nonebot` 会自动包裹同步函数为异步函数。 diff --git a/docs/guide/loading-a-plugin.md b/docs/guide/loading-a-plugin.md index 4ed55434..5f445a14 100644 --- a/docs/guide/loading-a-plugin.md +++ b/docs/guide/loading-a-plugin.md @@ -107,8 +107,8 @@ if __name__ == "__main__": ```json { - "plugins": ["nonebot_plugin_status", "awesome_bot.plugins.xxx"], - "plugin_dirs": ["awesome_bot/plugins"] + "plugins": ["nonebot_plugin_status", "awesome_bot.plugins.xxx"], + "plugin_dirs": ["awesome_bot/plugins"] } ```