xdoctest

What it is and what it does

Xdoctest is a replacement for Python's built-in doctest module that discovers and executes example code written in docstrings. Instead of using regex-based parsing, it employs an abstract-syntax-tree parser for more reliable detection and execution of doctests. The package encourages writing tests and documentation together in the same file, reducing boilerplate and helping developers maintain minimal working examples alongside their code.

You can run xdoctest either as a standalone command-line tool or as a pytest plugin. The standalone interface lets you execute all doctests in a module, list them, dump them as unit tests, or run specific functions' doctests. The pytest integration allows you to run doctests alongside your regular unit tests using a single command, making it practical for CI pipelines. The package is actively maintained, supports Python 3.8 through 3.14, and has no external runtime dependencies.

Use it for:

• Validate example code in function and class docstrings during development or CI to catch documentation drift
• Write minimal working examples in docstrings that serve as both documentation and regression tests
• Run all doctests in a project with a single command to ensure examples remain executable
• Integrate doctest execution into pytest workflows alongside unit tests for comprehensive test coverage
• Debug functions by first writing example inputs and outputs in docstrings, then implementing the body

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Xdoctest finds and executes test code embedded in Python docstrings, replacing the built-in doctest module with an AST-based parser that integrates with pytest or runs standalone.

Yes. Xdoctest is a mature, actively maintained tool with zero dependencies and broad Python support. It solves a real problem—keeping documentation examples in sync with code—and integrates cleanly into both standalone and pytest workflows. The permissive Apache 2 license poses no restriction. Install it if you want to treat docstring examples as executable tests.

Install

xdoctest on PyPI

pip install xdoctest

uv add xdoctest

poetry add xdoctest

Installing xdoctest

Before you install

Installation is straightforward with no runtime dependencies. The package is actively maintained, with a recent release and ongoing commits. It supports modern Python versions (3.8+) across CPython and PyPy implementations.

License in practice

Apache 2 is a permissive license, allowing use in most commercial and open-source projects without significant restriction.

Quickstart

pip install xdoctest

# Run all doctests in a module
python -m xdoctest /path/to/module.py all

# Or with pytest
pytest --xdoctest /path/to/module.py

Requires Python 3.8 or later; Python 2.7 and 3.4–3.7 are no longer supported as of version 1.1.0 and 1.2.0 respectively.

Verify before relying

• Performance characteristics when running doctests on large codebases or deeply nested modules
• Specific AST parsing edge cases or limitations compared to the built-in doctest module
• Compatibility with all pytest plugins or configurations

Package facts

Evidence: xdoctest-1.3.2-py3-none-any.whl

Keywords: xdoctest, doctest, test, docstr, pytest

Tags

More Python Modules packages