Tox中Pytest无法导入Python子包，本地运行正常的问题咨询

背景 #

我在学习Python的pytest和tox自动化测试时，使用SlapThatLikeButton-TestingStarterProject仓库。克隆仓库后执行以下步骤：

• 创建虚拟环境
• 执行pip install -r requirements_dev.txt
• 执行pip install -e .
  本地pytest和tox均运行成功。

目录结构调整 #

之后调整了src目录结构：新增src/models子包，将slap_that_like_button.py移至该子包，并更新测试用例的导入路径。

新目录结构 #

src
├── slapping
    ├── __init__.py
    ├── models
    │   ├── __init__.py
    │   └── slap_that_like_button.py
    └── py.typed

测试文件变更 #

diff --git a/tests/test_slapping.py b/tests/test_slapping.py
index 40ed2f4..8298ec5 100644
--- a/tests/test_slapping.py
+++ b/tests/test_slapping.py
@@ -1,5 +1,5 @@
 import pytest
-from slapping.slap_that_like_button import LikeState, slap_many
+from slapping.models.slap_that_like_button import LikeState, slap_many


def test_empty_slap():

问题现象 #

本地终端运行pytest成功，但tox中执行pytest时报错ModuleNotFoundError: No module named 'slapping.models'。

疑问 #

1. 为何本地pytest正常，tox中找不到子包？
2. 模块移至子包为何会导致这种差异？

补充提示 #

建议将requirements_dev.txt中的tox版本升级至4.11.4，否则会触发另一个报错。

解决方法 #

在tox.ini中添加package = editable配置后问题解决，配置变更如下：

$ git diff tox.ini
diff --git a/tox.ini b/tox.ini
index 6b58ff8..8730352 100644
--- a/tox.ini
+++ b/tox.ini
@@ -13,6 +13,7 @@ python =
 [testenv]
 setenv =
     PYTHONPATH = {toxinidir}
+package = editable
 deps =
     -r{toxinidir}/requirements_dev.txt
 commands =

根因分析 #

1. 本地与tox的环境差异：

   • 本地执行了pip install -e .（可编辑安装），Python会直接从源码目录加载包，子包结构变更后能被正确识别。
   • 默认情况下，tox会将项目打包后安装到隔离环境中，而非使用可编辑模式。如果打包配置（如setup.py或pyproject.toml）没有及时更新以包含新的models子包，打包后的安装包就不会包含该子包，导致tox环境中找不到slapping.models模块。

2. 模块移至子包的影响：

   • 原结构中模块直接在slapping包下，打包配置默认会包含该目录下的所有模块；新增子包后，若打包配置未明确包含子包（或依赖自动发现的规则未覆盖），打包过程会忽略新增的models子包，从而导致安装后的环境缺失该模块。
   • 添加package = editable后，tox会以可编辑模式安装项目，和本地环境一致，直接从源码加载所有子包，因此能找到slapping.models。

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