# ValueError: mypkg.mod 的文档字符串第 1 行示例后缺少空行

- **ID:** `python/pytest-doctest-module-not-found`
- **领域:** python
- **类别:** data_error
- **验证级别:** ai_generated
- **修复率:** 80%

## 根因

pytest --doctest-modules 将文档字符串解析为 doctest；'>>>' 块后缺少空行或缩进错误会在收集阶段触发此 ValueError。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| 7.x | active | — | — |
| 8.x | active | — | — |

## 解决方案

1. **** (94% 成功率)
   ```
   def add(a, b):
    """Return a + b.

    >>> add(1, 2)
    3

    """
    return a + b
   ```
2. **** (88% 成功率)
   ```
   # pyproject.toml
[tool.pytest.ini_options]
addopts = "--doctest-modules"
doctest_optionflags = ["NORMALIZE_WHITESPACE", "ELLIPSIS"]
   ```

## 无效尝试

- **** — Skips legitimate doctests and hides the formatting bug; other modules with the same issue still fail. (70% 失败率)
- **** — Loses documentation and breaks help() output; doesn't address the formatting pattern for future modules. (75% 失败率)