Python 项目工程化实战（一）：pyproject.toml + uv + Ruff 现代工具链从零搭建 | Python 进阶

1
传统 Python 项目配置文件散落情况：
2

3
my_project/
4
├── setup.py             # 构建配置（需要执行 Python 代码才能读取！）
5
├── setup.cfg            # 部分配置迁移到这里
6
├── requirements.txt     # 生产依赖
7
├── requirements-dev.txt # 开发依赖（手动维护，容易遗漏）
8
├── .flake8              # flake8 配置
9
├── .isort.cfg           # isort 配置
10
├── mypy.ini             # mypy 配置
11
├── pytest.ini           # pytest 配置
12
├── tox.ini              # tox 配置
13
└── pyproject.toml       # 越来越多工具开始迁移到这里
14
                         # 但和其他文件并存，混乱

1
my_project/
2
├── pyproject.toml       # ✅ 唯一配置文件，包含所有工具配置
3
├── uv.lock              # ✅ 自动生成的精确依赖 lock 文件
4
├── src/
5
│   └── my_project/      # ✅ src layout，避免包名冲突
6
│       ├── __init__.py
7
│       └── main.py
8
└── tests/
9
    └── test_main.py

1
# pyproject.toml —— Python 项目统一配置文件
2

3
# ── 构建系统 ──────────────────────────────────────────────────
4
# 声明使用哪个构建后端（用于 pip install / python -m build）
5
[build-system]
6
requires = ["hatchling"]          # hatchling 是现代轻量构建后端（uv 默认使用）
7
build-backend = "hatchling.build"
8

9
# 其他常见选择：
10
# requires = ["setuptools>=61", "wheel"]  # 传统方案
11
# requires = ["poetry-core"]              # poetry 方案
12
# requires = ["flit_core>=3.2"]           # flit 方案（简洁）
13

14
# ── 项目元信息（PEP 621 标准）────────────────────────────────
15
[project]
16
name = "my-awesome-project"
17
version = "0.1.0"
18
description = "A short description of the project"
19
readme = "README.md"
20
license = { file = "LICENSE" }
21
authors = [
22
    { name = "Your Name", email = "you@example.com" },
23
]
24
keywords = ["python", "example"]
25
classifiers = [
26
    "Development Status :: 3 - Alpha",
27
    "Programming Language :: Python :: 3",
28
    "Programming Language :: Python :: 3.11",
29
    "Programming Language :: Python :: 3.12",
30
]
31

32
# 支持的 Python 版本范围
33
requires-python = ">=3.11"
34

35
# 生产依赖（等价于老式 requirements.txt）
36
dependencies = [
37
    "requests>=2.31",
38
    "pydantic>=2.0",
39
    "httpx>=0.27",
40
]
41

42
# ── 可选依赖组（pip install my-project[ml]）──────────────────
43
[project.optional-dependencies]
44
ml = [
45
    "numpy>=1.26",
46
    "scikit-learn>=1.4",
47
]
48
dev = [
49
    "pytest>=8.0",
50
    "pytest-cov>=5.0",
51
    "ruff>=0.5",
52
    "mypy>=1.10",
53
]
54

55
# ── 命令行入口点 ──────────────────────────────────────────────
56
[project.scripts]
57
# pip install 后，my-cli 命令可用
58
my-cli = "my_project.cli:main"
59

60
# ── 项目 URL ─────────────────────────────────────────────────
61
[project.urls]
62
Homepage = "https://github.com/yourname/my-project"
63
Documentation = "https://my-project.readthedocs.io"
64
Repository = "https://github.com/yourname/my-project"
65
"Bug Tracker" = "https://github.com/yourname/my-project/issues"
66

67
# ── Hatchling 构建配置 ────────────────────────────────────────
68
[tool.hatch.build.targets.wheel]
69
packages = ["src/my_project"]     # src layout：指定包在 src/ 下
70

71
# ── uv 配置 ──────────────────────────────────────────────────
72
[tool.uv]
73
dev-dependencies = [              # 开发依赖（等价于 [project.optional-dependencies].dev）
74
    "pytest>=8.0",
75
    "pytest-cov>=5.0",
76
    "ruff>=0.5",
77
    "mypy>=1.10",
78
]
79

80
# ── Ruff：linter + formatter 配置 ────────────────────────────
81
[tool.ruff]
82
target-version = "py311"          # 目标 Python 版本
83
line-length = 120                 # 每行最大字符数（Black 默认 88，可按需调整）
84
src = ["src", "tests"]            # 告知 Ruff 源码目录（影响 import 排序）
85

