Flat-layout下Pyproject配置异常：Lib生成多文件夹而非单模块

我之前采用src-layout创建Python模块detection_engine，现需切换为flat-layout。查阅setuptools文档后仍觉晦涩且缺乏示例，原src-layout的pyproject.toml配置如下：

[build-system]
requires = ["setuptools", "setuptools-scm"]
build-backend = "setuptools.build_meta"

[project]
name = "detection_engine"
authors = [
    {name = "Josiah Carberry", email = "josiah_carberry@brown.edu"},
]
description = "Detection Engine"
readme = "README.md"
requires-python = ">=3.8"

dependencies = [
    "requests",
    'importlib-metadata; python_version<"3.10"',
]
dynamic = ["version"]

[project.optional-dependencies]
yolox = [
    "loguru==0.7.2",
    "tqdm==4.66.1",
    "thop==0.1.1.post2209072238",
    "ninja==1.11.1.1",
    "tabulate==0.9.0",
    "psutil==5.9.6",
    "tensorboard==2.14.0",
    "pycocotools>=2.0.7",
    "onnx>=1.13.0",
    "onnx-simplifier",
]
mmcv = [
    "loguru==0.5.3",
    "mmdet==2.28.1",
    "mmcv-full",
    "numpy",
    "opencv-python==4.7.0.72",
    "pydantic",
    "pytest-cov==4.0.0",
    "pytest==7.2.2",
    "torch==2.0.1",
    "torchvision==0.15.2"
]

[tool.setuptools.packages.find]
where = ["src"]
include = ["*"]
namespaces = true # set false to not include folders without __init__.py file.

将[tool.setuptools.packages.find]的where设置为["."]后，安装时lib目录下生成了detection、engines、models、tracking四个独立文件夹，而非包含这四个子文件夹的detection_engine单模块。项目当前目录结构如下：

├── detection
├── detection_engine.egg-info
├── dist
├── engines
├── environment.yml
├── MANIFEST.in
├── mmcv_install.sh
├── models
├── pyproject.toml
├── README.md
├── requirements_mmcv.txt
├── requirements_yolox.txt
├── setup.py
└── tracking

问题原因 #

当前目录结构中，detection、engines等文件夹直接位于项目根目录，setuptools会将它们识别为独立的顶级Python包，而非detection_engine的子模块。flat-layout要求主模块（即detection_engine）作为根目录下的文件夹，所有子模块嵌套在该主模块内部。

修复步骤 #

1. 调整目录结构 #

创建detection_engine文件夹，将所有子模块文件夹移动进去，并为主文件夹添加__init__.py文件（每个子文件夹也需确保有__init__.py，空文件即可）：

├── detection_engine
│   ├── __init__.py
│   ├── detection
│   │   └── __init__.py
│   ├── engines
│   │   └── __init__.py
│   ├── models
│   │   └── __init__.py
│   └── tracking
│       └── __init__.py
├── detection_engine.egg-info
├── dist
├── environment.yml
├── MANIFEST.in
├── mmcv_install.sh
├── pyproject.toml
├── README.md
├── requirements_mmcv.txt
├── requirements_yolox.txt
├── setup.py

2. 修改pyproject.toml配置 #

保持where为["."]，但限制include的范围为detection_engine相关包，避免识别根目录下的其他独立文件夹：

[tool.setuptools.packages.find]
where = ["."]
include = ["detection_engine*"]  # 匹配主模块及所有子模块
namespaces = false

如果更倾向于手动指定包，也可以替换为以下配置：

[tool.setuptools]
packages = [
    "detection_engine",
    "detection_engine.detection",
    "detection_engine.engines",
    "detection_engine.models",
    "detection_engine.tracking"
]

3. 验证安装 #

先清理旧构建文件：

rm -rf detection_engine.egg-info dist build

执行 editable 安装：

pip install -e .

检查site-packages目录下的detection_engine，确认其包含所有子模块。

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