手把手带你构建一个现代化的 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 最佳开发实践。

开发功能

支持 Python 3.7 及更高版本。
使用 Poetry 作为依赖管理器。请查看 pyproject.toml 和 setup.cfg 中的配置。
使用 black、isort 和 pyupgrade 进行自动代码格式化。
预配置的 pre-commit 钩子，用于代码格式化。
使用 mypy 进行类型检查，使用 darglint 进行文档字符串检查，使用 safety 和 bandit 进行安全检查。
使用 pytest 进行测试。
预配置的 .editorconfig、.dockerignore 和 .gitignore 文件。你不需要担心这些事情。

部署功能

GitHub 集成：问题和 PR 模板。
使用预定义的构建工作流程作为默认的 CI/CD。
已经设置好安全检查、代码格式检查、代码格式化、测试、linting、Docker 构建等的所有内容，使用 Makefile。更多细节请参阅 makefile-usage。
为你的包提供 Dockerfile。
使用 @dependabot 始终保持依赖项最新。你只需要启用它。
使用 Release Drafter 自动生成发布说明。你可以在 release-drafter.yml 中查看标签列表。与 Semantic Versions 规范完美配合。

开源社区功能

预配置的 Pull Requests 模板和几个 Issue 模板。
自动生成文件，如：LICENSE、CONTRIBUTING.md、CODE_OF_CONDUCT.md 和 SECURITY.md。
使用 Stale bot 在一段时间内自动关闭未处理的问题（你只需要设置免费计划）。配置在这里。
使用 Release Drafter 自动生成发布说明。
使用 Semantic Versions 规范和 Release Drafter。

🤯 如何使用

安装

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

pip install -U cookiecutter

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

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

输入变量

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

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

参数	默认值	描述
`project_name`	`python-project`	在创建项目之前，请检查可能的名称的可用性。
`project_description`	基于 `project_name`	你的项目的简要描述。
`organization`	基于 `project_name`	组织的名称。我们需要生成许可证，并在 `pyproject.toml` 中指定所有权。
`license`	`MIT`	`MIT`、`BSD-3`、`GNU GPL v3.0` 和 `Apache Software License 2.0` 中的一个。
`minimal_python_version`	`3.7`	最低 Python 版本。可以是 `3.7`、`3.8` 或 `3.9` 中的一个。用于构建、GitHub 工作流和格式化工具 (`black`、`isort` 和 `pyupgrade`)。
`github_name`	基于 `organization`	用于托管的 GitHub 用户名。还用于设置 `README.md`、`pyproject.toml` 和 GitHub 的模板文件。
`email`	基于 `organization`	用于 `CODE_OF_CONDUCT.md`、`SECURITY.md` 文件以及在 `pyproject.toml` 中指定项目所有权。
`version`	`0.1.0`	包的初始版本。请确保符合 Semantic Versions 规范。
`line_length`	88	每行的最大长度（用于 `black` 和 `isort` 的代码样式）。注意：此值必须介于 50 和 300 之间。
`using_tsinghua_image_source`	false	清华镜像源的 poetry 镜像源
`create_example_template`	`cli`	如果选择 `cli`，生成器将创建一个简单的 CLI 应用程序，使用 `Typer` 和 `Rich` 库。其中一个选项是 `cli`、`none`

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

演示

初始设置

初始化 `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 应用程序示例。它使用 Typer 和 Rich 来进行 CLI 输入验证和在终端中进行美观的格式化。

通过 make install（首选）或 poetry install 安装后，你可以尝试使用示例：

poetry run <project_name> --help

poetry run <project_name> --name Roman

构建和发布你的包

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

提升包的版本 poetry version <version>。你可以显式地传递新版本，也可以使用 major、minor 或 patch 等规则。有关更多详细信息，请参阅 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. 代码样式

自动格式化使用 pyupgrade、isort 和 black。

make codestyle

# 或使用同义词
make formatting

仅进行代码样式检查，而不重写文件：

make check-codestyle

注意：check-codestyle 使用 isort、black 和 darglint 库

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

make update-dev-deps

4. 代码安全性

make check-safety

此命令会运行 Poetry 的完整性检查，并使用 Safety 和 Bandit 检测安全问题。

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 Actions 文档。
也许你想在提交名称中添加 gitmoji。这真的很有趣。😄

📈 发布

你可以在 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 开发体验。

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

测试覆盖率报告（Codecov？）。
当创建新的 GitHub 发布时，自动将你的包上传到 PyPI。
自动创建和部署文档到 GitHub 页面。我正在研究 MkDocs 和 Material Design 主题，以及 mkdocstrings。
使用 Radon 进行代码度量。
使用 interrogate 进行文档字符串覆盖率。
使用 dockerfilelint 对 Dockerfile 进行 linting。
Sourcerer 的名人堂。
使用 Release Drafter 自动生成发布说明。
一些高级的 Python linting（？）。
对 cookiecutter 模板进行端到端测试和验证。
添加 Invoke。
添加 Earthly。

目录CONTENT

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

简介

python-package-template

快速上手

🚀 功能

开发功能

部署功能

开源社区功能

🤯 如何使用

安装

输入变量

演示

更多细节

初始设置

初始化 `poetry`

初始化 `pre-commit`

包示例

CLI 示例

构建和发布你的包

Makefile 使用方法

🎯 接下来做什么

📈 发布

标签列表及其对应的标题

🧪 待办事项

评论区

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

简介

python-package-template

快速上手

🚀 功能

开发功能

部署功能

开源社区功能

🤯 如何使用

安装

输入变量

演示

更多细节

初始设置

初始化 poetry

初始化 pre-commit

包示例

CLI 示例

构建和发布你的包

Makefile 使用方法

🎯 接下来做什么

📈 发布

标签列表及其对应的标题

🧪 待办事项

评论区

初始化 `poetry`

初始化 `pre-commit`