Skip to main content

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 不属于本页的内容​

主题去哪
解释器执行、对象模型与 GCInterpreter and Objects
类型注解、Protocol 与检查器语义Functions and Protocols
镜像分层、容器运行时与编排Docker
CI 流水线的阶段与缓存策略CI/CD
依赖投毒、签名与 SBOMSupply 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