1 / 4概念
Toolchain: Modules and Packaging
一个 Python 项目能不能交付,取决于三件分开的事:导入时解释器从哪里找到模块、安装时依赖被解析成哪一组版本、构建时产出的是哪种文件。判断标准不是本机能跑,而是拿到同一份 lockfile 与同一个 Python 版本,在干净环境里能否装出同一个结果。
1 概念
1.1 一句话定义
模块是一个 .py 命名空间,包是带层级与 __init__ 语义的模块集合;导入是按 sys.path 搜索并缓存到 sys.modules 的过程;分发是把项目按 PEP 517 构建后端打成 wheel 或 sdist;环境是隔离解释器与 site-packages 的目录,锁定文件固定整棵依赖解析结果。
1.2 它解决什么问题
- 命名空间与复用:把代码切成模块与包,按导入路径引用而不是复制粘贴。
- 依赖可复现:
pyproject.toml声明意图,lockfile 固定解析结果,CI 按锁安装。 - 构建可移植:wheel 预编译,装到目标平台不需要现场编译;sdist 保留源码构建路径。
- 环境隔离:项目级解释器与包目录,避免全局安装互相污染。
- 可分发入口:控制台脚本与插件入口点让包成为命令或框架扩展。
- 启动可诊断:导入耗时与模块数量可以量化,启动慢有据可查。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 解释器执行、对象模型与 GC | Interpreter and Objects |
类型注解、Protocol 与检查器语义 | Functions and Protocols |
| 镜像分层、容器运行时与编排 | Docker |
| CI 流水线的阶段与缓存策略 | CI/CD |
| 依赖投毒、签名与 SBOM | Supply Chain Security |
| 数据帧库本身的用法 | Dataframes |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| 模块 | 一个 .py 文件或扩展模块 | 不是类 |
| 包 | 带子模块的目录 | 命名空间包可以没有 __init__.py |
sys.path | 模块搜索路径列表 | 顺序决定谁先被找到 |
sys.modules | 已导入模块的缓存 | 导入一次,后续直接命中 |
site-packages | 第三方包安装目录 | 不是项目目录 |
pyproject.toml | 构建系统与项目元数据的标准入口 | 不是 lockfile |
| 构建后端 | 把源码变成 wheel/sdist 的程序 | 与构建前端不同 |
| wheel | 预构建、可直接安装的分发格式 | 不是源码包 |
| sdist | 源码分发包,安装时可能现场构建 | 需要构建工具链 |
| lockfile | 完整解析结果与哈希 | 不是版本约束 |
| editable install | 安装指向源码目录的链接 | 不是复制文件 |
| 入口点 | 包声明的命令或插件钩子 | 不是 __main__ |
| 平台标签 | wheel 文件名里的解释器、ABI 与平台 | none-any 表示纯 Python |
2 机制
2.1 心智模型
导入是一条查找链:sys.path 上每个目录按名字找模块,找到就执行并放进 sys.modules,之后不再执行。安装只是把 wheel 解包进某个 site-packages,所以“哪个解释器、哪个环境、哪个版本”决定运行时看到什么。锁文件把这组选择写成文件,构建则把它们变成可传输的产物。
2.2 机制拆解
- 导入解析:
import x依次询问元路径查找器,按sys.path顺序查找;sys.path[0]在脚本模式下是脚本所在目录,在-m模式下是当前目录;PYTHONPATH与site-packages依次追加。找到后执行模块顶层代码,结果缓存进sys.modules;再次导入直接返回缓存对象。 - 包与命名空间:常规包有
__init__.py,导入子模块会先执行它;PEP 420 命名空间包可以没有__init__.py,路径片段合并为一个逻辑包。相对导入from . import x只能在包上下文中使用,直接运行文件会失败,入口应写成python -m package.module。 - 循环导入:A 导入 B 时 B 又导入 A,B 看到的是 A 的半成品模块。解法是把共享定义下沉到第三方模块、把导入移进函数,或用
TYPE_CHECKING只做类型导入。 - 构建:
pyproject.toml的[build-system]指定后端与依赖,[project]声明名称、版本、依赖、入口点与 extras。前端(pip、uv、build)创建隔离环境,调用后端的build_wheel与build_sdist;wheel 文件名编码解释器标签、ABI 与平台,py3-none-any是纯 Python。 - 安装:前端读取 wheel 元数据,校验
Requires-Python与依赖标记,把文件解包进site-packages,生成.dist-info与入口点脚本。-e可编辑安装不复制源码,而是放一个指向项目目录的链接(PEP 660)。 - 环境与锁定:
venv用当前解释器创建隔离目录;uv在解析的同时写uv.lock,并支持工作区;Poetry 用poetry.lock;pip 用requirements.txt加--require-hashes或pip-tools。锁定只固定版本与哈希,Python 版本、平台与构建选项仍要单独固定。 - 可复现:同一 lockfile、同一 Python 小版本、同一平台标签、同一构建后端版本,才可能装出同一棵依赖树;缺一项就会出现“本机能装、CI 不能装”。
2.3 完整枚举
| 工具 | 角色 | 边界 |
|---|---|---|
pip | 安装器与前端 | 解析能力弱,需要额外锁定 |
uv | 解析、安装、锁定、工作区 | 较新,团队需统一版本 |
poetry | 依赖管理与打包 | 与 PEP 621 有差异,锁文件专用 |
pdm | PEP 621 项目管理 | 生态较小 |
hatchling | 构建后端 | 只负责构建 |
setuptools | 构建后端,兼容旧项目 | 配置项多,setup.py 属遗留 |
flit | 纯 Python 包的轻量后端 | 不适合复杂构建 |
maturin | Rust 扩展后端 | 需要 Rust 工具链 |
scikit-build-core | CMake 扩展后端 | 需要 C/C++ 工具链 |
venv | 标准库环境隔离 | 不管理依赖 |
conda / mamba | 二进制环境与包管理 | 与 pip 混用易冲突 |
pyenv | 多解释器版本切换 | 不管理项目依赖 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 解释器启动 | 数十毫秒 | 不含第三方导入 |
| 纯 Python 包导入 | 毫秒级 | 取决于顶层代码 |
| NumPy / pandas 导入 | 百毫秒级 | 含原生扩展加载 |
| 空 venv 体积 | 数十 MB | 含 pip 与 setuptools |
| 解析加速 | 约一个数量级 | uv 对比 pip,视依赖规模 |
| 纯 Python wheel | 数十 KB 到数 MB | 不含原生库 |
| 原生 wheel | 数 MB 到数百 MB | CUDA 包可达 GB 级 |
| sdist 现场构建 | 秒到分钟 | 取决于编译与依赖 |
| lockfile 行数 | 数百到数千 | 含传递依赖与哈希 |
3 实践
3.1 最小示例
# pyproject.toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "orders"
version = "0.3.0"
requires-python = ">=3.11"
dependencies = ["polars>=1.0", "pydantic>=2.5"]
[project.optional-dependencies]
dev = ["pytest>=8", "ruff>=0.4", "pyright>=1.1"]
[project.scripts]
orders = "orders.cli:main"
[tool.hatch.build.targets.wheel]
packages = ["src/orders"]
orders/
├── pyproject.toml
├── uv.lock
├── src/
│ └── orders/
│ ├── __init__.py
│ ├── cli.py
│ └── pipeline.py
└── tests/
└── test_pipeline.py
追踪一次安装:uv sync 读取 pyproject.toml 与 uv.lock,为声明的 Python 版本创建 .venv,按锁安装依赖,再以可编辑模式安装 orders;src 布局保证只有安装后的包才能被导入,测试不会意外读到仓库根目录的同名目录。orders 命令来自 [project.scripts],指向 orders.cli:main。
3.2 常用操作与参数
| 操作 | 命令 | 说明 |
|---|---|---|
| 建环境 | python -m venv .venv | 标准库、无额外依赖 |
| 激活 | source .venv/bin/activate | Windows 用 .venv\Scripts\activate |
| 同步依赖 | uv sync | 按 lockfile 安装 |
| 加依赖 | uv add polars | 更新声明与锁 |
| 可编辑安装 | uv pip install -e . | 开发时源码直接生效 |
| 构建产物 | python -m build | 在隔离环境调用后端 |
| 只构建 wheel | uv build --wheel | 输出到 dist/ |
| 检查一致性 | pip check | 报告版本冲突 |
| 看依赖树 | uv tree | 定位传递依赖来源 |
| 看导入耗时 | python -X importtime -c "import orders" | 定位慢模块 |
| 看安装来源 | python -m pip show -f orders | 文件清单与位置 |
| 释放模式 | uv run python -m orders | 不必手动激活 |
3.3 标准流程
- 用
src布局建项目,包名与导入名一致,测试放在独立的tests/。 - 在
pyproject.toml写requires-python、依赖、extras 与入口点;构建后端在项目初期就固定。 - 提交 lockfile;CI 与生产镜像都按锁安装,不允许无锁解析。
- 本地与 CI 使用同一 Python 小版本;用
.python-version或镜像标签固定。 - 构建 wheel 后在干净环境安装并跑测试,确认没有隐式依赖与本地路径依赖。
- 发布前检查元数据、版本号、平台标签与入口点,再上传到私有或公共索引。
3.4 与相邻技术的组合
- Docker:多阶段构建,前一阶段构建 wheel,后一阶段只装 wheel 与运行时依赖,镜像不带编译器。
- CI/CD:缓存包索引与虚拟环境,按 lockfile 安装;把 lint、类型检查、测试、构建拆成独立阶段。
- 私有索引:
uv与 pip 支持--index-url与 extra index,凭据走环境变量或密钥管理。 - C 扩展与 Rust 扩展:
manylinux与musllinux标签决定可移植性,现场编译需要完整工具链。 - 单仓多包:uv 工作区把多个包放进一个锁,路径依赖可编辑安装,发布时仍各自打 wheel。
- PEP 723 单文件脚本:在脚本头部声明依赖,
uv run script.py自动建临时环境,适合一次性任务。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 依赖规模 | 少量 / 大量 / 含原生库 | 决定解析器与锁策略 |
| 平台 | 纯 Python / 多平台原生 | 决定 wheel 标签与构建矩阵 |
| 团队约定 | pip / uv / poetry | 决定命令与锁文件格式 |
| 交付形态 | 库 / 应用 / 镜像 | 决定是否需要入口点与多阶段构建 |
| 多包协作 | 单包 / 工作区 | 决定路径依赖与统一锁 |
| 网络环境 | 公网 / 内网 / 离线 | 决定索引镜像与构建隔离 |
3.6 决策规则
- 新项目默认
src布局加pyproject.toml,不再新增setup.py。 - 依赖解析用 uv 或 Poetry,锁文件入库;CI 只用锁安装。
- 纯 Python 包优先纯 Python wheel;有原生扩展就为每个目标平台构建。
- 应用镜像只装 wheel,不在运行镜像里装编译器和测试依赖。
- 固定 Python 小版本;
requires-python是兼容范围,不是运行版本。 - 入口点写在
[project.scripts],不要靠python path/to/file.py交付命令。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| pip + venv | 标准、通用、无额外依赖 | 解析慢、锁定弱 | 教学、简单项目 |
| uv | 快、锁、工作区、单文件脚本 | 较新、命令需统一 | 新项目、CI |
| Poetry | 依赖与打包一体 | 锁文件专用、配置差异 | 应用与库 |
| PDM | 贴近 PEP 621 | 生态较小 | 标准优先的团队 |
| conda | 二进制依赖与 CUDA | 环境重、与 pip 混用冲突 | 科学计算、GPU |
| 容器作为环境 | 强隔离、可复现 | 体积大、开发反馈慢 | 生产交付 |
| PyInstaller / Nuitka | 打包成可执行文件 | 体积大、动态导入受限 | 桌面分发 |
3.8 何时不该用
- 一次性脚本不必建包与锁;PEP 723 或标准库足够。
- 纯内网离线环境不要临时拉取依赖;先做本地索引或 vendoring。
- 需要系统级共享库与驱动时,容器或 conda 比 pip 更可靠。
- 单一平台的小工具不必为多平台 wheel 建矩阵。
- 依赖树极小且稳定的内部工具,引入完整工作区反而增加维护成本。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
本机可导入,CI 报 ModuleNotFoundError | 依赖了仓库根目录的隐式路径 | 用 src 布局并按包安装 |
| 安装成功但导入失败 | wheel 没打包源码目录 | 检查构建后端的 packages 配置 |
from . import x 报“无父包” | 直接运行了包内文件 | 用 python -m package.module |
| 编辑源码后不生效 | 非可编辑安装或指向旧 wheel | uv pip install -e . 并确认路径 |
| 报版本冲突 | 多个包约束同一依赖的不同版本 | uv tree 定位,统一约束 |
| 安装时现场编译失败 | 目标平台没有 wheel 或缺少工具链 | 补 manylinux 构建或装编译器 |
| 命令找不到 | 入口点未声明或环境未激活 | 检查 [project.scripts] 与 PATH |
| 容器镜像巨大 | 运行阶段带入了构建依赖 | 多阶段构建,只复制 wheel |
| 导入的是标准库同名文件 | 当前目录遮蔽了标准库 | 重命名文件,检查 sys.path[0] |
| 锁文件与声明不一致 | 手改 lock 或跳过锁 | 重新解析并提交锁文件 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
全局 pip install | 项目之间互相污染 | 每项目独立环境 |
| 生产环境现场解析依赖 | 版本随时间漂移 | lockfile + 固定索引 |
提交 .venv | 平台相关、体积大 | 提交 lockfile 与 pyproject.toml |
sys.path.append 修导入 | 掩盖包结构问题 | 正确安装或调整布局 |
| 在运行镜像里装编译器 | 镜像膨胀、攻击面变大 | 多阶段构建 |
| 手改 lockfile | 哈希与依赖树不一致 | 用工具重新生成 |
| 依赖未声明的系统库 | 换机器即失败 | 写进镜像或文档 |
4.3 可观测信号
导入看 python -X importtime 与 -v 的模块搜索顺序;安装看前端日志里的解析结果与 wheel 标签;依赖一致性看 pip check 与 uv tree;环境看 sys.executable、sys.path 与 sysconfig.get_paths();构建看后端输出与 wheel 内容清单(unzip -l);启动慢看 -X importtime 的累计耗时排序。
4.4 安全 / 性能 / 一致性边界
- 可复现边界:锁 + Python 小版本 + 平台标签 + 构建后端版本四者缺一不可;源码安装还会引入编译器版本差异。
- 供应链边界:锁文件应带哈希,索引与凭据分离;私有包与公共包同名会造成依赖混淆。
- 平台边界:含原生扩展的 wheel 只能在匹配的解释器与 ABI 上使用,跨平台需要重新构建。
- 隔离边界:虚拟环境隔离的是包目录,不隔离内核、系统库与文件系统;真正的隔离要容器或命名空间。