nonebot2/website/versioned_docs/version-2.1.3/developer/plugin-publishing.mdx
noneflow[bot] b9392371c7 🔖 Release 2.1.3
2023-12-25 03:57:43 +00:00

203 lines
7.3 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
sidebar_position: 0
description: 在商店发布自己的插件
---
# 发布插件
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
NoneBot 为开发者提供了分享插件给大家使用的方式——商店。本章节将会介绍如何将我们写好的插件发布到商店。
:::tip 提示
本章节仅包含插件发布流程指导,插件开发请查阅前述章节。
:::
## 准备工作
### 插件命名规范
NoneBot 插件使用下述命名规范:
- 对于**项目名**,建议统一以 `nonebot-plugin-` 开头,之后为拟定的插件名字,词间用横杠 `-` 分隔;
- **项目名**用于代码仓库名称、PyPI 包的发布名称等;
- 本文使用 `nonebot-plugin-{your-plugin-name}` 为例。
- 对于**模块名**,建议与**项目名**一致,但词间用下划线 `_` 分隔,即统一以 `nonebot_plugin_` 开头,之后为拟定的插件名字;
- **模块名**用于程序导入使用,应为插件文件(夹)的名称;
- 本文使用 `nonebot_plugin_{your_plugin_name}` 为例。
### 项目结构
:::tip 提示
本段所述的项目结构仅作推荐,不做强制要求,保证实际可用性即可。
:::
插件程序本身结构可参考[插件结构](../tutorial/create-plugin.md#插件结构)一节,唯一区别在于,插件包可以直接处于项目顶层。
插件项目的一种组织结构如下:
```tree
📦 nonebot-plugin-{your-plugin-name}
├── 📂 nonebot_plugin_{your_plugin_name}
│ ├── 📜 __init__.py
│ └── 📜 config.py
├── 📜 pyproject.toml
└── 📜 README.md
```
#### 第三方项目模板
一些社区用户可能会分享自己制作的项目模板方便大家使用,如:[A-kirami/nonebot-plugin-template](https://github.com/A-kirami/nonebot-plugin-template) 等。
:::tip 提示
本文档**不保证**第三方模板的适用性。
根据项目模板提供的使用指导补全/修改相应内容后上传到 GitHub 即可。
:::
### 插件依赖
本段指导填写插件依赖,避免不正确的依赖信息导致插件无法正常工作。
依赖填写的基本原则:程序直接导入了什么第三方库,就添加什么第三方包依赖;能用哪些第三方库的特性,就根据使用的特性锁定第三方包版本。
:::caution 注意
1. 插件需要添加 `nonebot2` 为依赖以避免“幽灵依赖”;
2. 插件需要将使用的适配器加入依赖列表,如:使用 OneBot 适配器的插件应添加 `nonebot-adapter-onebot` 依赖;
3. 由于 `nonebot` 是指 `nonebot1` **而非** `nonebot2`,因此要注意**不要**将 `nonebot` 添加为插件的依赖,以免造成冲突;
4. 尽可能避免使用 `==` 锁定单一版本,增强与其它插件的兼容性。
:::
### 填写插件元数据
请注意,插件发布要求**必须**填写元数据才能通过审核。
下面是一个示例:
```python title=nonebot_plugin_{your_plugin_name}/__init__.py
from nonebot.plugin import PluginMetadata
from .config import Config
__plugin_meta__ = PluginMetadata(
name="{插件名称}",
description="{插件介绍}",
usage="{插件用法}",
type="{插件分类}",
# 发布必填,当前有效类型有:`library`(为其他插件编写提供功能),`application`(向机器人用户提供功能)。
homepage="{项目主页}",
# 发布必填。
config=Config,
# 插件配置项类,如无需配置可不填写。
supported_adapters={"~onebot.v11", "~telegram"},
# 支持的适配器集合,其中 `~` 在此处代表前缀 `nonebot.adapters.`,其余适配器亦按此格式填写。
# 若插件可以保证兼容所有适配器(即仅使用基本适配器功能)可不填写,否则应该列出插件支持的适配器。
)
```
:::caution 注意
`__plugin_meta__` 变量**必须**处于插件最外层(如 `__init__.py` 中),否则无法正常识别。
一般做法是在 `__init__.py` 中定义 `__plugin_meta__`。
:::
:::tip 提示
带花括号 `{}` 的内容需要自行替换,注意**一定要把原有的花括号去掉**。
:::
### 准备项目主页
通常可以使用 GitHub 项目页面作为项目主页,在 `README.md` 文件中编写插件介绍等内容。
内容大致包括:
- 插件功能介绍
- 安装方法(建议至少有 `nb-cli` 方式安装,**不要**使用旧式的 `bot.py` 配置)
- 插件配置项(若无可跳过)
- 插件设置的触发规则(若无可跳过)
- 插件的其它用法(按需编写)
:::tip 提示
可以参考[第三方项目模板](#第三方项目模板)。
:::
### 发布至 [PyPI](https://pypi.org)
根据选用的构建系统,在项目的 `pyproject.toml` 中填入必要信息后进行构建与发布。
:::tip 提示
不同构建工具的使用可能存在差别。本文仅以 [`pdm`](https://pdm.fming.dev/latest/),
[`poetry`](https://python-poetry.org/docs/), [`setuptools`](https://setuptools.pypa.io/en/latest/)
构建系统**本地构建与发布**为示例讲解,其余构建/管理工具等和自动化构建的用法请读者自行探索。
:::
<Tabs groupId="publishMethod">
<TabItem value="poetry" label="Poetry" default>
```bash
poetry publish --build # 构建并发布
# 等效于以下两个命令
poetry build # 只构建
poetry publish # 只发布先前的构建
```
</TabItem>
<TabItem value="pdm" label="PDM" default>
```bash
pdm publish # 构建并发布
# 等效于以下两个命令
pdm build # 只构建
pdm publish --no-build # 只发布先前的构建
```
</TabItem>
<TabItem value="setuptools" label="Setuptools (PEP 517)" default>
```bash
pip install build twine # 安装通用构建与发布工具
python -m build --sdist --wheel . # 只构建
twine upload dist/* # 只发布先前的构建
```
</TabItem>
</Tabs>
:::tip 提示
发布前建议自行测试构建包是否可用,避免遗漏代码文件或资源文件等问题。
:::
## 商店审核
### 提交申请
完成在 PyPI 的插件发布流程后,前往[商店](/store/plugins)页面,切换到插件页签,点击 **发布插件** 按钮。
在弹出的插件信息提交表单内,填入您所要发布的相应插件信息。请注意,如果插件需要必要配置项才能正常导入,请在“插件配置项”中填写必要的内容(请勿填写密钥等敏感信息)。
完成填写后,点击 **发布** 按钮,这将自动跳转 NoneBot 仓库内的“发布插件”页面。确认信息无误后点击页面下方的 `Submit new issue` 按钮进行最终提交即可。
### 等待插件审核
插件发布 Issue 创建后,将会经过 **NoneFlow Bot** 的自动前置检查,以确保插件信息正确无误、插件能被正确加载。
:::tip 提示
若插件检查未通过或信息有误,**不必**关闭当前 Issue。只需更新插件并上传到 PyPI/修改信息后在当前 Issue 追加任意内容的评论(如“已更新”等)即可重新触发插件检查。
:::
之后NoneBot 的维护者和一些插件开发者会初步检查插件代码,帮助减少该插件的问题。
完成这些步骤后,您的插件将会被自动合并到[商店](/store/plugins),而您也将成为 [**NoneBot 贡献者**](https://github.com/nonebot/nonebot2/graphs/contributors)的一员。