[!info] 关联笔记

• 所属 MOC：工具链 · 学习路线
• 前置：模块与导入 · 包管理演进
• 相关：uv · poetry

Python 项目结构与打包

这个概念为什么出现

“能跑脚本”不等于“可安装的库/应用”。没有布局约定会出现：测试导入错包、生产缺依赖、工具找不到元数据。

[!abstract] 一句话理解 用清晰目录 + pyproject.toml 声明项目元数据与依赖，通过构建后端打包或可编辑安装进入环境。

最小可运行示例

先把示例放进业务场景，再看代码：

场景：给内部工具准备最小 pyproject 骨架说明

# show_layout_tips.py
# 业务意图：打印推荐布局清单（教学）。
# 教学点：布局是约定，服务于导入与分发。

def recommended_layout() -> list[str]:
    return [
        "src/myapp/",
        "tests/",
        "pyproject.toml",
        "README.md",
    ]


if __name__ == "__main__":
    print("\n".join(recommended_layout()))

建议运行：

python show_layout_tips.py

期望输出：

src/myapp/
tests/
pyproject.toml
README.md

结合场景再看三个关注点

1. src 布局避免测试误导入源码树半成品。
2. pyproject 成为现代中心配置。
3. 应用与库的入口（console_scripts）写在元数据中。

核心概念与准确模型

• 构建后端：setuptools/hatchling/flit 等
• 可编辑安装：pip install -e / uv sync
• 版本、依赖、脚本入口
• wheel/sdist 产物

边界情况与反直觉行为

1. 命名空间包规则不同。
2. 多包 monorepo 需工具链支持。
3. 资源文件打包要用 package data。

常见误区

[!warning] 常见误区：把 venv 目录提交进 git 错误理解：环境也是源码。
正确模型：锁文件 + 可重建环境。

工程实践

• 单一包名清晰
• CI：install → test → build
• 应用镜像内安装 wheel

本节总结

布局与打包把“一堆 py 文件”变成可协作工件。

自测题

1. src 布局的主要收益？
2. pyproject 角色？

参考答案

1. 强制以安装方式导入，减少路径意外。
2. 项目元数据、依赖与工具配置中心。

延伸阅读与资料来源

资料	类型	支撑内容
Packaging User Guide	指南	官方打包
pyproject.toml	指南	元数据