From 9d7da873c4c67d4078dd66d9076587e3019ff889 Mon Sep 17 00:00:00 2001 From: yanyongyu Date: Sat, 7 Nov 2020 12:36:47 +0800 Subject: [PATCH] :memo: add plugin load doc --- docs/.vuepress/config.js | 13 +++-- docs/README.md | 2 +- docs/guide/loading-a-plugin.md | 95 ++++++++++++++++++++++++++++++++++ docs/guide/writing-a-plugin.md | 32 ------------ nonebot/plugins/base.py | 10 ++-- 5 files changed, 111 insertions(+), 41 deletions(-) create mode 100644 docs/guide/loading-a-plugin.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index f2656b4d..15bea39f 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -86,8 +86,7 @@ module.exports = context => ({ sidebar: { "/guide/": [ { - title: "指南", - path: "", + title: "开始", collapsable: false, sidebar: "auto", children: [ @@ -95,7 +94,15 @@ module.exports = context => ({ "installation", "getting-started", "creating-a-project", - "basic-configuration", + "basic-configuration" + ] + }, + { + title: "编写插件", + collapsable: false, + sidebar: "auto", + children: [ + "loading-a-plugin", "writing-a-plugin" ] } diff --git a/docs/README.md b/docs/README.md index e568de9f..a1607904 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,7 +3,7 @@ home: true heroImage: /logo.png tagline: An asynchronous QQ bot framework. actionText: 开始使用 -actionLink: /guide/ +actionLink: guide/ features: - title: 简洁 details: 提供极其简洁易懂的 API，使你可以毫无压力地开始验证你的绝佳创意，只需编写最少量的代码，即可实现丰富的功能。 diff --git a/docs/guide/loading-a-plugin.md b/docs/guide/loading-a-plugin.md new file mode 100644 index 00000000..bb7db02d --- /dev/null +++ b/docs/guide/loading-a-plugin.md @@ -0,0 +1,95 @@ +# 加载插件 + +在 [创建一个完整的项目](creating-a-project) 一章节中，我们已经创建了插件目录 `awesome_bot/plugins`，现在我们在机器人入口文件中加载它。当然，你也可以单独加载一个插件。 + +## 加载内置插件 + +在 `bot.py` 文件中添加以下行： + +```python{5} +import nonebot + +nonebot.init() +# 加载 nonebot 内置插件 +nonebot.load_bulitin_plugins() + +app = nonebot.get_asgi() + +if __name__ == "__main__": + nonebot.run() +``` + +这将会加载 nonebot 内置的插件，它包含： + +- 命令 `say`：可由**superuser**使用，可以将消息内容由特殊纯文本转为富文本 +- 命令 `echo`：可由任何人使用，将消息原样返回 + +以上命令均需要指定机器人，即私聊、群聊内@机器人、群聊内称呼机器人昵称。参考 [Rule: to_me](../api/rule.md#to-me) + +## 加载插件目录 + +在 `bot.py` 文件中添加以下行： + +```python{5} +import nonebot + +nonebot.init() +# 加载插件目录，该目录下为各插件，以下划线开头的插件将不会被加载 +nonebot.load_plugins("awesome_bot/plugins") + +app = nonebot.get_asgi() + +if __name__ == "__main__": + nonebot.run() +``` + +:::tip 提示 +加载插件目录时，目录下以 `_` 下划线开头的插件将不会被加载！ +::: + +:::warning 提示 +**插件不能存在相同名称！** +::: + +:::danger 警告 +插件间不应该存在过多的耦合，如果确实需要导入某个插件内的数据，可以使用如下两种方法： + +1. (推荐) `from plugin_name import xxx` 而非 `from awesome_bot.plugins.plugin_name import xxx` +2. 在需要导入其他插件的文件中添加 `__package__ = "plugins"; from .plugin_name import xxx` (将共同的上层目录设定为父包后使用相对导入) + +具体可以参考：[nonebot/nonebot2#32](https://github.com/nonebot/nonebot2/issues/32) +::: + +## 加载单个插件 + +在 `bot.py` 文件中添加以下行： + +```python{5,7} +import nonebot + +nonebot.init() +# 加载一个 pip 安装的插件 +nonebot.load_plugin("nonebot_plugin_status") +# 加载本地的单独插件 +nonebot.load_plugin("awesome_bot.plugins.xxx") + +app = nonebot.get_asgi() + +if __name__ == "__main__": + nonebot.run() +``` + +## 子插件(嵌套插件) + + + +~~待填坑~~ + +## 运行结果 + +尝试运行 `nb run` 或者 `python bot.py`，可以看到日志输出了类似如下内容： + +```plain +09-19 21:51:59 [INFO] nonebot | Succeeded to import "nonebot.plugins.base" +09-19 21:51:59 [INFO] nonebot | Succeeded to import "plugin_in_folder" +``` diff --git a/docs/guide/writing-a-plugin.md b/docs/guide/writing-a-plugin.md index 42657d9d..9953bfe7 100644 --- a/docs/guide/writing-a-plugin.md +++ b/docs/guide/writing-a-plugin.md @@ -2,38 +2,6 @@ 本章将以一个天气查询插件为例，教学如何编写自己的命令。 -## 加载插件 - -在 [创建一个完整的项目](creating-a-project) 一章节中，我们已经创建了插件目录 `awesome_bot/plugins`，现在我们在机器人入口文件中加载它。当然，你也可以单独加载一个插件。 - -:::tip 提示 -加载插件目录时，目录下以 `_` 下划线开头的插件将不会被加载！ -::: - -在 `bot.py` 文件中添加以下行： - -```python{5,7} -import nonebot - -nonebot.init() -# 加载单独的一个插件，参数为合法的python包名 -nonebot.load_plugin("nonebot.plugins.base") -# 加载插件目录，该目录下为各插件，以下划线开头的插件将不会被加载 -nonebot.load_plugins("awesome_bot/plugins") - -app = nonebot.get_asgi() - -if __name__ == "__main__": - nonebot.run() -``` - -尝试运行 `nb run` 或者 `python bot.py`，可以看到日志输出了类似如下内容： - -```plain -09-19 21:51:59 [INFO] nonebot | Succeeded to import "nonebot.plugins.base" -09-19 21:51:59 [INFO] nonebot | Succeeded to import "plugin_in_folder" -``` - ## 创建插件 现在我们已经有了一个空的插件目录，我们可以开始创建插件了！插件有两种形式 diff --git a/nonebot/plugins/base.py b/nonebot/plugins/base.py index 075ddd20..67ed40af 100644 --- a/nonebot/plugins/base.py +++ b/nonebot/plugins/base.py @@ -26,9 +26,9 @@ echo = on_command("echo", to_me()) @echo.handle() async def echo_escape(bot: Bot, event: Event, state: dict): - Message = event.message.__class__ - MessageSegment = event.message[0].__class__ + # Message = event.message.__class__ + # MessageSegment = event.message[0].__class__ - message = Message().append( # type: ignore - MessageSegment.text(str(event.message))) - await bot.send(message=message, event=event) + # message = Message().append( # type: ignore + # MessageSegment.text(str(event.message))) + await bot.send(message=event.message, event=event)