Repolode
Submit
Erotemic

Erotemic/xdoctest

A Python package that finds and runs the example code in docstrings, rewriting the builtin doctest module with an AST-based parser.

View on GitHub
Stars
221
Forks
18
Open issues
29
Last commit
3 days ago

What is it?

Xdoctest executes doctests, the example code written inside Python docstrings. It is a rewrite of the standard library doctest module that replaces the regex-based parser with one built on Python's ast module, which lets examples be written with a consistent >>> prefix on every line and multi-line strings without special prefixes.

You can run it from the command line with xdoctest on a module or package path, or through pytest by enabling the --xdoctest flag. The native runner can list doctests, run all of them, or run a single named function's doctest, and it can also run zero-argument functions by name. Parsing supports Google-style Example blocks as well as freeform >>> blocks.

Got/want checking is permissive by default: it ignores whitespace differences, uses ELLIPSIS matching, and passes if either the printed output or the final value matches. Tests without a want statement only need to run without errors, so plain assert statements work for checks.

Key features

  • 01Parses doctests with Python's ast module instead of regular expressions.
  • 02Allows every line to be prefixed with >>>, with no need to distinguish PS1 and PS2 lines.
  • 03Integrates with pytest through the --xdoctest flag.
  • 04Provides a native command line runner that can list, run all, or run a single doctest.
  • 05Supports Google-style and freeform doctest parsing styles.

Use cases

  • Keeping usage examples in docstrings executable in CI alongside unit tests.
  • Checking that a Python package's documentation examples still run after code changes.
  • Writing quick demo inputs in a docstring while developing a function.

Quick start

  1. 1

    Install xdoctest from PyPI

    pip install xdoctest
  2. 2

    Run all doctests in your package or module

    python -m xdoctest /path/to/your/pkg-or-module.py

Things to know

  • Requires Python 3.8 or newer.

In collections

Testing frameworks & test automation tools

Topics

#python#doctest#testing#pytest#docstrings#pytest-plugin

FAQ

What is xdoctest?
A Python package that finds and runs the example code in docstrings, rewriting the builtin doctest module with an AST-based parser. Xdoctest executes doctests, the example code written inside Python docstrings. It is a rewrite of the standard library doctest module that replaces the regex-based parser with one built on Python's ast module, which lets examples be written with a consistent >>> prefix on every line and multi-line strings without special prefixes.
Is xdoctest free to use? What license does it have?
xdoctest is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is xdoctest still maintained?
Actively maintained. The last commit to xdoctest was on Nov 4, 2026.
What can I use xdoctest for?
Keeping usage examples in docstrings executable in CI alongside unit tests. Checking that a Python package's documentation examples still run after code changes. Writing quick demo inputs in a docstring while developing a function.
How do I install xdoctest?
Install xdoctest from PyPI: pip install xdoctest Run all doctests in your package or module: python -m xdoctest /path/to/your/pkg-or-module.py
Where can I get xdoctest?
The source code and installation instructions are on GitHub: https://github.com/Erotemic/xdoctest

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects