diff --git a/website/docs/advanced/plugin-info.md b/website/docs/advanced/plugin-info.md index bb83489b..ef3c1ecd 100644 --- a/website/docs/advanced/plugin-info.md +++ b/website/docs/advanced/plugin-info.md @@ -50,7 +50,7 @@ __plugin_meta__ = PluginMetadata( - `type`:插件类别,发布插件必填。当前有效类别有:`library`(为其他插件编写提供功能),`application`(向机器人用户提供功能); - `homepage`:插件项目主页,发布插件必填; -- `config`:插件的[配置类](../appendices/config.mdx#插件配置),如无配置类可不填; +- `config`:插件的[配置类](../appendices/config.mdx#插件配置),发布插件时如有配置类则必须填写; - `supported_adapters`:支持的适配器模块名集合,若插件只使用了 NoneBot 基本抽象,应显式填写 `None`; - `extra`:一个字典,可以用于存储任意信息。其他插件可以通过约定 `extra` 字典的键名来达成收集某些特殊信息的目的。 diff --git a/website/docs/developer/plugin-publishing.mdx b/website/docs/developer/plugin-publishing.mdx index 5bf2ca80..1aa7efae 100644 --- a/website/docs/developer/plugin-publishing.mdx +++ b/website/docs/developer/plugin-publishing.mdx @@ -13,7 +13,7 @@ NoneBot 为开发者提供了分享插件的官方商店。本指南囊括**从 :::warning 警告 如果你的插件只是满足自用需求,则完全可以选择**不发布插件**。发布插件**不是**使用插件的必要条件。 -NoneBot 社区对于插件有一定质量要求,对于不符合要求的插件,社区成员有权要求整改,直至符合要求后才能通过审核;如果长期未更新整改,社区有权关闭当前请求,之后如需发布请重新提交发布插件请求。相应的质量要求会在本章节介绍。 +NoneBot 社区对于插件有一定质量要求,对于不符合要求的插件,社区成员将会要求修改,直至符合要求后才能通过审核;如果长期未更新整改,社区将会关闭当前请求,之后如需发布请重新提交发布插件请求。相应的要求会在本章节以下部分介绍。 ::: :::tip 提示 @@ -371,7 +371,7 @@ twine upload dist/* # 只发布先前的构建 #### 依赖其他插件 -如果插件依赖其他插件提供的功能,则**必须**在代码中使用 `require()` 来引入该插件,然后才能 `import` 该插件提供的功能。具体细节参阅[跨插件访问](../advanced/requiring.md) 。 +如果插件依赖其他插件提供的功能,则**必须**在代码中使用 `require()` 来引入该插件,然后才能 `import` 该插件提供的功能。具体细节参阅[跨插件访问](../advanced/requiring.md)。 使用示例如下: @@ -385,7 +385,7 @@ from nonebot_plugin_apscheduler import scheduler #### 不能零配置加载的插件 -如果插件需要必要配置项才能正常导入,则**必须**在插件元数据中填写 `config` 字段,并且在商店提交表单中填写必要的配置项内容。 +如果插件需要必要配置项才能正常导入,则**必须**在商店提交表单中填写必要的配置项内容。 但一种更好的做法是,**将插件设计为零配置即可加载**(允许缺少必要配置项时插件仍能正常导入,但不执行需要相应配置项的功能),尤其是对于一些必要配置含有敏感信息(如密钥、Token、API Key 等)的插件。这样可以避免在商店提交表单时填写敏感信息的风险。 @@ -414,7 +414,7 @@ __plugin_meta__ = PluginMetadata( # 发布必填。 config=Config, - # 插件配置项类,如无需配置可不填写。 + # 插件配置项类,如果有配置类则必须填写。 supported_adapters={"~onebot.v11"}, # 支持的适配器集合,其中 `~` 在此处代表前缀 `nonebot.adapters.`,其余适配器亦按此格式填写。 @@ -456,10 +456,6 @@ __plugin_meta__ = PluginMetadata( ) ``` -## 质量要求 - -以下内容**强烈建议**完成,否则社区成员有权要求整改: - ### 准备项目主页 通常可以使用 GitHub 项目页面作为项目主页,在 `README.md` 文件中编写插件介绍等内容。 @@ -476,6 +472,10 @@ __plugin_meta__ = PluginMetadata( - 插件的其它用法(按需编写) - 效果图、权限说明(按需编写) +## 质量要求 + +以下内容**强烈建议**完成,否则社区成员将会要求整改: + ### 依赖管理原则 - **必须**包含 `nonebot2`。 @@ -488,13 +488,51 @@ __plugin_meta__ = PluginMetadata( NoneBot 是一个异步框架,插件中**禁止**使用任何可能阻塞事件循环的同步操作,例如: - 同步 HTTP 请求(如 `requests` 库); -- 同步文件操作(如 `open()` 函数); -- 其他可能阻塞事件循环的操作。 -| 操作类别 | 禁止的同步操作示例 | 推荐的异步操作示例 | -| --- | --- | --- | -| HTTP 请求 | `requests.get("https://api.example.com/data")` | `async with httpx.AsyncClient() as client: response = await client.get("https://api.example.com/data")` | -| 文件操作 | `with open("data.txt", "r") as file: data = file.read()` | `async with aiofiles.open("data.txt", "r") as file: data = await file.read()` | + **推荐**操作(以 `httpx` 为例): + + ```python + import httpx + + async with httpx.AsyncClient() as client: + response = await client.get("https://api.example.com/data") # 异步操作,不阻塞机器人 + ``` + + **禁止**操作: + + ```python + import requests + + requests.get("https://api.example.com/data") # 同步操作,会阻塞机器人 + ``` + +- 其他可能长时间运行阻塞事件循环的操作。 + +### 本地文件存储 + +如果插件需要在本地存储数据、配置或缓存文件,**必须**使用 [`nonebot-plugin-localstore`](https://github.com/nonebot/plugin-localstore) 管理,具体细节参阅[本地存储](../best-practice/data-storing.md)章节。 + +参考示例: + +```python title=nonebot_plugin_weather/__init__.py +from pathlib import Path +from nonebot import require +require("nonebot_plugin_localstore") + +import nonebot_plugin_localstore as store + +# 获取插件缓存文件(夹)路径 +weather_cache_dir: Path = store.get_plugin_cache_dir() +weather_cache_file: Path = store.get_plugin_cache_file("cache.json") + +# 获取插件配置文件(夹)路径 +weather_config_dir: Path = store.get_plugin_config_dir() +weather_config_file: Path = store.get_plugin_config_file("config.toml") + +# 获取插件数据文件(夹)路径 +weather_data_dir: Path = store.get_plugin_data_dir() +weather_data_file: Path = store.get_plugin_data_file("resource-index.json") +``` ## 商店审核