Python project template

Python 项目模板

这是一个适用于各类 Python 项目的模板仓库，包含以下开发工具：

• ruff：识别许多错误和风格问题（flake8、isort、pyupgrade）
• black：自动格式化代码

这些检查通过 pre-commit 库作为提交前钩子运行。

模板包含用于测试的 pytest，以及用于测量覆盖率的 pytest-cov 插件。

每次提交拉取请求或合并到 main 时，都会使用 Github actions 运行所有检查和测试。

此仓库配置为使用 Python 3.11。要更改版本：

1. 更改 .devcontainer/devcontainer.json 中的 image 参数（预构建 Docker 镜像列表见 https://github.com/devcontainers/images/tree/main/src/python）
2. 更改 .precommit-config.yaml 中的配置选项
3. 更改 .github/workflows/python.yaml 中的版本号

开发说明

使用 devcontainer

此仓库附带一个 devcontainer（Docker 化的 Python 环境）。如果你在 Codespaces 中打开它，devcontainer 应会自动初始化。

在本地安装 Dev Containers 扩展后，你可以在 VS Code 中打开它。

不使用 devcontainer

如果你无法或不想使用 devcontainer，请先创建一个虚拟环境：

python3 -m venv .venv
source .venv/bin/activate

然后安装开发工具和提交前钩子：

python3 -m pip install --user -r requirements-dev.txt
pre-commit install

添加代码和测试

此仓库初始包含一个非常简单的 main.py，以及针对它的测试文件 tests/main_test.py。 你需要将其替换为自己的代码，并且随着代码复杂度的增加，可能还需要添加其他文件。

准备好运行测试时，运行：

python3 -m pytest

文件说明

以下简要介绍此模板中的每个文件/文件夹：

• .devcontainer：包含用于设置 devcontainer 的文件的文件夹
  • devcontainer.json：配置 devcontainer 的文件，其中包含 VS Code 设置
• .github：包含 Github 专用文件和文件夹的文件夹
  • workflows：包含 Github actions 配置文件的文件夹
    • python.yaml：配置运行工具和测试的 Github action 的文件
• tests：包含 Python 测试的文件夹
  • main_test.py：包含针对 main.py 的 pytest 风格测试的文件
• .gitignore：描述 Git 不应跟踪哪些文件模式的文件
• .pre-commit-config.yaml：列出所有提交前钩子及其参数的文件
• main.py：程序的主 Python 文件（目前也是唯一的文件）
• pyproject.toml：配置大多数 Python 开发工具的文件
• README.md：你正在阅读的文件！
• requirements-dev.txt：列出开发所需所有 PyPi 软件包的文件
• requirements.txt：列出生产环境所需所有 PyPi 软件包的文件

如需更详细的说明，请阅读这篇博客文章。

🔎 发现问题或有改进建议？

请告诉我们并提交 issue，帮助我改进这个模板仓库！