4.3 Packaging Code for Release and Distribution（整理版）

原始笔记: 4.3 Packaging Code for Release and Distribution.md 原始教程: 4.3 Packaging Code for Release and Distribution created: 2026-07-30 14:21 整理说明: 本版本仅整理原始笔记中已有的 Poetry 安装与配置、依赖管理、包名区别以及构建和安装 wheel 等知识点；教程中其他发布流程未纳入笔记。

内容简要概括

Poetry 可以统一管理 Python 项目的元数据、依赖、虚拟环境和构建过程。项目通过 pyproject.toml 声明运行时与开发依赖，再由 Poetry 解析并记录精确版本。完成配置后，可以构建 wheel 等分发文件，并使用 pip 安装生成的 wheel。

Poetry、Python packaging、pyproject.toml、virtual environment、dependency、development dependency、lock file、distribution package、module package、wheel、pip

为什么需要打包软件

将代码整理为标准 Python 包，可以明确项目元数据与依赖，使软件更容易安装、复用和分发。Poetry 将这些信息集中记录在 pyproject.toml 中，并负责解析依赖和构建分发文件。

安装与配置 Poetry

使用 pip 安装 Poetry：

python3 -m pip install poetry

确认当前 shell 使用的 Poetry 可执行文件：

which poetry

将 Poetry 创建的虚拟环境放在项目目录内：

poetry config virtualenvs.in-project true

启用该设置后，Poetry 通常会在项目根目录创建 .venv/。需要注意：

如果已经激活一个虚拟环境，Poetry 会优先使用当前环境。
如果没有手动激活虚拟环境，Poetry 会按配置创建或选用项目环境。
修改 virtualenvs.in-project 不会自动移动或重建已经存在的虚拟环境。

因此，应在初始化环境前确定配置；已有环境需要按实际情况重新创建。

初始化项目配置

在已有项目中运行：

poetry init

Poetry 会交互式询问包名、版本、描述、作者、Python 版本和依赖等信息，并生成 pyproject.toml。该文件是项目打包与依赖配置的主要入口。

管理项目依赖

运行时依赖

程序正常运行所需的库属于运行时依赖：

poetry add matplotlib numpy

开发依赖

仅在开发、测试或检查代码时需要的工具应放入开发依赖组：

poetry add --group dev pylint

--group dev 将依赖归入 dev 组，避免把开发工具误认为软件运行时的必要组成部分。

执行 poetry add 时，Poetry 会：

更新 pyproject.toml 中的依赖声明。
解析兼容的依赖版本。
更新 lock file，以记录可复现安装所需的精确版本。
将依赖安装到 Poetry 管理的虚拟环境。

区分分发包名与模块包名

Python 项目中有两类容易混淆的名称：

Distribution package name：安装与分发时使用的项目名称，记录在 pyproject.toml 中，并由 pip 或包索引识别。
Module package name：Python 代码中通过 import 使用的模块或包目录名称。

两者可以不同。例如，分发包名可能使用连字符，而导入名通常使用符合 Python 标识符规则的下划线。配置时应分别确认发布名称和代码导入路径。

构建并安装 wheel

在项目根目录构建分发文件：

poetry build

构建结果会写入 dist/。Poetry 通常会生成 source distribution 和 wheel，其中 wheel 文件以 .whl 结尾，适合直接安装。

安装生成的 wheel：

python3 -m pip install dist/inflammation*.whl

通配符应只匹配目标项目的 wheel；如果 dist/ 中存在多个版本或多个包，应改用明确的文件名，避免安装错误构件。

4.3 Packaging Code for Release and Distribution - Read