Python 配置即代码的实践思路

pyproject.toml 不能仅写 [build-system]，因为工具链需实际消费字段：pip install -e . 需 [project]，poetry 忽略它，[build-system.requires] 必须匹配真实构建工具，动态 version 易被缓存坑，setup.py 虽弃用但 ci 可能仍依赖。

为什么 pyproject.toml 不能只写 [build-system] 就完事

因为 python 的“配置即代码”不是把配置文件写全就自动生效，而是依赖工具链对字段的实际消费。比如 setuptools 会读 [project]，但 poetry 默认忽略它；pip install -e . 只认 [build-system] + [project]，而 pipx 安装时还会检查 [project.scripts] 是否存在。

常见错误现象：pip install -e . 成功但 import mypkg 报 ModuleNotFoundError；或者 python -m build 失败，提示 Unknown distribution option: 'entry_points'。

• 必须确保 [build-system.requires] 包含真正用于构建的工具，例如 ["setuptools>=61.0", "wheel"]，而不是抄别人项目里的 ["poetry-core"] 却没装 poetry
• [project] 下的 name 和 version 必须是字符串，不能是动态表达式（如 "0.1.0.dev"+open("VERSION").read()），否则 pip 解析失败
• 如果用 src/ 目录结构，得加 [project.paths] 或在 [tool.setuptools] 里配 package-dir = {"" = "src"}，否则打包时找不到模块

setup.py 已弃用，但删掉它可能让 CI 崩溃

PEP 621 明确推荐用 pyproject.toml 替代 setup.py，但很多 CI 流水线、docker 构建脚本或内部工具仍硬编码调用 python setup.py sdist。直接删掉 setup.py 不是“干净”，而是制造隐性故障。

使用场景：你刚迁移到 pyproject.toml，本地 pip install -e . 没问题，但 jenkins 上跑 python setup.py bdist_wheel 报错 No module named 'setuptools'。

立即学习“Python免费学习笔记（深入）”；

• 最省事的做法是留一个极简 setup.py，只包含 from setuptools import setup; setup()，它会自动 fallback 到 pyproject.toml 中的 [project]
• 不要在 setup.py 里写逻辑（比如读 VERSION 文件），否则和 pyproject.toml 的 version 不一致，导致安装后 importlib.metadata.version("mypkg") 返回错误值
• CI 脚本中优先替换为 python -m build --wheel，它原生支持 PEP 621，且不依赖 setup.py

动态 version 怎么写才不会被缓存坑死

用 git 描述符（如 v1.2.0-3-gabc123）生成版本号很常见，但 pip 在 editable 模式下会缓存 pyproject.toml 解析结果，导致改了 commit 后 importlib.metadata.version() 还返回旧值。

性能影响：每次 import 都执行 git describe 会拖慢启动；兼容性影响：某些环境（如 Alpine linux）没装 git，pip install 直接失败。

• 推荐用 setuptools_scm：在 [tool.setuptools_scm] 里配 version_scheme = "guess-next-dev"，它只在构建时运行一次 git 命令，生成静态 version 写入 wheel 元数据
• 避免在 [project.version] 直接写函数调用，比如 "{file:VERSION}" 或 "{attr: mypkg.__version__}"，这些只在某些工具（如 hatch）里支持，pip 原生不认
• 如果必须手动管理，把 version 放进 src/mypkg/_version.py，由构建工具写入，再在 pyproject.toml 里用 [project.dynamic.version] 声明，这样 pip 才能识别

tool.* 下的配置项到底谁在读

pyproject.toml 里 [tool.black]、[tool.ruff]、[tool.mypy] 这些段落，Python 解释器完全不看——它们只是各工具约定俗成的存放位置。真正决定行为的是你**实际执行的命令**和**对应工具是否安装**。

容易踩的坑：在 [tool.isort] 里写了 profile = "black"，但没装 isort，结果 pre-commit 钩子静默跳过；或者 [tool.pytest.ini_options] 配了 addopts，但 pytest 版本太老不支持该字段，直接报错退出。

• 每个 [tool.XXX] 段落只对 XXX 工具生效，pip、python、venv 全部无视，别指望它们影响 import 行为或虚拟环境创建
• 不同工具对同一名字的字段语义可能冲突，比如 [tool.black.line-Length] 是 int，但 [tool.ruff.line-length] 是 String，写错类型会导致工具启动失败
• 想确认某段配置是否生效？直接运行对应命令加 --verbose，例如 black --verbose . 会打印它加载了哪些配置项

复杂点在于，同一个配置项在不同工具链里可能触发完全不同的行为路径——比如 [project.optional-dependencies] 在 pip install mypkg[dev] 和 poetry add --group dev pytest 中的解析逻辑就不是一回事，别假设“写了就能用”。