README_zh.md

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@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. 安装所有依赖和预提交钩子

安装要求：

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

🎯 下一步是什么

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

• Typer 非常适合创建 CLI 应用程序。
• Rich 可以轻松地在终端中添加美观的格式。
• [Pydantic](https://