编写pyproject.toml实现Python子模块独立构建及导入异常解决

问题场景 #

项目结构固定如下：

project/
   pyproject.toml
   src_dir/
      module1_dir/
         module1_file1.py
         module1_file2.py
         mod1_tests_dir/
      module2_dir/

在module1_file2.py中使用绝对导入：from module1_dir.module1_file1 import var，单元测试正常，但直接执行python module1_file2.py时会报错ModuleNotFoundError: No module named 'module1_dir'。需要编写pyproject.toml实现module1和module2的独立构建，同时支持该导入方式。

错误原因 #

直接运行脚本时，Python的sys.path中未包含src_dir目录，导致无法识别module1_dir作为合法的Python包。

解决方案 #

1. 清除无效配置 #

原配置混用了setuptools和poetry规则（build-backend为setuptools，却配置了tool.poetry），属于无效配置，需移除[tool.poetry]相关内容。

2. 实现独立构建（分模块配置） #

要让两个模块独立构建为单独的包，需为每个模块创建专属的pyproject.toml：

module1的配置（放在src_dir/module1_dir/pyproject.toml）

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

[project]
name = "module1"
version = "0.0.1"
authors = [{name="Me", email="me@me.com"}]
requires-python = ">=3.11"

# 指定包的位置：module1_dir位于上级目录（src_dir）
[tool.setuptools.packages]
packages = ["module1_dir"]
package_dir = {"": "../"}

# 可选：配置控制台入口，避免直接运行脚本
[project.scripts]
module1-run = "module1_dir.module1_file2:main"

module2的配置（放在src_dir/module2_dir/pyproject.toml）

参照module1的配置，将name改为module2，调整packages和scripts对应内容即可。

3. 构建与使用 #

• 构建module1：进入src_dir/module1_dir目录，执行pip wheel .，生成独立的wheel包。
• 安装module1：执行pip install module1-0.0.1-py3-none-any.whl，安装后即可正常使用from module1_dir.module1_file1 import var导入语句。
• 直接测试脚本（无需安装）：在项目根目录执行PYTHONPATH=./src_dir python src_dir/module1_dir/module1_file2.py，临时将src_dir加入Python路径。

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