Python Best Practices Launchpad

Python 最佳实践启动模板

此仓库提供了一个现代 Python 项目模板，包含可运行的 FastAPI REST API，旨在使用 uv、ruff、mypy、pytest 以及由 pre-commit 驱动的 Git 钩子，实现高效开发。它展示了构建可用于生产环境的 Python 应用程序的最佳实践，涵盖稳健的测试、容器化以及 CI/CD 集成。

功能特性

• FastAPI REST API： 开箱即用的 API，使用 Pydantic 模型进行数据验证。
• Docker 和 Docker Compose： 通过多阶段构建实现适用于生产环境的容器化。
• 使用 uv 管理依赖项： 快速、高效地解析依赖项并管理虚拟环境。
• 使用 ruff 进行代码检查和格式化： 确保代码风格一致、及早发现错误，并提供自动修复功能。
• 使用 mypy 进行类型检查： 为 Python 代码添加静态类型检查，避免与类型相关的错误。
• 使用 pytest 进行测试： 完备的测试套件，包含单元测试、API 测试和集成测试。
• 使用 pre-commit 管理 Git 钩子： 在每次提交前自动执行代码质量检查。
• GitHub Actions 工作流： 开箱即用的 CI 流水线，用于测试和质量保证。
• Dev Container 支持： 提供配置，可在 VS Code 或 GitHub Codespaces 中立即开始开发。

项目结构

2024-Python-Best-Practices-Launchpad/
├── .github/workflows/       # GitHub workflows for CI/CD
│   └── main.yml             # Main CI workflow
├── .devcontainer/           # Dev Container configuration
│   ├── devcontainer.json    # Dev container settings
│   └── Dockerfile           # Dev container image definition
├── src/                     # Source code directory
│   └── my_package/          # Main package directory
│       ├── __init__.py      # Package initialization
│       ├── api.py           # FastAPI implementation
│       ├── models.py        # Pydantic data models
│       ├── module.py        # Core functionality
│       ├── example.py       # Example calculator class
│       └── run.py           # Script to run the FastAPI server
├── tests/                   # Test directory
│   ├── test_api.py          # Tests for FastAPI endpoints using models
│   ├── test_endpoints.py    # Tests for API endpoints using test client
│   ├── test_module.py       # Tests for core functionality
│   ├── test_example.py      # Tests for example calculator
│   └── integration_test.py  # Integration tests
├── .pre-commit-config.yaml  # Pre-commit hooks configuration
├── docker-compose.yml       # Docker Compose configuration
├── Dockerfile               # Multi-stage production Docker image
├── LICENSE                  # MIT License
├── pyproject.toml           # Project configuration and dependencies
├── pytest.ini               # Pytest configuration
└── README.md                # This file

API 功能

随附的 FastAPI 应用程序提供：

• 支持输入验证的数据处理 API
• 规范的错误处理和状态码
• 用于跨源请求的 CORS 中间件
• 自动生成 OpenAPI 文档（可通过 /docs 访问）
• 用于验证请求和响应架构的 Pydantic 模型

快速入门

你可以选择以下两种方式之一来设置此项目：

选项 1：使用 Dev Containers（推荐）

如果你安装了 VS Code 和 Dev Containers 扩展，或者使用 GitHub Codespaces，就可以快速开始，无需进行任何本地设置：

1. VS Code + Dev Containers：

   • 克隆此仓库
   • 在 VS Code 中打开仓库文件夹
   • 出现“Reopen in Container”提示时，点击“Reopen in Container”
   • （也可以按 F1，输入“Reopen in Container”，然后选择该选项）

2. GitHub Codespaces：

   • 点击 GitHub 仓库中的“Code”按钮
   • 选择“Codespaces”选项卡
   • 点击“Create codespace on main”

容器中包含所有必需的工具和依赖项，均已正确配置，可直接使用。

选项 2：使用 Docker Compose

要使用 Docker Compose 运行 API：

# Build and start the container
docker-compose up --build

# API will be available at http://localhost:8000

选项 3：使用 Linuxbrew/Homebrew 进行本地设置

克隆仓库之前，请确保已安装 Linuxbrew（macOS 上则安装 Homebrew）。

Windows/WSL 设置

