pyproject.toml 必须存在且包含 [build-system] 和 [project] 两个核心段：前者需声明 requires（如 ["setuptools>=61.0"]）和 build-backend（如 "setuptools.build_meta"），后者必填 name 和 version；缺一则导致 python -m build 或 pip install -e . 失败。

pyproject.toml 必须存在且结构正确

没有 pyproject.toml，python -m build 会回退到旧模式或直接报错，生成的 wheel 可能不被 pip 正确识别。它不是可选配置，而是 PEP 517 的强制入口。

必须包含两个核心段：[build-system] 和 [project]。前者声明构建依赖和后端，后者定义包名、版本、作者等元数据。漏掉任意一个，pip install -e . 或 python -m build 都可能失败。

• [build-system] 中 requires 至少要含一个构建后端，比如 ["setuptools>=61.0"] 或 ["hatchling"]；build-backend 必须匹配，如 "setuptools.build_meta"
• [project] 中 name 和 version 是必填项；requires-python 建议明确（如 ">=3.8"），否则 CI 上可能因 Python 版本模糊而构建失败
• 如果用 src/ 布局，[project] 里不用写 packages 字段——现代构建后端（setuptools 61+、hatchling、flit）会自动发现 src/<name></name> 目录

src/ 布局比 flat layout 更可靠

把代码放在 src/my_package/ 而不是项目根目录下，能彻底避免 pip install -e . 导致的 import 冲突。常见现象是：本地运行 python -c "import my_package" 成功，但测试时却报 ModuleNotFoundError——大概率是因为当前目录被加进了 sys.path，Python 优先导入了未打包的源码副本，而非安装后的包。

Claw Code Suite (Python-Only Edition)

仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...

下载

• Cookiecutter 模板（如 audreyr/cookiecutter-pypackage）启用 use_src_layout [y] 后，自动生成 src/my_package/__init__.py 和 pyproject.toml 适配结构
• 手动建 src/ 时，确保 project.name（在 pyproject.toml 中）与 src/ 下的子目录名完全一致，大小写、连字符都不能错
• 运行 pip install -e . 后，检查 site-packages 是否有 my_package-0.1.0-py3.x.egg-link 文件，内容应指向你的项目根目录——这是 editable 安装生效的标志

tox + pytest 组合必须隔离 Python 环境

Tox 不是“高级可选工具”，而是验证 PEP 517 包是否真正可复现的关键环节。它强制你在干净虚拟环境中执行 pip install . 和 pytest，暴露那些只在你本机环境里才跑得通的问题。

• tox.ini 中 [testenv] 的 deps = pytest 要写在 deps 下，而不是 commands 里——否则 pytest 可能用的是系统全局版本，而非 tox 创建的隔离环境里的版本
• 常见错误：tox -e py39 报 No module named 'my_package'，90% 是因为 pyproject.toml 缺少 [project] 段，或 name 和实际目录名不一致
• 建议在 tox.ini 的 commands 中加入 python -c "import my_package; print(my_package.__file__)"，确认导入的是安装后的包路径，而非源码路径

build 工具比 setup.py 更安全也更可控

python -m build 在临时隔离环境中执行构建，不会污染你当前的 Python 环境，也不执行任意代码——这直接规避了 python setup.py sdist 的安全风险和依赖冲突问题。

• 运行前确认已安装 build：执行 pip install build（无需全局升级 pip，build 本身不依赖新版 pip）
• 构建命令就是 python -m build，默认同时产出 .tar.gz（sdist）和 .whl（wheel）；加 --wheel 或 --sdist 可单独指定
• 生成的 .whl 文件名格式为 {name}-{version}-py{X.Y}-{platform}.whl，其中 py39 表示仅兼容 Python 3.9——若需多版本兼容，确保 requires-python 设置合理（如 ">=3.8"），且代码无版本专有语法

实际搭建时最易被忽略的点是：pyproject.toml 的 [project] 段缺失或字段拼写错误（比如写成 project-name 而非 name），会导致整个构建链路静默失效——既不报错，又生成无效 wheel。务必在 python -m build 后用 pip install --find-links dist/ --no-index my_package 验证安装是否真能成功导入。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！