后端插件开发教程文档

前提

1. 确定插件名称，如：dvadmin-celery
2. 创建对应插件的git仓库 (如：https://gitee.com/huge-dream/dvadmin-celery)
3. 进入插件目录 cd backend/plugins/
4. git clone https://gitee.com/huge-dream/dvadmin-celery
5. cd backend/plugins/dvadmin-celery

步骤

以下以 dvadmin-celery 插件为例

1. 编写对应插件内容

在plugins/dvadmin-celery/目录下编写自己的内容

注：每个文件夹下必须存在__init__.py文件，否则其文件夹无法build

参考：https://gitee.com/huge-dream/dvadmin-celery

2. 创建plugins/dvadmin-celery/pyproject.toml文件

[build-system]
requires = [
    "setuptools>=42",
    "wheel"
]
build-backend = "setuptools.build_meta"

3. 创建 plugins/dvadmin-celery/setup.py 文件

setup.py 是 setuptools 的构建脚本，用于告知 setuptools 我们要上传到PYPI的库的信息（库名、版本信息、描述、环境需求等）

下面是 setup.py 的示例

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="dvadmin-celery",
    version="1.0.0",
    author="DVAdmin",
    author_email="liqiang@django-vue-admin.com",
    description="适用用 django-vue-admin 的celery异步插件",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://gitee.com/huge-dream/dvadmin-celery",
    packages=setuptools.find_packages(),
    python_requires='>=3.6, <4',
    install_requires=["django-celery-beat>=2.2.1", "tenant-schemas-celery>=1.0.1", "django-redis>=5.0.0",
                      "django-celery-results>=2.2.0"],
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
)

参数解析：

--name 包名称------------生成的egg名称
--version (-V) 包版本----生成egg包的版本号
--author 程序的作者------包的制作者名字
--author_email 程序的作者的邮箱地址
--maintainer 维护者
--maintainer_email 维护者的邮箱地址
--url 程序的官网地址
--license 程序的授权信息
--description 程序的简单描述-------程序的概要介绍
--long_description 程序的详细描述---程序的详细描述
--platforms 程序适用的软件平台列表
--classifiers 程序的所属分类列表
--keywords 程序的关键字列表
--packages 需要处理的包目录（包含__init__.py的文件夹）-------和setup.py同一目录下搜索各个含有 init.py的包
--py_modules 需要打包的python文件列表
--download_url 程序的下载地址
--cmdclass
--data_files 打包时需要打包的数据文件，如图片，配置文件等
--scripts 安装时需要执行的脚步列表
--package_dir 告诉setuptools哪些目录下的文件被映射到哪个源码包。一个例子：package_dir = {'': 'lib'}，表示“root package”中的模块都在lib 目录中。
--requires 定义依赖哪些模块
--provides定义可以为哪些模块提供依赖
--find_packages() 对于简单工程来说，手动增加packages参数很容易，刚刚我们用到了这个函数，它默认在和setup.py同一目录下搜索各个含有 init.py的包。其实我们可以将包统一放在一个src目录中，另外，这个包内可能还有aaa.txt文件和data数据文件夹。另外，也可以排除一些特定的包 find_packages(exclude=[".tests", ".tests.", "tests.", "tests"])
--install_requires = ["requests"] 需要安装的依赖包
--entry_points 动态发现服务和插件

4. 创建 plugins/dvadmin-celery/README.md ，向其写入自己对该库的简介、描述、操作步骤等

# Example Package
https://gitee.com/huge-dream/dvadmin-celery/blob/master/README.md

5. 创建 plugins/dvadmin-celery/LICENSE ，对于每一个创建的库来说 LICENSE 是很重要的，这告诉大 家我们的库能用在什么方面（商用之类的）还有免责啊之类的；一般来说我们选择MIT

下面是 setup.py 的示例 (把下面year替换当前年份，fullname 设置为空间名)

MIT License

Copyright (c) [year] [fullname]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

MIT LICENSE 的大概意思是

• 软件可以随便用，随便改
• 可以免费，可以收费
• 软件的源文件里必须有这个许可证文档
• 我提供这个软件不是为了犯法，你要用它来犯法，那与我无关
• 你用这个软件犯事了，责任全在你自己，与其他贡献者无关

6. 最终目录结构

├── __init__.py
└── dvadmin-celery
    ├── LICENSE
    ├── README.en.md
    ├── README.md
    ├── dvadmin_celery
    │   ├── __init__.py
    │   ├── admin.py
    │   ├── apps.py
    │   ├── settings.py
    │   ├── urls.py
    │   └── views
    │       ├── __init__.py
    │       ├── crontab_schedule.py
    │       ├── interval_schedule.py
    │       └── periodic_task.py
    ├── pyproject.toml
    └── setup.py

7. 确保我们已安装最新setuptools 和 wheel和twine ，下面是安装/更新命令

python3 -m pip install --user --upgrade setuptools wheel twine

8. 打包的我们的库/项目

python3 setup.py sdist bdist_wheel

此时在当前目录我们会看到以下：

dist/
  dvadmin_celery-1.0.0-py3-none-any.whl
  dvadmin-celery-1.0.0.tar.gz

9. 发布到插件市场

• 压缩dist文件夹，命名为 dvadmin-celery-1.0.0.zip；
• 登录 插件市场，进行发布

参考文档：

https://zhuanlan.zhihu.com/p/79164800

https://packaging.python.org/en/latest/tutorials/packaging-projects/