手把手带你构建一个现代化的 python 项目结构

简介

最近在搞一堆开源项目,同时面临着不断创建 python 项目的需求,故特意在 github 上逛了一圈,找到一个特别完善的 python-package-template,因源作者不再维护,因此笔者将其进行二次开发,对 windows 环境下做了特别的适配优化,并且完善了原有项目存在的一些问题。需要说明的是,这个项目可以很好地提升 python 开发的工程能力,含金量极高,下面笔者将介绍一下这个项目。

python-package-template 内置了单元测试、代码检查、格式化、包管理、pre-commit 配置、Github Actions 等众多方便的工具,可以很方便的管理 Python 项目

python-package-template

仓库地址:https://github.com/Undertone0809/python-package-template

快速上手

cookiecutter gh:Undertone0809/python-package-template --checkout v1.0.1

你只需要安装最新版本的 cookiecutter 😉

🚀 功能

在这个 cookiecutter 🍪 模板中,我们结合了最先进的库和 Python 最佳开发实践。

开发功能

部署功能

开源社区功能

🤯 如何使用

安装

开始使用模板之前,请确保更新 cookiecutter

pip install -U cookiecutter

然后进入你想要创建项目的目录,并运行:

cookiecutter gh:Undertone0809/python-package-template --checkout v1.0.1

输入变量

模板生成器会要求你填写一些变量。

输入变量及其默认值如下:

参数默认值描述
project_namepython-project在创建项目之前,请检查可能的名称的可用性
project_description基于 project_name你的项目的简要描述。
organization基于 project_name组织的名称。我们需要生成许可证,并在 pyproject.toml 中指定所有权。
licenseMITMITBSD-3GNU GPL v3.0Apache Software License 2.0 中的一个。
minimal_python_version3.7最低 Python 版本。可以是 3.73.83.9 中的一个。用于构建、GitHub 工作流和格式化工具 (blackisortpyupgrade)。
github_name基于 organization用于托管的 GitHub 用户名。还用于设置 README.mdpyproject.toml 和 GitHub 的模板文件。
email基于 organization用于 CODE_OF_CONDUCT.mdSECURITY.md 文件以及在 pyproject.toml 中指定项目所有权。
version0.1.0包的初始版本。请确保符合 Semantic Versions 规范。
line_length88每行的最大长度(用于 blackisort 的代码样式)。注意:此值必须介于 50 和 300 之间。
using_tsinghua_image_sourcefalse清华镜像源的 poetry 镜像源
create_example_templatecli如果选择 cli,生成器将创建一个简单的 CLI 应用程序,使用 TyperRich 库。其中一个选项是 clinone

所有输入值将保存在 cookiecutter-config-file.yml 文件中,以便你不会丢失它们。😉

演示

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

更多细节

你的项目将包含一个 README.md 文件,其中包含有关开发、部署等的说明。你可以在项目 README.md 模板中阅读更多信息。

初始设置

初始化 poetry

通过运行 pip install poetry & make install 来初始化 poetry

在创建项目后,它将出现在你的目录中,并显示关于如何初始化项目的消息。

初始化 pre-commit

如果在运行 make install 之前初始化 git 仓库,pre-commit 已经安装好了。如果没有初始化,可以再次运行 make install 来将 pre-commit 安装到 .git

包示例

想了解更多关于 Poetry 的信息吗?请查看 它的文档

关于 Poetry 的详细信息

Poetry 的 命令 非常直观和易于学习,例如:

  • poetry add numpy@latest
  • poetry run pytest
  • poetry publish --build

等等

CLI 示例

如果将 create_example_template 设置为 cli,模板将提供一个简单的 CLI 应用程序示例。它使用 TyperRich 来进行 CLI 输入验证和在终端中进行美观的格式化。

通过 make install(首选)或 poetry install 安装后,你可以尝试使用示例:

poetry run <project_name> --help
poetry run <project_name> --name Roman

构建和发布你的包

构建新版本的应用程序包含以下步骤:

  • 提升包的版本 poetry version <version>。你可以显式地传递新版本,也可以使用 majorminorpatch 等规则。有关更多详细信息,请参阅 Semantic Versions 规范。
  • 提交到 GitHub
  • 创建 GitHub release
  • 然后… 发布 🙂 poetry publish --build

Makefile 使用方法

Makefile 包含许多函数,用于加快开发速度。

1. 下载和删除 Poetry

下载并安装 Poetry:

make poetry-download

卸载 Poetry:

make poetry-remove
2. 安装所有依赖项和 pre-commit 钩子

安装依赖项:

make install

git init 之后安装 pre-commit 钩子:

make pre-commit-install
3. 代码样式

自动格式化使用 pyupgradeisortblack

make codestyle

# 或使用同义词
make formatting

仅进行代码样式检查,而不重写文件:

make check-codestyle

注意:check-codestyle 使用 isortblackdarglint

使用一条命令将所有开发库更新到最新版本:

make update-dev-deps
4. 代码安全性

make check-safety

此命令会运行 Poetry 的完整性检查,并使用 SafetyBandit 检测安全问题。

make check-safety
5. 类型检查

运行 mypy 静态类型检查器:

make mypy
6. 测试和覆盖率

运行 pytest

make test
7. 所有 linters

当然,有一个命令可以一次运行所有 linters:

make lint

与以下命令相同:

make test && make check-codestyle && make mypy && make check-safety
8. Docker

make docker-build

等同于:

make docker-build VERSION=latest

删除 Docker 镜像:

make docker-remove

有关 Docker 的更多信息,请参阅这里

9. 清理

删除 pycache 文件:

make pycache-remove

删除构建的包:

make build-remove

删除 .DS_STORE 文件:

make dsstore-remove

删除 .mypycache:

make mypycache-remove

或者,删除所有上述文件:

make cleanup

🎯 接下来做什么

好吧,这取决于你 💪🏻。我只能推荐一些帮助我的包和文章。

  • Typer 适用于创建 CLI 应用程序。
  • Rich 可以在终端中添加漂亮的格式化。
  • Pydantic - 使用 Python 类型提示进行数据验证和设置管理。
  • Loguru 使日志记录变得简单。
  • tqdm - 快速、可扩展的 Python 和 CLI 进度条。
  • IceCream 是一个用于调试的小型库。
  • orjson - 超快的 JSON 解析库。
  • Returns 使你的函数输出有意义、类型化和安全!
  • Hydra 是一个用于优雅配置复杂应用程序的框架。
  • FastAPI 是一个基于类型的异步 Web 框架。

文章:

📈 发布

你可以在 GitHub Releases 页面上查看可用的发布列表。

我们遵循 Semantic Versions 规范。

我们使用 Release Drafter。当合并 pull request 时,草稿式发布将保持更新,列出更改内容,准备发布。使用标签可以将 pull request 分类到发布说明中。

标签列表及其对应的标题

标签发布中的标题
enhancement, feature🚀 功能
bug, refactoring, bugfix, fix🔧 修复和重构
build, ci, testing📦 构建系统和 CI/CD
breaking💥 重大变更
documentation📝 文档
dependencies⬆️ 依赖项更新

🧪 待办事项

该模板将继续开发,并遵循最新的工具和最佳实践,以改进 Python 开发体验。

以下是尚未实现的一些事项: