手把手带你构建一个现代化的 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 文件中，以便你不会丢失它们。

演示

更多细节

你的项目将包含一个 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 应用程序示例。它使用 Typer 和 Rich 来进行 CLI 输入验证和在终端中进行美观的格式化。

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

poetry run <project_name> --help

poetry run <project_name> --name Roman

构建和发布你的包

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

• 提升包的版本 poetry 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。