Skip to main content

Pytest plugin for testing examples in docstrings and markdown files.

Project description

pytest-examples

CI PyPI versions license

Pytest plugin for testing Python code examples in docstrings and markdown files.

pytest-examples can:

  • lint code examples using ruff and black
  • run code examples
  • run code examples and check print statements are inlined correctly in the code

It can also update code examples in place to format them and insert or update print statements.

Installation

pip install -U pytest-examples

Usage

Basic usage

Here's an example basic usage - lint then run examples in the foo_dir directory and the bar_file.py file.

import pytest
from pytest_examples import find_examples, CodeExample, EvalExample


@pytest.mark.parametrize('example', find_examples('foo_dir', 'bar_file.py'), ids=str)
def test_docstrings(example: CodeExample, eval_example: EvalExample):
    eval_example.lint(example)
    eval_example.run(example)

Check print statements

pytest-examples can also check print statements are inserted correctly.

There's the expected format of prints statemints in docstrings:

def add_two_things(a, b):
    """
    ```py
    from my_lib import add_two_things

    print(add_two_things(1, 2))
    #> 3
    ```
    """
    return a + b

And here's an example of a markdown file, again documenting add_two_things:

# How `add_two_things` works

```py
from my_lib import add_two_things

print(add_two_things(1, 2))
#> 3
```

pytest-examples can then run the code and check the print statements are correct:

import pytest
from pytest_examples import find_examples, CodeExample, EvalExample


@pytest.mark.parametrize('example', find_examples('foo_dir'), ids=str)
def test_docstrings(example: CodeExample, eval_example: EvalExample):
    eval_example.run_print_check(example)

Updating files

As well as checking linting and print statements, are correct, we can also update files.

This requires the --update-examples flags AND use of the format() and run_print_update() methods.

Here's a full example of a unit test that checks code when called normally, but can update it when the flag is set:

import pytest
from pytest_examples import find_examples, CodeExample, EvalExample


@pytest.mark.parametrize('example', find_examples('README.md'), ids=str)
def test_readme(example: CodeExample, eval_example: EvalExample):
    if eval_example.update_examples:
        eval_example.format(example)
        eval_example.run_print_update(example)
    else:
        eval_example.lint(example)
        eval_example.run_print_check(example)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pytest_examples-0.0.18.tar.gz (21.2 kB view details)

Uploaded Source

Built Distribution

pytest_examples-0.0.18-py3-none-any.whl (18.2 kB view details)

Uploaded Python 3

File details

Details for the file pytest_examples-0.0.18.tar.gz.

File metadata

  • Download URL: pytest_examples-0.0.18.tar.gz
  • Upload date:
  • Size: 21.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for pytest_examples-0.0.18.tar.gz
Algorithm Hash digest
SHA256 9a464f007f805b113677a15e2f8942ebb92d7d3eb5312e9a405d018478ec9801
MD5 f943223d7da389e68e03265a270edef3
BLAKE2b-256 af714ae972fd95f474454aa450108ee1037830e7ba11840363e981b8d48fd16a

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytest_examples-0.0.18.tar.gz:

Publisher: ci.yml on pydantic/pytest-examples

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pytest_examples-0.0.18-py3-none-any.whl.

File metadata

File hashes

Hashes for pytest_examples-0.0.18-py3-none-any.whl
Algorithm Hash digest
SHA256 86c195b98c4e55049a0df3a0a990ca89123b7280473ab57608eecc6c47bcfe9c
MD5 157d4ba19c428f13173c4cc03d750726
BLAKE2b-256 09527bbfb6e987d9a8a945f22941a8da63e3529465f1b106ef0e26f5df7c780d

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytest_examples-0.0.18-py3-none-any.whl:

Publisher: ci.yml on pydantic/pytest-examples

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page