Python多可安装包项目结构配置与优化咨询

方案一：保留现有结构，实现三个独立可安装包 #

你的现有结构可以通过为每个包单独配置构建文件实现独立安装，核心是把src（作为共享核心包）、src/package_2、package_3分别作为三个独立包，明确各自的依赖关系。

配置步骤 #

1. 核心包（src）构建配置
   在src目录下创建pyproject.toml和setup.cfg：
   src/pyproject.toml：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "core"
version = "0.1.0"
authors = [{ name="你的名字", email="你的邮箱" }]
description = "共享核心模块包"
requires-python = ">=3.8"
dependencies = []

src/setup.cfg：

[metadata]
license_files = ../LICENSE

[options]
packages = find:
package_dir =
    = .
include_package_data = True

2. package_2构建配置
   在src/package_2目录下创建pyproject.toml和setup.cfg：
   src/package_2/pyproject.toml：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "package2"
version = "0.1.0"
authors = [{ name="你的名字", email="你的邮箱" }]
description = "Package2功能包"
requires-python = ">=3.8"
dependencies = ["core>=0.1.0"]

src/package_2/setup.cfg：

[metadata]
license_files = ../../LICENSE

[options]
packages = find:
package_dir =
    = .
include_package_data = True

3. package_3构建配置
   在package_3目录下创建pyproject.toml和setup.cfg：
   package_3/pyproject.toml：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "package3"
version = "0.1.0"
authors = [{ name="你的名字", email="你的邮箱" }]
description = "Package3封装包"
requires-python = ">=3.8"
dependencies = ["core>=0.1.0", "package2>=0.1.0"]

package_3/setup.cfg：

[metadata]
license_files = ../LICENSE

[options]
packages = find:
package_dir =
    = .
include_package_data = True

安装与测试 #

• 安装顺序：先安装core（cd src && pip install .），再安装package2（cd src/package_2 && pip install .），最后安装package3（cd package_3 && pip install .）
• 测试：每个tests子目录对应包的测试，运行前确保对应包已安装，例如用pytest tests/src_tests/单独测试核心包。

方案二：重构为规范Monorepo结构（长期维护更友好） #

虽然重构需要投入时间，但这种结构更符合Python打包最佳实践，后续维护、版本管理、发布都会更顺畅，尤其适合耦合度高的关联包。

重构后的结构 #

my-project
    - packages
        - core
            - src
                - core
                    - __init__.py
                    - widely_used_module_1.py
                    - widely_used_module_2.py
                    - widely_used_module_3.py
            - pyproject.toml
            - setup.cfg
        - package2
            - src
                - package2
                    - __init__.py
                    - package_2_module.py
            - pyproject.toml
            - setup.cfg
        - package3
            - src
                - package3
                    - __init__.py
                    - package_3_module.py
            - pyproject.toml
            - setup.cfg
    - tests
        - core_tests
        - package2_tests
        - package3_tests
    - README.md
    - LICENSE

重构优势 #

• 每个包独立目录，结构清晰，避免命名冲突
• 统一采用src-layout，符合Python打包规范，减少导入异常
• 后续解耦、版本升级、单独发布更灵活
• 测试目录与包结构一一对应，便于维护

重构步骤建议 #

不用一次性完成代码解耦，先调整目录结构和配置文件，确保三个包能正常安装测试，再逐步优化内部代码的耦合问题，比如抽象公共接口、减少直接依赖等。

同类项目参考 #

很多Python生态中的关联包都采用类似Monorepo结构：

• Celery生态：Celery（核心任务队列）、kombu（消息传递库）、billiard（进程管理）三个独立包，互相依赖，结构清晰
• FastAPI生态：FastAPI（Web框架）依赖Starlette（ASGI工具包），两者为独立包，采用标准src-layout
• 企业内部工具链：多数公司内部的共享工具包会用Monorepo管理多个关联包，便于统一维护和版本控制

额外优化建议 #

• 用tox/nox管理测试：编写一个配置文件，自动为每个包创建独立虚拟环境、安装依赖并运行测试，避免环境冲突
• 统一版本管理：如果三个包同步发布，用bumpversion或towncrier工具批量更新版本号，避免版本不一致
• 添加pre-commit钩子：配置black（代码格式化）、flake8（代码检查）、mypy（类型检查），提交代码前自动执行，保证代码质量
• 文档规范化：每个包添加单独的README，说明功能、安装方法、使用示例，或用mkdocs搭建统一文档站点
• 依赖锁定：用pip-compile为每个包生成requirements.txt.lock，确保开发、测试、生产环境依赖一致

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