Python Poetry项目中两种packages配置方式的差异及适用场景

核心区别 #

两种写法的本质差异在于安装后子包的层级结构：

• {include = "b", from = "a"}：从a目录下引入b子包，安装后b会成为顶级包，用户可以直接import b。
• {include = "a/b"}：直接引入a/b子包，安装后它的层级保持为a.b，用户必须通过import a.b来使用。

适用场景 #

1. 需要把子包作为独立顶级包使用（选第一种写法） #

假设你的项目结构是：

project/
└── a/
    ├── __init__.py
    └── b/
        ├── __init__.py
        └── core.py

如果想让用户安装后直接用import b而不是import a.b，就用第一种写法。常见场景比如：

• 拆分旧项目，把原主包下的某个子模块逐步剥离成独立包的过渡阶段；
• 代码存放目录和最终发布的包结构不一致（比如源码在src/a/b，但想发布成顶级包b）。

2. 保留子包的原有层级关系（选第二种写法） #

如果你的包本身就是多层级结构，a是主包，b是它的子模块，希望保持这种层级逻辑，就用第二种写法。这是Python包的常规子包引用方式，符合用户对多层级模块的使用习惯。

验证方式 #

你可以执行poetry build生成wheel包，解压后查看内部目录：

• 第一种写法的wheel里会直接出现b/目录；
• 第二种写法则是a/b/目录。

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