Python项目如何实现类Maven/Gradle的子模块架构？

一、基于pyproject.toml + setup.cfg的原生实现 #

可以通过标准配置文件实现，但需要手动处理依赖关联和批量构建流程：

1. 调整项目结构：将所有子包归集到统一根目录下，每个子包保留独立的pyproject.toml/setup.cfg，根目录可添加一个可选的总控pyproject.toml：

bootstrap_library
├── pyproject.toml（根目录，可选）
├── library_a
│   ├── pyproject.toml
│   └── src/library_a
├── library_b
│   ├── pyproject.toml
│   └── src/library_b
└── library_utils
    ├── pyproject.toml
    └── src/library_utils

2. 配置子项目依赖：
   • 若用Poetry，在library_a/pyproject.toml中声明本地路径依赖：

     [tool.poetry.dependencies]
     python = "^3.9"
     library_utils = { path = "../library_utils" }
     

   • 若用setuptools，在library_a/setup.cfg中配置：

     [options]
     install_requires =
         library_utils @ file://../library_utils
     

3. 批量构建：标准工具无原生批量构建能力，需自行编写脚本（如bash或Python）遍历子目录，依次执行poetry build或python -m build命令。

这种方式能满足核心需求，但批量构建需要手动封装，缺乏Maven/Gradle式的原生子项目管理能力。

二、更高效的工具推荐 #

1. Poetry Workspaces #

Poetry 1.2及以上版本的Workspaces功能完全匹配你的需求：

• 初始化配置：在根目录创建pyproject.toml，声明工作区包含的所有子项目：

  [tool.poetry]
  name = "bootstrap-library-workspace"
  version = "0.1.0"
  description = ""
  authors = []
  
  [tool.poetry.workspace]
  members = [
      "library_a",
      "library_b",
      "library_utils",
  ]
  

• 子项目依赖配置：在library_a的pyproject.toml中直接关联工作区内的library_utils：

  [tool.poetry.dependencies]
  library_utils = { workspace = true }
  

• 批量操作：在根目录执行poetry build --all即可一次性构建所有子项目的wheel包；开发阶段修改library_utils后，依赖它的子项目会自动加载本地最新代码，无需重新安装。

2. Hatch #

Hatch原生支持单仓库多包（monorepo）结构，提供子项目管理与批量构建能力：

• 项目结构：根目录通过hatch init初始化，子项目存放于packages目录下：

  bootstrap_library
  ├── hatch.toml
  └── packages
      ├── library_a
      ├── library_b
      └── library_utils
  

• 依赖配置：在library_a的pyproject.toml中声明本地依赖：

  [project.dependencies]
  library_utils = { path = "../library_utils" }
  

• 批量构建：执行hatch build --all即可完成所有子包的构建，开发时Hatch会自动处理本地依赖的联动更新。

3. Pants #

Pants是专为Python monorepo设计的构建工具，适合中大型项目，核心特性包括：

• 自动识别子项目间的依赖关系
• 一键完成所有子包的构建、测试与发布
• 缓存构建结果，大幅提升重复构建效率

只需在根目录添加pants.toml配置，工具会自动扫描子项目，执行pants package ::即可构建所有子包。

总结 #

• 用pyproject.toml + setup.cfg可实现需求，但需手动编写批量构建脚本，适合小型项目；
• Poetry Workspaces、Hatch、Pants是更便捷的选择，其中Poetry Workspaces与你现有Poetry使用习惯契合度最高，上手成本最低。

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