Poetry项目中脚本运行时的模块导入问题解析

在Python项目开发中，使用Poetry作为依赖管理工具时，开发者可能会遇到一个常见问题：当通过pyproject.toml定义的脚本运行时，出现ModuleNotFoundError错误，而直接使用Python命令却能正常运行。这种情况通常与Python的模块搜索路径和Poetry的运行环境有关。

问题现象

在一个典型的Poetry项目中，项目结构通常包含src目录存放源代码，tests目录存放测试代码。当开发者尝试通过Poetry脚本运行测试时，测试代码无法导入主程序模块，报错显示找不到模块。然而，直接使用python -m unittest命令却能正常执行测试。

根本原因

这个问题的核心在于Python的模块导入系统和Poetry的运行机制：

1. Python模块搜索路径：Python在导入模块时会按照sys.path中的路径顺序查找。当直接运行测试时，Python会自动将项目根目录加入搜索路径，因此能找到src下的模块。

2. Poetry脚本执行环境：当通过Poetry运行脚本时，执行环境与直接运行有所不同。Poetry会创建一个隔离的虚拟环境，并且默认不会将项目根目录自动加入Python路径。

3. 相对导入问题：测试文件中使用绝对导入（如from indentation_converter import...）时，在Poetry脚本环境下无法解析这种导入方式。

解决方案

针对这个问题，有几种可行的解决方案：

1. 使用pytest替代unittest

pytest作为更现代的测试框架，能更好地处理模块导入问题：

[tool.poetry.dev-dependencies]
pytest = "^7.0"

然后更新脚本：

def test():
    subprocess.run(["pytest", "tests"])

2. 手动设置Python路径

在脚本中显式添加项目根目录到Python路径：

import sys
from pathlib import Path

def test():
    root = str(Path(__file__).parent)
    sys.path.insert(0, root)
    subprocess.run(["python", "-m", "unittest", "discover", "tests"])

3. 使用Poetry的run命令参数

Poetry提供了-E参数可以指定执行环境：

poetry run -E test python -m unittest discover tests

最佳实践建议

1. 统一测试框架：推荐使用pytest而非unittest，它提供了更丰富的功能和更好的模块处理能力。

2. 项目结构规范化：遵循Poetry推荐的项目结构，将主代码放在src目录下，这有助于隔离开发环境和安装环境。

3. 明确依赖关系：确保所有测试依赖都在pyproject.toml的dev-dependencies中明确声明。

4. 考虑使用tox：对于复杂项目，可以考虑使用tox来管理测试环境，它能更好地处理多环境测试需求。

通过理解Poetry的运行机制和Python的模块系统，开发者可以避免这类导入问题，确保项目在不同环境下都能正确运行测试。