pytest-examples

What it is and what it does

pytest-examples is a pytest plugin that discovers and validates Python code examples embedded in docstrings and markdown files. It integrates black and ruff to lint examples for style compliance, runs them to verify they execute without error, and can verify that print statements in the code match their expected output (marked with `#>` comments). The plugin can also update examples in place to auto-format code and insert or refresh print statement annotations.

Typical use involves writing a pytest test that parametrizes over examples found in a directory or file, then calling methods like `lint()`, `run()`, `run_print_check()`, or `run_print_update()` on each example. This ensures documentation code stays correct and executable as the underlying library evolves.

Use it for:

• Verify that code examples in API documentation actually run without errors
• Enforce consistent code style in docstrings and README examples using ruff and black
• Validate that printed output in documented examples matches what the code actually produces
• Automatically update and reformat all code examples across a project in one pass
• Catch broken examples early in CI when documentation is changed alongside code

Worth the install?

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

A pytest plugin that finds, lints, runs, and validates Python code examples embedded in docstrings and markdown files, using ruff and black for formatting and checking print statement correctness.

Yes. The plugin fills a real gap—keeping documentation examples in sync with code—and is actively maintained with no known vulnerabilities. Low install friction and permissive MIT license make it a straightforward addition to any pytest-based test suite. Install if you maintain libraries with documented examples and want them to stay correct.

Install

pytest-examples on PyPI

pip install pytest-examples

uv add pytest-examples

poetry add pytest-examples

Installing pytest-examples

Before you install

Low friction install with three runtime dependencies (black, pytest, ruff). Active maintenance with recent commits; last release 465 days ago but repository remains actively developed.

License in practice

MIT license permits free use, modification, and distribution with minimal restrictions—suitable for most commercial and open-source projects.

Quickstart

pip install pytest-examples

import pytest
from pytest_examples import find_examples, CodeExample, EvalExample

@pytest.mark.parametrize('example', find_examples('docs'), ids=str)
def test_examples(example: CodeExample, eval_example: EvalExample):
    eval_example.lint(example)
    eval_example.run(example)

Verify before relying

• Whether the plugin works with pytest versions beyond those implicitly tested in CI
• Performance characteristics when scanning large codebases with many examples

Package facts

Evidence: pytest_examples-0.0.18-py3-none-any.whl

Tags

More Python Modules packages