{
  "id": "python/pytest-doctest-import-path",
  "signature": "ERROR collecting docs/usage.rst\nE   ModuleNotFoundError: No module named 'mypkg'\n# when running pytest --doctest-glob='*.rst'",
  "signature_zh": "收集 docs/usage.rst 时出错\nE   ModuleNotFoundError: 没有名为 'mypkg' 的模块\n# 运行 pytest --doctest-glob='*.rst' 时",
  "regex": "ERROR\\ collecting\\ docs/usage\\.rst\\\nE\\ \\ \\ ModuleNotFoundError:\\ No\\ module\\ named\\ 'mypkg'\\\n\\#\\ when\\ running\\ pytest\\ \\-\\-doctest\\-glob='\\*\\.rst'",
  "domain": "python",
  "category": "module_error",
  "subcategory": null,
  "root_cause": "Doctests in .rst files are collected from the docs directory, which is not on sys.path, so imports inside code blocks fail even though the package is installed in editable mode.",
  "root_cause_type": "generic",
  "root_cause_zh": "在 .rst 文件中收集 doctest 时，docs 目录不在 sys.path 上，因此代码块中的导入失败，即使包已以可编辑模式安装。",
  "versions": [
    {
      "version": "7.x",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "8.x",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Doctest code blocks are not executable module-level statements; the insert runs but relative to the wrong cwd.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Installs a copy that may not reflect the working tree, causing stale doctest results.",
      "fail_rate": 0.75,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "",
      "success_rate": 0.92,
      "how": "Set pythonpath in pytest.ini so the package is importable from any cwd:\n\n[pytest]\npythonpath = . src\naddopts = --doctest-glob='*.rst'",
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "success_rate": 0.9,
      "how": "Or install editable before running doctests:\n\npip install -e . && pytest --doctest-glob='*.rst' docs/",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": null,
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.85,
  "fix_success_rate": 0.8,
  "resolvable": "true",
  "first_seen": "2025-07-14",
  "last_confirmed": "2025-01-01",
  "last_updated": "2025-01-01",
  "evidence_count": 0,
  "tags": [],
  "locale": "en",
  "aliases": []
}