Python工程化系统学习路线第269讲_核心原理与实战案例详解【技巧】_技术教程

Python工程化核心是解决协作与维护中的导入问题：__init__.py缺失、pip install -e .失败、sys.path加载顺序混乱、PYTHONPATH不生效、模块缓存干扰等，需通过-m运行、规范包结构、正确配置pyproject.toml来应对。

Python 工程化不是堆砌工具链，而是让代码在多人协作、持续交付、长期维护中不崩。第269讲这类标题容易让人误以为是“高级技巧合集”，实际它暴露的往往是基础原理没吃透——比如不明白 __init__.py 为何有时可删有时必留，或为什么 pip install -e . 能绕过安装却仍报 ModuleNotFoundError。

为什么 `sys.path` 和 `PYTHONPATH` 总对不上？

这是工程化起步阶段最常卡住的地方：本地跑通，CI 失败；IDE 能 import，命令行报错。根本原因不是路径没加，而是加载顺序和模块缓存干扰。

sys.path 是运行时生效的列表，但 Python 会优先从 sys.path[0]（通常是当前目录）开始查，而不是你期望的包根目录
PYTHONPATH 只影响新启动的解释器，已运行的进程（如 Jupyter kernel、IDE 内置 Python）不会重新读取
importlib.invalidate_caches() 并不能清掉已成功导入的模块，得用 del sys.modules['pkg_name'] 手动卸载（仅调试用）

实操建议：统一用 -m 方式运行，例如

python -m mypackage.main

，强制以包模式启动，避免当前目录污染 sys.path[0]。

`setup.py` vs `pyproject.toml`：什么时候必须切？

不是“新版一定更好”，而是构建行为是否被正确捕获。如果你的项目用了 setuptools_scm 自动生成版本号，或需要 build-system.requires 显式声明构建依赖，pyproject.toml 就不可绕过。

setup.py 在 pip ≥21.3+ 中已被标记为 legacy，某些 CI 镜像默认禁用
pyproject.toml 中若漏写 [project] 段，pip install -e . 会静默回退到旧逻辑，但不再支持 setup.cfg
混合使用（如 pyproject.toml + setup.py）极易触发未定义行为，官方明确不保证兼容

判断依据：执行

pip debug --verbose

，看输出里 build_backend 是否为 setuptools.build_meta 或 hatchling.build —— 若仍是 setuptools.pep517，说明配置未生效。

`pip install -e .` 报 `ModuleNotFoundError` 的真实原因

错误信息指向模块名，但问题往往出在包结构本身。典型场景是包内有同名子模块和顶层模块（如 mypackage/mypackage/），或 __init__.py 缺失导致 Python 无法识别为包。

检查 find_packages() 返回值：在 setup.py 或 pyproject.toml 中加一行打印，确认它是否真找到了你的源码目录
运行
```
python -c "import mypackage; print(mypackage.__file__)"
```
，如果报错，说明没进 editable 模式；如果路径指向 site-packages 下的 egg-link，说明链接文件损坏，删掉 src/ 同级的 .egg-info 目录重试
Windows *意路径分隔符：find_packages(where="src") 中的 where 必须是斜杠或正则安全字符串，反斜杠可能被当成转义