Python多仓库pipeline代码组织与模块导入最佳实践咨询

1. 子仓库（各Pipeline步骤）的规范要求 #

每个独立步骤的仓库统一按Python可安装包的标准结构组织，确保可以被pip直接安装，结构示例：

your-step-repo/
├── pyproject.toml  # 包依赖、入口点、元信息声明
├── src/
│   └── your_step_name/  # 包名统一用下划线分隔，避免和其他步骤冲突
│       ├── __init__.py
│       ├── core.py  # 核心逻辑代码
│       └── __main__.py  # 支持单独运行的入口
└── tests/  # 单测目录，各仓库自己维护单元测试

• 每个子仓库的pyproject.toml里必须明确声明包名、版本号、依赖，同时可以声明命令行入口点，方便主pipeline既可以导入API调用，也可以直接起进程调用。
• 所有对外暴露的API都要在__init__.py里明确导出，保持接口稳定，避免主pipeline依赖内部路径。

注意：所有子仓库的包名必须全局唯一，不要出现重名导致导入冲突。

2. 主Pipeline仓库的组织方式 #

主仓库只负责流程编排、全局配置、跨步骤的状态流转，不要包含任何步骤的业务逻辑，结构示例：

main-pipeline/
├── pyproject.toml  # 声明所有子步骤包的依赖
├── pipeline/
│   ├── __init__.py
│   ├── config.py  # 全局配置管理
│   ├── runner.py  # 流程编排逻辑
│   └── state.py  # 跨步骤状态/数据传递管理
└── requirements.txt  # 也可以用requirements代替pyproject.toml声明依赖

3. 主仓库导入子仓库的两种实现方式 #

方式1：直接安装子包后导入API #

适合需要在主进程里直接调用子步骤逻辑、或者需要传递Python对象的场景：

• 在主仓库的依赖文件里声明子仓库的依赖，支持按版本/分支/Commit拉取，示例requirements.txt写法：

  git+https://your-git-host.com/step/step1.git@v1.0.0#egg=step1
  git+https://your-git-host.com/step/step2.git@main#egg=step2
  

• 安装完成后直接在主pipeline代码里导入即可：

  import step1
  import step2
  
  # 调用子步骤的对外API
  res1 = step1.run(config=step1_config)
  res2 = step2.run(input=res1, config=step2_config)
  

方式2：调用子仓库的命令行入口 #

适合子步骤需要作为独立进程运行、隔离资源/环境的场景：

• 子仓库在pyproject.toml里声明入口点，示例：

  [project.scripts]
  run-step1 = "step1.__main__:main"
  

• 子仓库安装完成后，主pipeline可以直接通过subprocess调用，不需要导入Python代码：

  import subprocess
  
  subprocess.run(["run-step1", "--config", "./step1_config.yaml"], check=True)
  subprocess.run(["run-step2", "--input-path", "./step1_output.parquet"], check=True)
  

  这种方式的好处是子步骤可以完全独立运行、甚至可以用不同的Python版本，和主pipeline完全解耦。

4. 可选的优化方案 #

• 如果子步骤迭代频繁，可以用pip install -e的方式本地开发时安装editable版本，改完子步骤代码不需要重新安装就能生效。
• 可以统一用私有PyPI服务器托管所有子步骤的包，主仓库直接按版本号拉取包，不需要写git地址，依赖管理更清晰。
• 所有子步骤的对外接口统一规范，比如都实现run()方法、都支持相同格式的配置传参，主pipeline的编排逻辑可以做通用化封装。

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