Python仓库布局与安装路径转换关系及文件映射依赖算法咨询

核心问题解决方案（路径转对应包/版本） #

你不需要完整掌握所有打包工具的配置规则就能实现需求，Python生态已经有标准化的元数据机制可以直接用：

• 标准库方案（Python 3.8+）：直接使用importlib.metadata模块，低版本可安装第三方包importlib-metadata兼容。遍历所有已安装包的文件列表，和你拿到的绝对路径做匹配即可：
  1. 先通过sys.path定位所有site-packages目录，将目标文件绝对路径切掉site-packages前缀得到相对路径
  2. 调用importlib.metadata.distributions()获取所有已安装包的实例，每个实例调用files()方法可以拿到该包所有安装文件的路径对象，匹配到对应相对路径后，直接从实例的metadata['Name']和metadata['Version']字段拿到包名和版本
• 特殊场景处理：
  • 可编辑安装（pip install -e）的包会在site-packages下生成.egg-link文件，文件内容是开发目录的绝对路径，匹配到目标路径属于该开发目录时，直接读取开发目录下的pyproject.toml/setup.cfg/setup.py即可获取包名和版本
  • 系统级安装的Python包（比如通过apt、brew安装的包）元数据规则和pip安装的包完全一致，不需要单独适配

路径转换规则说明 #

你把流程拆分为构建、安装两个阶段是对的，所有路径转换都只发生在这两个阶段：

1. 构建阶段的路径转换 #

所有打包工具（setuptools/poetry/flit等）的配置核心都是定义「开发目录的文件对应发布包中的什么位置」，常见转换只有三类：

• 源码目录映射：比如你提到的package_dir = = src配置，作用是将开发目录下src文件夹内的包直接提到发布包根目录，比如开发路径src/foo/bar.py，打包后路径就是foo/bar.py
• 包含/排除规则：通过packages、exclude等配置指定哪些文件要打包进发布包，不符合规则的文件不会出现在最终安装路径中
• 资源文件映射：包依赖的非Python文件（配置、静态资源等）可以通过配置指定安装位置，最终路径都会记录在包元数据中
  所有打包工具最终输出的wheel包（.whl）结构是完全标准化的，所有构建阶段的路径转换结果都会直接体现在wheel包的文件结构里，不需要单独适配不同打包工具的配置。

2. 安装阶段的路径转换 #

正常安装wheel包时没有额外路径转换，wheel包根目录下的Python包文件会原封不动写入site-packages目录，仅两种特殊情况有区别：

• 可编辑安装：不会复制源码到site-packages，仅写入.egg-link文件指向本地开发目录
• 安装源码包（.tar.gz格式的sdist）：pip会先在本地执行构建流程生成wheel包再安装，路径转换规则和开发者本地构建完全一致

深入学习路线图 #

如果你需要进一步研究打包分发机制，按以下顺序学习即可：

• 第一步：掌握wheel包的结构规范，这是所有打包流程的最终输出标准，理解后就能通配所有打包工具的输出结果
• 第二步：学习pyproject.toml的基础配置规范，了解构建系统声明、包元数据配置的基本规则
• 第三步：了解setuptools、poetry两个主流打包工具的常用路径配置，其他小众工具的逻辑和这两个基本一致

内容的提问来源于stack exchange，提问作者wheresmycookie