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.13.tar.gz (20.4 kB view details)

Uploaded Source

Built Distribution

pytest_examples-0.0.13-py3-none-any.whl (17.3 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: pytest_examples-0.0.13.tar.gz
  • Upload date:
  • Size: 20.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.10.14

File hashes

Hashes for pytest_examples-0.0.13.tar.gz
Algorithm Hash digest
SHA256 4d6fd78154953e84444f58f193eb6cc8d853bca7f0ee9f44ea75db043a2c19b5
MD5 99c40547a91ff86a3290ca90b990821c
BLAKE2b-256 0d679d3486460bde76a5fd3709de38eea6cbeab7f41b1fe2c657f52a71b19575

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for pytest_examples-0.0.13-py3-none-any.whl
Algorithm Hash digest
SHA256 8c05cc66459199963c7970ff417300ae7e5b7b4c9d5bd859f1e74a35db75555b
MD5 22519fe73429b193de278135ae96b611
BLAKE2b-256 17c49b639b46dc0aa246847c5d82171d4167218bcceb2108f566e25afdfd229f

See more details on using hashes here.

Supported by

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