1. 安装 WSL： 按照 Microsoft 官方说明安装 WSL 并选择一个 Linux 发行版（例如 Ubuntu）。

2. 打开 直接 WSL 终端：

   • 不要在 Windows 终端（如 PowerShell 或 Command Prompt）中使用 wsl。
   • 在 VS Code 中： 点击终端选项卡上的“+”按钮，打开一个新的集成终端，然后从下拉菜单中选择你的 WSL 发行版（例如“Ubuntu”“Debian”）。
   • 从开始菜单打开： 也可以直接从 Windows 开始菜单启动 WSL 发行版的终端（例如“Ubuntu”“Debian”）。

   本节后续所有步骤都必须在这个直接 WSL 终端中执行。

3. 安装基础依赖（在 WSL 中）：

   sudo apt update && sudo apt install -y build-essential curl file git
   

4. 安装 Linuxbrew：

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

5. 将 Linuxbrew 添加到 PATH： 根据你使用的 shell，将以下行添加到 ~/.bashrc 或 ~/.zshrc：

   export PATH="/home/linuxbrew/.linuxbrew/bin:$PATH"
   export MANPATH="/home/linuxbrew/.linuxbrew/share/man:$MANPATH"
   export INFOPATH="/home/linuxbrew/.linuxbrew/share/info:$INFOPATH"
   

   然后运行 source ~/.bashrc 或 source ~/.zshrc。

6. 通过 Linuxbrew 安装 Python： brew install python

macOS

1. 安装 Homebrew： 如果尚未安装，请在终端中运行以下命令安装 Homebrew：

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

2. 通过 Homebrew 安装 Python： brew install python

Linux

1. 安装 Linuxbrew： 按照 Linuxbrew 主页上的说明操作：https://brew.sh/
2. 通过 Linuxbrew 安装 Python： brew install python

2. 项目设置

安装 Linuxbrew（或在 macOS 上安装 Homebrew）和 Python 后，即可继续执行以下步骤：

1. 克隆代码仓库：

   git clone <repository_url>
   cd <project_name>
   

2. 创建并激活虚拟环境：

   uv venv
   

   如果虚拟环境尚不存在，此命令会创建一个。

3. 安装依赖：

    uv sync
   

   此命令会从锁定文件（uv.lock）安装所有依赖，包括开发依赖。

4. 安装 Git 钩子：

   pre-commit install
   

   此命令会安装 pre-commit 钩子，确保每次提交前自动执行格式整理和 lint 检查。

5. 创建锁定文件：

   uv lock
   

   此命令会创建锁定文件，将项目中的所有依赖固定到已知版本。

开发

• 运行 API 服务： 在本地启动 FastAPI 服务以进行开发。

  python -m src.my_package.run
  

  或

  uvicorn my_package.api:app --reload
  

• 访问 API 文档： 打开浏览器并访问：

  • Swagger UI：http://localhost:8000/docs
  • ReDoc：http://localhost:8000/redoc

• 运行测试： 在根目录中使用 pytest 运行测试。

  pytest
  

API 端点

• GET / - 提供 API 信息的根端点
• POST /process - 处理数据项列表
  • 接受包含 items 数组和可选 name 的 JSON
  • 返回已处理数据项的平均值、最大值和数量

Docker 支持

该项目包含可用于生产环境的 Docker 配置：

• 多阶段构建，以生成更小的镜像
• 使用非 root 用户，提升安全性
• 配置适当的环境变量
• 健康检查
• 资源限制

使用 Docker 构建和运行：

# Build the image
docker build -t python-best-practices .

# Run the container
docker run -p 8000:8000 python-best-practices

自动 lint 和格式整理

• 保存更改时，ruff 会自动修复格式和 lint 错误。

类型检查

• mypy 会作为 pre-commit 钩子的一部分运行，并捕获任何类型问题。

配置

核心配置

项目的核心配置位于 pyproject.toml 文件中。

• 项目元数据：
  • 项目的基本信息，例如名称、版本、描述、作者等。
  • 在 requires-python 中指定 Python 版本
