{"id":4858,"library":"xdoctest","title":"xdoctest","description":"xdoctest is a powerful and flexible rewrite of Python's builtin `doctest` module, designed for better integration with modern development workflows, especially pytest. It offers enhanced features like static analysis, improved error reporting, and dynamic code execution. The current version is 1.3.2, and it maintains an active release cadence with frequent updates addressing features and bug fixes.","status":"active","version":"1.3.2","language":"en","source_language":"en","source_url":"https://github.com/Erotemic/xdoctest","tags":["testing","doctest","pytest","documentation","test-runner"],"install":[{"cmd":"pip install xdoctest","lang":"bash","label":"Install core library"},{"cmd":"pip install xdoctest[all]","lang":"bash","label":"Install with all optional dependencies"}],"dependencies":[{"reason":"Required for pytest integration, though xdoctest can be used standalone.","package":"pytest","optional":true}],"imports":[{"symbol":"doctest_module","correct":"import xdoctest\nxdoctest.doctest_module('my_module')"},{"note":"Typically used via CLI: `python -m xdoctest`","symbol":"main","correct":"from xdoctest.__main__ import main"},{"note":"Automatically loaded by pytest when xdoctest is installed.","symbol":"plugin","correct":"from xdoctest import plugin"}],"quickstart":{"code":"# my_module.py\ndef add_one(x):\n    \"\"\"\n    >>> add_one(1)\n    2\n    >>> add_one(0)\n    1\n    \"\"\"\n    return x + 1\n\n# Run tests from the command line\n# In your terminal:\n# python -m xdoctest my_module.py\n\n# Or programmatically:\nimport xdoctest\n# For doctesting a specific module (e.g., 'my_module')\nxdoctest.doctest_module('my_module')","lang":"python","description":"Create a Python file with doctests, then run them directly using the xdoctest CLI or programmatically. If pytest is installed, simply running `pytest --xdoctest` will discover and run xdoctests."},"warnings":[{"fix":"Ensure your project uses Python 3.8 or newer. For projects requiring Python 3.6 or 3.7, pin xdoctest to version `<=1.1.6`.","message":"xdoctest dropped support for Python 3.6 and 3.7.","severity":"breaking","affected_versions":">=1.2.0"},{"fix":"Update your CLI commands to remove these flags. xdoctest's dynamic behavior is now handled by default or through other mechanisms. Refer to the official documentation for current CLI options.","message":"The deprecated CLI flags `--xdoc-force-dynamic` and `--allow-xdoc-dynamic` were removed.","severity":"breaking","affected_versions":">=1.3.0"},{"fix":"xdoctest now uses the standard pytest plugin system to disable the stdlib `doctest` module instead of monkey patching. This generally means better compatibility and fewer conflicts, but might affect highly customized test setups. Standard usage (e.g., `pytest --xdoctest`) should continue to work as expected.","message":"When using `xdoctest` with `pytest`, its integration mechanism changed.","severity":"gotcha","affected_versions":">=1.3.0"},{"fix":"Ensure you are on xdoctest version 1.3.2 or later for full and robust support for `async def` function discovery and correct line number reporting. Version 1.3.0 introduced the `ASYNC` directive for managing the asyncio event loop within tests, and 1.2.0 added support for top-level awaits.","message":"Discovering doctests in `async def` functions and using top-level `await` or the `ASYNC` directive.","severity":"gotcha","affected_versions":"<1.3.2 (especially <1.3.0 for `ASYNC` directive)"},{"fix":"Multiple fixes for `modname_to_modpath` were applied in versions 1.1.3, 1.1.4, and 1.1.5. If you encounter errors related to module discovery, particularly with editable installs or when module names differ from package names, ensure you are using xdoctest version 1.1.5 or newer.","message":"Issues with module path resolution, especially for packages installed in editable mode.","severity":"gotcha","affected_versions":"<1.1.5 (especially during 1.1.3 and 1.1.4)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}