Python 包项目生成器
April 2, 2025 · View on GitHub
Python 包项目生成器
你的下一个 Python 包需要一个前沿的项目结构。
这个版本是从 https://github.com/TezRomacH/python-package-template 派生的。与原项目相比，当前项目提供了更好的 Windows 兼容性和更快的 lint 构建，以及更加轻量化的创建方式。
📚 文档
完整文档请访问：https://p3g.zeeland.top
🚀 特性
在这个 cookiecutter 🍪 模板中，我们结合了最先进的库和 Python 最佳开发实践。
开发特性
- 支持
Python 3.7及更高版本。 - 使用
Poetry作为依赖管理器。参见pyproject.toml和setup.cfg中的配置。 - 更快的格式化工具，使用
ruff自动代码风格，替代black、isort和pyupgrade。 - 已准备好使用的
pre-commit钩子，用于代码格式化。 - 类型检查使用
ruff；docstring 检查使用darglint；安全检查使用safety和bandit。 - 使用
pytest进行测试。 - 已准备好使用的
.editorconfig、.dockerignore和.gitignore文件。你不必担心这些事情。 - 构建 docker 的能力。
部署特性
GitHub集成：问题和 pr 模板。- 使用预定义的 构建工作流 作为默认的 CI/CD 的
Github Actions。 - 已经为安全检查、代码风格检查、代码格式化、测试、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 规范。
🤯 如何使用它
安装
开始使用模板，请安装 p3g
pip install -U p3g
然后转到你想创建项目的目录并运行：
p3g generate
输入变量
模板生成器将要求你填写一些变量。
输入变量及其默认值：
| 参数 | 默认值 | 描述 |
|---|---|---|
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_mirror_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
创建项目后，它将出现在你的目录中，并显示如何初始化项目的消息。
初始化 pre-commit
如果你在运行 make install 之前初始化 git 仓库，pre-commit 已经安装。如果没有初始化而失败，请再次运行 make install 以将 pre-commit 安装到 .git。
包示例
想了解更多关于 Poetry？查看相关文档。
关于 Poetry 的细节
Poetry 的命令非常直观易学，比如：
poetry add numpy@latestpoetry run pytestpoetry 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. 安装所有依赖和预提交钩子
安装要求：
make install
预提交钩子可以在 git init 之后通过以下方式安装：
make pre-commit-install
2. 代码风格和类型检查
自动格式化使用 ruff。
make format
仅检查代码风格，不重写文件：
make check-codestyle
注意：
check-codestyle使用ruff和darglint库
3. 代码安全
make check-safety
该命令启动 Poetry 完整性检查以及使用 Safety 和 Bandit 识别安全问题。
make check-safety
4. 带覆盖率徽章的测试
运行 pytest
make test
5. 所有的 linters
当然，有一个命令可以一次运行所有的 linters：
make lint
与以下命令相同：
make check-codestyle && make test && make check-safety
6. Docker
make docker-build
等同于：
make docker-build VERSION=latest
移除 docker 镜像：
make docker-remove
更多信息关于 docker。
7. 清理
删除 pycache 文件：
make pycache-remove
移除包构建：
make build-remove
删除 .DS_STORE 文件：
make dsstore-remove
移除 .mypycache：
make mypycache-remove
或者运行以下命令以移除以上所有内容：
make cleanup
🎯 下一步是什么
好吧，这取决于你 💪🏻。我只能推荐帮助我的包和文章。