单代码仓库存放多个Python包的示例及包目录可靠识别方法咨询

常见实际案例 #

单仓托管多个独立Python包（也叫Python monorepo）是工业界非常普遍的做法，典型场景包括：

• 大型工具类项目：比如代码检查、测试框架类项目，会将核心引擎、官方扩展、CLI工具拆分为多个独立发布的包，放在同一个仓库管理，方便版本联动
• 云服务SDK：云厂商的Python SDK通常会按服务类型拆分多个独立包，比如对象存储、云服务器、数据库等服务各对应一个包，全部托管在同一个仓库中
• 业务项目：大型后端业务项目会将通用工具库、业务公共组件、对外API SDK拆分为独立包，统一在同一个仓库迭代

通用可靠的包目录识别方案 #

你可以按照优先级从高到低执行多层校验，几乎可以覆盖所有主流构建工具、所有常规结构的场景：

1. 优先识别独立构建配置 #

每个可独立发布的Python包，必然在自己的根目录下存在专属的构建配置文件，这是最准确的判断依据：

• Poetry、PDM、Hatch等现代构建工具管理的包：目录下存在pyproject.toml，且文件中包含[project]标准字段（PEP 621规范要求）或者对应工具的发布配置块，明确填写了包名name、版本version两个发布必填属性
• Setuptools管理的旧格式包：目录下存在setup.py或setup.cfg文件，且包含包名、版本等发布配置

注意：仓库根目录通常也会有pyproject.toml用于全局依赖管理、任务编排，但不会配置name、version这类发布属性，可以通过这点区分全局配置和单包构建配置

2. 补充校验包结构 #

如果遇到特殊场景下配置文件位置非常规，可以结合Python包的标准结构做二次校验：

• 包根目录下要么直接存在和包名一致的文件夹，里面有至少1个.py模块文件；要么存在src目录，src目录下存在和包名一致的模块文件夹
• 目录下通常包含对应单包的README、LICENSE、变更日志等说明文件

3. 排除非包目录 #

可以提前过滤掉肯定不属于独立发布包的目录，减少误判：

• 测试目录：所有命名为tests、test的目录直接排除
• 非代码目录：docs、examples、scripts、tools这类非发布内容的目录直接排除
• 隐藏目录：.git、.venv、.idea这类隐藏的工具目录直接排除

内容的提问来源于stack exchange，提问作者Nasif Imtiaz Ohi