【NoneBot2】第二章:基础插件编写指南第一节———前置知识

  1. 1. python基础
    1. 1.0.0.1. python程序语言设计(视频及网站:中国大学Mooc)
      1. 1.0.0.1.1. 优点:
      2. 1.0.0.1.2. 缺点:
    2. 1.0.0.2. 孙兴华zz(视频:B站)
      1. 1.0.0.2.1. 优点:
      2. 1.0.0.2.2. 缺点:
    3. 1.0.0.3. 菜鸟教程(网站:网站)
      1. 1.0.0.3.1. 优点:
      2. 1.0.0.3.2. 缺点:
  • 2. nonebot的目录结构
    1. 2.0.1. 常规文件
      1. 2.0.1.0.1. src文件夹(或以机器人的名字命名的文件夹)
      2. 2.0.1.0.2. .env.* 文件
      3. 2.0.1.0.3. bot.py 文件
      4. 2.0.1.0.4. pyproject.toml 文件
  • 2.0.2. 其他文件
    1. 2.0.2.0.1. docker相关的文件
    2. 2.0.2.0.2. 其他文件
  • 3. nonebot的插件
    1. 3.1. 插件放在哪?
      1. 3.1.0.0.1. site-packages
      2. 3.1.0.0.2. scr/plugins
  • 3.2. 插件的结构
    1. 3.2.0.0.1. 模块(module)
    2. 3.2.0.0.2. 包(package)

  • 在这个章节正式开始之前,我们首先需要为接下来的学习奠定一些基础。

    python基础

    由于nonebot是使用了 asyncio 的异步框架,并且使用了较多语法糖,相对来说并不适合新手入门,因此如果这个是你入门python之后的第一个实践项目,请做好十足的心理准备。
    在此推荐几个个人入门看的python教程

    python程序语言设计(视频及网站:中国大学Mooc)

    https://www.icourse163.org/course/BIT-268001

    优点:
    1. 北京理工大学出品,国家精品课程,目前仍在开课
    2. 面向非程序员,零基础人群
    3. 完全免费,没有第三方网站付费才能解锁题库啥的骚操作
    4. 节奏把控很好,能在短时间内快速上手
    5. 有配套练习
    6. 有专门的老师可以帮助答疑
    缺点:
    1. 第二周的课程实际完全用不到,属于是为了迎合大学课程特地加的一节,完全没必要去听
    2. 课程深度很浅,基本上就只是半只脚入了门的水平,不足以读懂大部分项目的文档(但是能看懂部分教程)
    3. 课程开始时间为2018年,可能已经部分过时了
    4. 如果只学这一个课程的话,可能无法看懂本教程的部分内容,完全不足以看懂官方文档。
    孙兴华zz(视频:B站)

    https://www.bilibili.com/video/BV1HE41157bu

    优点:
    1. 讲的非常简单易懂
    2. 面向非程序员,零基础人群
    3. 完全免费,没有第三方网站付费才能解锁题库啥的骚操作
    4. python相关教程很多,可以作为入门项目的库有不少
    缺点:
    1. 代码采用了大量中文变量,以及并不十分规范的格式,如果照抄有可能会被大佬嫌弃
    2. 深度并不足以阅读nonebot的源码,但是完全可以看懂此教程。
    3. python教程以及有段时间没更了,估计以后接着更的可能性也不高
    菜鸟教程(网站:网站)

    https://www.runoob.com/python3/python3-tutorial.html

    优点:
    1. 基础部分十分全面,进阶部分也有代码示例等
    2. 十分适合作为速查手册辅助学习
    3. 目前国内面对新手的教程向网站中最好的
    4. 适合有编程基础的快速上手
    缺点:
    1. 没有视频以及答疑
    2. 不适合完全没接触过编程的小白硬啃,需要配合上面的视频教程使用

    nonebot的目录结构

    nonebot的目录结构其实并不复杂,按照 官方文档 中的示例,我们可以看到如下的结构:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    AweSome-Bot
    ├── awesome_bot # 或是 src
    │ └── plugins
    ├── .env # 可选的
    ├── .env.dev # 可选的
    ├── .env.prod # 可选的
    ├── .gitignore
    ├── bot.py
    ├── docker-compose.yml
    ├── Dockerfile
    ├── pyproject.toml
    └── README.md

    我们可以把项目的文件分为如下两类:

    常规文件

    顾名思义,常规结构(当然有一些使用nonebot的单文件机器人)中机器人运行中不可或缺的文件,或是常规结构中无法直接删除的文件等。

    src文件夹(或以机器人的名字命名的文件夹)

    该文件夹是我们用于放置插件的文件夹,这个文件夹可以随意起名,甚至不是必须存在的,但为了代码的规范以及目录结构的工整,官方的指导建议是将插件放置于 src/plugins 文件夹下。
    如果没有特殊情况,个人建议按照官方的建议,将插件放置在指定位置,并且使用 scr 作为其名字而不是机器人的名字,例如 awesome_bot(上面的那个案例就是反例)。
    这样做的目的是为了达到较高的兼容性,否则部分依赖于路径的插件会无法正常工作

    .env.* 文件

    注意:
    在部分操作系统下,以 . 为首的文件会被隐藏,因此,我们需要一些设置才能直接看到这些文件,具体方法请善用搜索引擎自行查找。

    顾名思义,用于储存环境变量的文件,其中 .env 文件一般用于指向另外两个文件。其中的内容一般为 ENVIRONMENT=prodENVIRONMENT=dev 中的一种,分别指向下面介绍的两个配置文件。

    实际上,你可以在 .env 中直接填写配置,而不需要指向另外两个配置文件。在指向另外的文件的时候,.env 中的内容也会被添加至环境变量一同加载。如果配置文件中的内容有所冲突,此处可参考 官方文档 对此的描述:

    bot.py 文件( nonebot.init ) > 系统环境变量 > .env, .env.* 文件

    .env.prod 文件是用于 生产环境 的环境变量存储,也就是日常使用的环境。
    .env.dev 文件是用于 测试环境 的环境变量存储,也就是编写插件或者其他测试的时候使用的,一般来说会开启一些实验性功能以及更加详细的log,能为我们debug提供更多信息。

    注意:
    这两个文件中起决定性差距的并不是文件名,而且其中的内容,例如你可以在 .env.prod 中开启debug模式,也可以不在 .env.dev 中开启任何测试性内容。
    但从实际出发,个人是十分不推荐这么做的,请务必不要这么做!!!

    在实际使用中,我们一般来说可以把无论哪个环境都需要加载的环境变量填写到 .env 中,对于某种特定环境变量填写在对应的环境变量中。

    bot.py 文件

    相当于机器人的心脏,在这个文件中执行了机器人的初始化以及插件加载等操作。
    由于其中的代码与其他文件和其他插件有较强的的关联性,因此不在此单独说明。

    pyproject.toml 文件

    项目插件配置文件,一般来说是存储一些项目信息的文件,包括自动导入插件等操作。
    bot.py 中对应的加载代码为 nonebot.load_from_toml("pyproject.toml")

    重要
    以下纯属依据我浅薄的经验得出的个人观点,希望各位结合实际合理选择操作方法,而不是单纯听信我的一家之言,盲目反对官方的目录结构安排不合理。

    但我个人是并不建议使用这个文件进行自动导入的,理由如下:

    1. 我们可以用其他更加直观可控的方法进行插件加载等操作,例如 nonebot.load_plugin('插件名字')
    2. 这个文件是配合 nb-cli 中提供的脚手架进行使用的,相对第一条中的方法有编辑器进行语法提示来说有更高的翻车风险。
    3. 最重要的一点,在部分环境下,pyproject.toml不能正常的导入插件(详细可见视频),也就是在不同的环境下可能会导致完全不一样的结果。

    因此,我一般会在 bot.py 中直接将 nonebot.load_from_toml("pyproject.toml") 这行代码直接注释掉或删除。

    其他文件

    在常规的部署方法下,该部分的文件可直接删除,而不会对机器人的正常使用造成任何影响。

    docker相关的文件

    docker-compose.yml 以及 Dockerfile
    官方提供的 docker 支持,在之后可能会出的docker部署教程会介绍。

    其他文件

    .gitignore 以及 README.md
    类似于谁都不会看的说明书吧,对机器人来说没什么用。 ( ̄ε(# ̄)

    nonebot的插件

    官方文档中对插件的介绍
    假如说使用nonebot搭建的机器人是一个人的话,nonebot可以理解为这个机器人的身体,能够做出各种各样的行为,但并不能产生自我意识。而插件则是这个人体中的“意识”,仅凭自己是无法独立存在的,但可以依赖身体做出行为,对身体进行指导。

    插件放在哪?

    理论上,你放在哪里都可以,就像你可以把Windows中的程序安装在任何系统允许的位置。
    但从可读性以及历史角度出发,nonebot中的插件一般来说有两个相对固定的存放位置

    site-packages

    也就是python的第三方库的存放位置,这里可以直接使用 nonebot.load_plugin() 来进行载入,一般来说,你从插件商店下载的插件就会存在这里。

    scr/plugins

    上文中提及到的目录,在此不再次赘述。可以使用 nonebot.load_plugins("src/plugins") 来加载该文件夹中的插件。

    注意!
    如果插件的名字首个字符是 _ 的话,那么这个插件将不会被 “自动加载” ,但仍可以使用单独加载的方式进行载入。

    插件的结构

    在nonebot中,插件可以以模块(module)或包(package)的形式导入,这个相信对于编写过多文件脚本的同学并不陌生,这里的模块形式和包形式与python中的定义一致。

    模块(module)

    也就是单文件形式的python脚本,例如下方展示的名为 my_plugin 的插件。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    AweSome-Bot
    ├── src
    │ └── plugins
    | └── my_plugin.py
    ├── .env
    ├── .env.dev
    ├── .env.prod
    ├── .gitignore
    ├── bot.py
    ├── docker-compose.yml
    ├── Dockerfile
    ├── pyproject.toml
    └── README.md

    相对于包形式的插件,模块形式的插件更简单,但相对的只能在一个文件中塞下全部代码,因此除非十分简单的插件,不建议使用该形式。

    包(package)

    以一个文件夹形式存在的包,例如下方展示的名为 my_plugin 的插件。

    值得注意的是,在python中,一个合法的包中必须含有一个 __init__.py ,即便其中一个字都没有也不能省略。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    AweSome-Bot
    ├── src
    │ └── plugins
    | └── my_plugin
    | └── __init__.py
    | └── function.py
    ├── .env
    ├── .env.dev
    ├── .env.prod
    ├── .gitignore
    ├── bot.py
    ├── docker-compose.yml
    ├── Dockerfile
    ├── pyproject.toml
    └── README.md

    相对于模块形式的插件,包形式的插件更加灵活美观,是个人比较推荐的插件形式。