Python项目中如何从测试目录导入上级api目录的模块？

我正在开发一个Python项目，项目结构如下：

my_project/
    ├── api/
    |     ├── core/
    │     |     ├── magic_box.py  # 内含ContentGenerator类
    │     |     ├── file1.py
    │     |     ├── file2.py
    |     |     ...
    │     ├── module3.py
    │     └── ...
    ├── tests/
    │     ├── test_my_module.py
    │     ├── ...
    └── ...

尝试在tests/test_my_module.py中导入api.core.magic_box里的ContentGenerator时触发导入错误，现有代码如下：

import unittest
from api.core import ContentGenerator

class TestMagicBox(unittest.TestCase):
    content_generator = ContentGenerator()

    def test_caption(self):
        result = TestMagicBox.content_generator.generate_description(
            "pizza", "peperoni pizza"
        )
        self.assertIsNotNone(result)

if __name__ == "__main__":
    unittest.main()

方案1：临时添加项目根目录到Python路径（快速临时解决） #

在测试文件开头添加代码，将项目根目录（my_project）加入Python的模块搜索路径：

import os
import sys
# 获取当前测试文件的目录，再向上跳一级到项目根目录
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))

import unittest
from api.core.magic_box import ContentGenerator  # 明确指定magic_box模块

class TestMagicBox(unittest.TestCase):
    content_generator = ContentGenerator()

    def test_caption(self):
        result = self.content_generator.generate_description(
            "pizza", "peperoni pizza"
        )
        self.assertIsNotNone(result)

if __name__ == "__main__":
    unittest.main()

注意：这种方式适合快速验证，但长期维护建议采用更规范的方案。

方案2：使用相对导入（需配合特定运行方式） #

将tests目录当作项目子模块，用相对导入修改测试文件：

import unittest
from ..api.core.magic_box import ContentGenerator

class TestMagicBox(unittest.TestCase):
    content_generator = ContentGenerator()

    def test_caption(self):
        result = self.content_generator.generate_description(
            "pizza", "peperoni pizza"
        )
        self.assertIsNotNone(result)

运行测试时必须从项目根目录执行，且使用模块调用方式，不能直接运行测试文件：

# 在my_project目录下执行
python -m unittest tests.test_my_module

注意：直接运行tests/test_my_module.py会触发相对导入报错，因为相对导入仅适用于包内部。

方案3：将项目打包为可安装包（最符合可维护规范） #

这是长期项目的最优解，通过配置文件将项目声明为可安装包，测试代码可直接正常导入模块。

1. 在my_project目录下创建pyproject.toml文件：

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

[project]
name = "my_project"
version = "0.1.0"
packages = ["api"]

2. 以开发模式安装项目（修改代码后无需重新安装）：

# 在my_project目录下执行
pip install -e .

3. 测试文件无需额外路径处理，直接正常导入：

import unittest
from api.core.magic_box import ContentGenerator

class TestMagicBox(unittest.TestCase):
    content_generator = ContentGenerator()

    def test_caption(self):
        result = self.content_generator.generate_description(
            "pizza", "peperoni pizza"
        )
        self.assertIsNotNone(result)

if __name__ == "__main__":
    unittest.main()

这种方式完全符合Python包管理规范，适合团队协作和长期维护。

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