Python 项目模板

这是一个 Python 项目的模板仓库，自带以下开发工具：

• ruff: 识别多种错误和风格问题 (flake8, isort, pyupgrade)
• black: 自动格式化代码

这些检查使用 pre-commit 库作为 pre-commit hooks 运行。

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

这些检查和测试都在每次 pull request 和合并到 main 分支时，使用 Github actions 运行。

此仓库设置为 Python 3.11。要更改版本：

1. 更改 .devcontainer/devcontainer.json 中的 image 参数 (请参阅 https://github.com/devcontainers/images/tree/main/src/python 获取预构建 Docker 镜像的列表)
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

然后安装开发工具和 pre-commit hooks：

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: 配置文件，包括 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: 列出所有 pre-commit hooks 和参数的文件
• main.py: 程序的主要（也是目前唯一的）Python 文件
• pyproject.toml: 配置文件，配置大多数 Python 开发工具
• README.md: 你正在阅读它！
• requirements-dev.txt: 列出开发所需的所有 PyPi 包的文件
• requirements.txt: 列出生产所需的所有 PyPi 包的文件

有关更长的解释，请阅读 这篇博文。

🔎 发现问题或有改进的想法？

通过告知我们并提出 issue，帮助我改进此模板仓库！