• 依赖项：
  • 项目的依赖项列在 [project.dependencies 数组中。
  • 开发依赖项列在 [project.optional-dependencies.dev] 数组中，也可以添加其他分组。

[tool.uv]

• default-groups = ["dev"]：设置默认安装 dev 依赖项。

[tool.ruff]

• line-length = 100：设置最大行长度。
• select：列出启用的 ruff 和其他 lint 工具的规则。
• ignore：列出忽略的规则。
• fix = true：自动修复 lint 错误。
• per-file-ignores：配置要忽略特定规则的文件或模式。
• quote-style = "single"：设置使用单引号。

[tool.mypy]

• mypy_path = "src"：设置 mypy 类型检查所用的包的位置。
• python_version = "3.10"：设置所用的 Python 版本。
• strict = true：启用严格类型检查选项。
• plugins = ["pytest_mypy_plugins"]：使 mypy 可以使用 pytest 插件。

Git 钩子配置（.pre-commit-config.yaml）

此文件用于配置 pre-commit，这是一个在每次提交前运行检查的工具。配置包括：

• 通用钩子（pre-commit-hooks）： 删除行尾空格、确保文件末尾有换行符、验证 YAML 等。
• ruff 钩子（astral-sh/ruff-pre-commit）： 自动修复 Ruff 错误（ruff --fix）。
• black 钩子（psf/black）： 使用 black 格式化工具自动重新格式化代码
• mypy 钩子（pre-commit/mirrors-mypy）： 使用 mypy 检查代码中的类型错误

VS Code 配置（.vscode/settings.json）

此文件用于配置 VS Code 编辑器。

• 类型检查： python.analysis.typeCheckingMode：启用 Python 类型检查器。
• Lint： python.linting.ruffEnabled：启用 ruff 作为 lint 工具。
• 格式化： python.formatting.provider：禁用默认格式化工具，因为项目使用 pre-commit。
• Ruff 设置： 配置 Ruff 语言服务器的设置（例如 importStrategy、organizeImports、fixAll、showSyntaxErrors）。
• ruff.configurationPreference：优先使用基于文件的配置。

常用且实用的配置（基础配置中未包含）

以下是一些常常有用、通常会用到或至少在适用时能派上用场的额外配置。

1. 自定义 Ruff 规则和忽略项

• [tool.ruff.lint.per-file-ignores]： 使用此部分为特定文件忽略规则。例如：

  [tool.ruff.lint.per-file-ignores]
  "tests/*" = ["S101", "ANN"]  # Allow asserts and skip annotations in tests.
  "src/my_package/legacy.py" = ["B001", "B002"] # Ignore specific bugbear rules for legacy code
  

• extend-select 和 extend-ignore： 为项目添加额外规则或忽略规则。

  [tool.ruff.lint
  extend-select = ["PT"] # adds rules from flake8-pytest
  extend-ignore = ["ANN101", "ANN401"] # extends the ignore rules
  

• 规则专属选项： 某些规则可以进一步配置，例如 isort 选项。

  [tool.ruff.lint.isort]
  force-wrap-aliases = true
  

2. 自定义 Mypy 选项

• ignore_missing_imports： 如果依赖项和类型检查遇到问题，请设置为 true。

  [tool.mypy]
  ignore_missing_imports = true
  

• disallow_untyped_defs： 如果要在函数定义中要求类型注解，请使用 disallow_untyped_defs = true。

  [tool.mypy]
  disallow_untyped_defs = true
  

• disallow_any_explicit：如果要禁止在代码中显式使用 Any 类型。

  [tool.mypy]
   disallow_any_explicit = true
  

• warn_unreachable： 如果要启用不可达代码警告

  [tool.mypy]
  warn_unreachable = true
  

  请参阅 Mypy 配置文档，了解所有可用设置。

3. uv 配置

• constraint-dependencies： 如果要将传递依赖固定为特定版本，请使用 constraint-dependencies。

  [tool.uv]
      constraint-dependencies = ["cryptography<42.0.0"]
  

• override-dependencies： 强制依赖项使用特定版本

  [tool.uv]
      override-dependencies = ["cryptography==42.0.0"]
  

• index： 可以指定其他软件包索引以获取依赖项

  [[tool.uv.index]]
   name = "pytorch"
   url = "https://download.pytorch.org/whl/cu121"
   explicit = true
  
   [tool.uv.sources]
   torch = { index = "pytorch" }
  

4. 测试配置

• pytest.ini：在项目根目录中创建 pytest.ini，以配置 pytest 选项。

  [pytest]
  testpaths = tests
  addopts =
      --cov=src/my_package
      --cov-report term-missing
      -vv
  

  这样可以确保 pytest 对 tests 文件夹中的所有测试运行

  还会为 src/my_package 添加覆盖率信息

  还会以详细模式运行

5. pre-commit 配置

你可以从其他仓库添加额外的钩子。

你可以根据需要配置现有钩子。例如，如果要从 ruff 中排除文件，可以使用：

-   id: ruff
    args: ["--fix", "--exclude", "path/to/exclude"]

环境与工作区设置提示

使用不同的 Python 版本

• 此模板要求 Python 3.10 或更高版本
• 如果安装了多个 Python 版本：
  • 在 Windows 上，使用 py -3.10 -m venv .venv 指定版本
  • 在 Unix 上，使用 python3.10 -m venv .venv
  • 使用 uv 时，在 pyproject.toml 的 requires-python 中指定 Python 版本

IDE 集成

1. VS Code

   • 安装 Python 和 Ruff 扩展
   • 使用命令面板选择 Python 解释器
   • 安装 pre-commit 钩子后重启 VS Code
   • 将“文件：Eol”设为“\n”，以保持换行符一致

2. PyCharm

   • 在 Languages & Frameworks > Python > Ruff 下启用“Ruff”
   • 将“Editor > Code Style > Line separator”设为 Unix
   • 将 pytest 配置为默认测试运行器

虚拟环境最佳实践

• 每个项目创建一个 venv，以避免依赖冲突
• 不要提交 .venv 目录（它已列入 .gitignore）
• 在 Windows 上，如果 UV 失败，请改用 python -m venv
• 如果怀疑存在依赖问题，请重建 venv

故障排除

常见问题

1. 安装工具后出现“找不到命令”错误

   • 确保 PATH 包含 Linuxbrew/Homebrew 的 bin 目录
   • 尝试重启终端，或运行 source ~/.bashrc（或对应 Shell 的等效命令）

2. UV 特定问题

   • 如果 uv sync 因“Default group 'dev' is not defined”而失败，请检查 pyproject.toml 配置
   • 在脚本等场景中将 UV 用作 Python 模块时，请使用 pip install uv 安装
   • Windows 用户创建虚拟环境时，可能需要使用 Python 的完整路径：python -m venv .venv

3. 第三方库的类型检查错误

   • 为该库安装类型存根：uv pip install types-libraryname
   • 如果没有可用的存根，请将该库添加到 pyproject.toml 中 mypy 的忽略列表
   • 如果使用 pytest-mypy-plugins 时出现错误，可以将其从 mypy 配置中移除，因为它是可选的

4. Pre-commit 钩子配置

   • 运行 pre-commit run --all-files 查看详细错误信息
   • 根据错误信息修复问题，或更新钩子配置
   • 请注意，ruff-format 在成功格式化文件时也可能报告“failed”——这是预期行为
   • 如果出现 ruff 配置问题，请从最简配置开始，然后逐步添加规则

5. 包安装和开发模式

   • 使用 -e 以开发模式安装时，请确保位于正确的目录中
   • 在 Windows 上激活虚拟环境时使用反斜杠：.venv\Scripts\activate
   • 如果覆盖率警告提示“No source for code”，请确保包已以开发模式安装

6. 测试问题

   • 对于集成测试，即使在 Windows 上也要确保路径使用正斜杠（pytest 偏好的格式）
   • 集成测试期间，可以安全地忽略有关临时文件的覆盖率警告
   • 测试需要修改文件时，请使用 tempfile.TemporaryDirectory()，以免影响项目的实际文件

开发技巧

1. 高效的测试工作流

   • 运行指定的测试文件：pytest tests/test_module.py -v
   • 运行带覆盖率的测试：pytest --cov=src/my_package
   • 使用 -v 标志输出详细信息，以查看各项测试结果

2. 类型检查最佳实践

   • 为测试函数添加 -> None 返回类型注解
   • 在测试中有意违反类型约束时，谨慎使用 # type: ignore 注释
   • 考虑将 mypy 与 pre-commit 分开运行，以加快开发迭代

3. 代码风格和格式

   • 通过 pre-commit 让 ruff 自动处理代码格式
   • 字符串使用单引号（在 ruff 设置中配置）
   • 行长限制为 100 个字符（在 ruff 设置中配置）

将包发布到 PyPI

项目准备好发布后，可以将其发布到 Python Package Index（PyPI），以便用户通过 pip 或 uv 安装。以下是发布包的分步指南：

准备要发布的包

1. 确保已正确配置 pyproject.toml：

   • 检查项目元数据（名称、版本、描述、作者等）
   • 检查所有依赖项是否已正确列出
   • 确保 README.md 清晰且信息充分

2. 创建或更新包分类器： 添加合适的分类器，帮助用户找到你的包：

   [project]
   # ...existing metadata...
   classifiers = [
       "Development Status :: 4 - Beta",
       "Intended Audience :: Developers",
       "License :: OSI Approved :: MIT License",
       "Programming Language :: Python :: 3",
       "Programming Language :: Python :: 3.10",
       "Programming Language :: Python :: 3.11",
       "Topic :: Software Development :: Libraries",
   ]
   

构建分发包

1. 安装构建工具：

   uv pip install build twine
   

2. 构建包：

   python -m build
   

   这会在 dist/ 目录中生成源码分发包（.tar.gz）和 wheel 分发包（.whl）。

使用 TestPyPI 进行测试

在发布到 PyPI 主仓库之前，建议先使用 TestPyPI 进行测试：

1. 创建 TestPyPI 账户： 在 https://test.pypi.org/account/register/ 注册。

2. 配置凭据： 创建或编辑 ~/.pypirc：

   [distutils]
   index-servers =
       pypi
       testpypi
   
   [pypi]
   username = __token__
   password = pypi-AgEIcHlwaS5vcmc...  # Your PyPI API token
   
   [testpypi]
   repository = https://test.pypi.org/legacy/
   username = __token__
   password = pypi-AgEIcHlwaS5vcmc...  # Your TestPyPI API token
   

3. 上传到 TestPyPI：

   python -m twine upload --repository testpypi dist/*
   

4. 从 TestPyPI 测试安装：

   uv pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ your-package-name
   

发布到 PyPI

确认所有内容在 TestPyPI 上都能正常运行后：

1. 创建 PyPI 账户： 在 https://pypi.org/account/register/ 注册。

2. 生成 API 令牌：

   • 前往 https://pypi.org/manage/account/token/
   • 创建一个作用范围为“上传到 PyPI”的令牌
   • 请妥善保存此令牌，因为它不会再次显示

3. 上传到 PyPI：

   python -m twine upload dist/*
   

   系统会提示你输入用户名和密码（或令牌）。

4. 验证从 PyPI 安装：

   uv pip install your-package-name
   

使用 GitHub Actions 自动发布

你可以使用 GitHub Actions 自动执行发布流程。以下是一个工作流示例：

1. 在 .github/workflows/publish.yml 中创建 GitHub Actions 工作流文件：

name: Publish to PyPI

on:
  release:
    types: [created]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.10'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install build twine
    - name: Build and publish
      env:
        TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
        TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
      run: |
        python -m build
        twine upload dist/*

2. 在 GitHub 仓库中添加机密：
   • 前往仓库设置
   • 导航至 Secrets and variables > Actions
   • 添加 PYPI_USERNAME（使用 __token__）
   • 添加 PYPI_PASSWORD（你的 PyPI API 令牌）

使用此工作流后，每当你创建新的 GitHub 发布版本，系统都会自动发布新的软件包版本。

版本管理

发布版本请遵循语义化版本控制（MAJOR.MINOR.PATCH）：

• MAJOR：不兼容的 API 变更
• MINOR：以向后兼容的方式添加新功能
• PATCH：向后兼容的错误修复

每次发布前，请在 pyproject.toml 中更新版本号：

[project]
name = "my_package"
version = "0.2.0"  # Update this line

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

贡献

如果你想为此模板添加功能或提出改进建议，欢迎创建拉取请求。