使用Poetry构建的Python包无法安装测试、脚本等支持文件

核心原因 #

Poetry默认遵循Python包标准规范，仅将核心源码目录（含__init__.py的目录）、配置指定的资源文件打包到wheel中。tests、scripts、docs这类目录默认不属于包的运行时依赖内容，因此不会被自动纳入安装路径；docs目录通常被归类为文档资源，会被安装到系统文档目录而非site-packages下的包路径。

符合最佳实践的解决方案 #

1. 将tests目录纳入安装包 #

若需随包分发tests目录（特殊场景下的需求），需在pyproject.toml中明确配置：

[tool.poetry]
# 保留原有配置，新增packages指定
packages = [
    { include = "mypkg" },
    { include = "tests", from = "." }
]

# 或者用全局include字段一次性指定所有需要包含的内容
# include = ["mypkg/**/*", "tests/**/*", "scripts/**/*", "docs/**/*"]

同时添加包数据配置确保所有文件被包含：

[tool.poetry.data.files]
"tests" = ["tests/**/*"]

配置后，tests目录会被安装到site-packages下的包根路径，符合规范。

2. 正确处理CLI脚本 #

无需手动打包scripts目录，Poetry提供了官方推荐的CLI脚本配置方式，直接在pyproject.toml中指定入口点：

[tool.poetry.scripts]
mypkg-cli = "scripts.main:main"

安装后终端会自动生成mypkg-cli命令，直接映射到scripts/main.py中的main函数，避免手动管理脚本路径的问题。

3. 将docs目录安装到包路径下 #

若要让docs目录随核心包安装到site-packages的mypkg路径下，有两种方式：

• 方式一：修改配置标记为包数据

[tool.poetry.package-data]
mypkg = ["docs/**/*"]

• 方式二：调整目录结构，将docs放到核心包目录内（如mypkg/docs），Poetry会自动将其作为包的一部分打包。

4. 验证构建结果 #

修改配置后重新构建包：

poetry build

通过以下命令检查打包内容是否符合预期：

# 查看wheel包内容
unzip -l mypkg-0.2.0-py3-none-any.whl
# 查看源码包内容
tar -tvf mypkg-0.2.0.tar.gz

注意事项 #

• 通常不推荐随安装包分发tests目录，此方案仅针对你的特殊需求；若只是需要运行测试，建议用户直接使用源码包。
• CLI脚本使用Poetry的scripts配置是官方规范，比手动打包scripts目录更可靠。
• 若docs需要被程序直接访问（如内置帮助文档），将其放到核心包目录内是更规范的做法。

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