86
[tool.ruff.lint]
87
select = [
88
    "E",    # pycodestyle errors
89
    "W",    # pycodestyle warnings
90
    "F",    # pyflakes（未使用变量/导入等）
91
    "I",    # isort（import 排序）
92
    "N",    # pep8-naming（命名规范）
93
    "UP",   # pyupgrade（自动升级旧语法）
94
    "B",    # flake8-bugbear（常见 bug 模式）
95
    "SIM",  # flake8-simplify（代码简化建议）
96
    "C4",   # flake8-comprehensions（列表推导式优化）
97
    "RUF",  # Ruff 自有规则
98
]
99
ignore = [
100
    "E501",   # 行长度（由 formatter 控制，不重复报告）
101
    "B008",   # 不允许函数调用作为默认参数（FastAPI 中常用，需忽略）
102
]
103

104
[tool.ruff.lint.isort]
105
known-first-party = ["my_project"]   # 声明第一方包，影响 import 排序分组
106

107
[tool.ruff.format]
108
quote-style = "double"            # 字符串使用双引号（与 Black 默认一致）
109
indent-style = "space"
110
skip-magic-trailing-comma = false
111

112
# ── mypy 静态类型检查配置 ─────────────────────────────────────
113
[tool.mypy]
114
python_version = "3.11"
115
warn_return_any = true
116
warn_unused_configs = true
117
disallow_untyped_defs = true      # 所有函数必须有类型注解
118
ignore_missing_imports = true     # 忽略没有 stubs 的第三方库
119

120
# ── pytest 测试配置 ───────────────────────────────────────────
121
[tool.pytest.ini_options]
122
testpaths = ["tests"]
123
python_files = ["test_*.py", "*_test.py"]
124
addopts = [
125
    "--tb=short",           # 简洁的失败回溯
126
    "--cov=src",            # 覆盖率（需要 pytest-cov）
127
    "--cov-report=term-missing",
128
]
129

130
# ── coverage.py 覆盖率配置 ───────────────────────────────────
131
[tool.coverage.run]
132
source = ["src"]
133
omit = ["tests/*", "**/__pycache__/*"]
134

135
[tool.coverage.report]
136
show_missing = true
137
skip_covered = false

1
# ── F401：未使用的 import ─────────────────────────────────────
2
import os          # ← F401 如果 os 未在文件中使用
3
import sys
4

5
# ── I001：import 排序（isort 规则）──────────────────────────
6
# 错误：第三方库和标准库混排
7
import requests
8
import os
9

10
# 正确（ruff format 自动修复）
11
import os
12
import requests
13

14
# ── UP007：使用更简洁的 Union 写法（Python 3.10+）──────────────
15
from typing import Union, Optional
16

17
def func(x: Union[int, str]) -> Optional[str]:  # UP007: 建议改为 int | str
18
    ...
19

20
# ruff --fix 自动改为：
21
def func(x: int | str) -> str | None:
22
    ...
23

24
# ── B006：可变默认参数（常见 bug！）──────────────────────────
25
def bad_function(data: list = []):   # B006: 默认列表是共享对象！
26
    data.append(1)
27
    return data
28

29
def good_function(data: list | None = None):  # ✅
30
    if data is None:
31
        data = []
32
    data.append(1)
33
    return data
34

35
# ── SIM108：三元表达式简化 ──────────────────────────────────
36
# 建议：
37
if condition:
38
    x = a
39
else:
40
    x = b
41

42
# 自动改为：
43
x = a if condition else b

1
#!/bin/bash
2
# bootstrap.sh —— 快速初始化新 Python 项目
3

4
PROJECT_NAME=${1:-"my-project"}
5

6
# 初始化项目
7
uv init --lib "$PROJECT_NAME"
8
cd "$PROJECT_NAME"
9

10
# 固定 Python 3.12
11
uv python pin 3.12
12

13
# 添加开发依赖
14
uv add --dev \
15
    pytest>=8.0 \
16
    pytest-cov>=5.0 \
17
    ruff>=0.5 \
18
    mypy>=1.10
19

20
# 开发模式安装
21
uv pip install -e .
22

23
echo "✅ 项目 $PROJECT_NAME 初始化完成！"
24
echo "📂 目录结构："
25
find . -not -path './.venv/*' -not -path './.git/*' | sort | head -30