{"id":5426,"library":"pytest-examples","title":"pytest-examples","description":"pytest-examples is a pytest plugin designed for testing Python code examples found within docstrings and markdown files. It can lint these code examples using tools like ruff and black, run them to verify their correctness, and even check if print statements are inlined as expected. The library is currently at version 0.0.18 and follows an active development and release cadence, often aligning with its upstream `pytest` and `pydantic` projects.","status":"active","version":"0.0.18","language":"en","source_language":"en","source_url":"https://github.com/pydantic/pytest-examples","tags":["pytest","testing","docstrings","markdown","code examples","linting","automation"],"install":[{"cmd":"pip install pytest-examples","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"pytest-examples is a plugin for the pytest testing framework.","package":"pytest","optional":false},{"reason":"Optional linter used by pytest-examples for code example linting.","package":"ruff","optional":true},{"reason":"Optional formatter used by pytest-examples for code example linting/formatting.","package":"black","optional":true}],"imports":[{"note":"pytest-examples operates as a pytest plugin; its functionalities are typically enabled via pytest configuration or command-line flags, rather than direct Python imports from pytest_examples itself in test files. Users will commonly import pytest for writing their tests.","symbol":"pytest","correct":"import pytest"}],"quickstart":{"code":"import pytest\n\n# my_lib.py (example code to be tested)\ndef add_two_things(a, b):\n    \"\"\"\n    Adds two things.\n\n    >>> add_two_things(1, 2)\n    3\n    \"\"\"\n    return a + b\n\n# test_my_lib.py (pytest test file)\ndef test_add_two_things_example():\n    # This test primarily ensures pytest-examples is installed and discoverable.\n    # The actual testing of examples is done by running `pytest`.\n    pass\n\n# To run tests and check examples:\n# 1. Save the above code into 'my_lib.py' and 'test_my_lib.py'\n# 2. Run from your terminal in the same directory: pytest --py-examples\n# 3. To lint and run, and optionally update: pytest --py-examples --update-examples\n","lang":"python","description":"To use `pytest-examples`, ensure it is installed alongside `pytest`. The plugin automatically discovers code examples in docstrings (like the `add_two_things` function above) and markdown files. You typically invoke `pytest` with specific flags to enable `pytest-examples`'s features. The `--py-examples` flag enables example collection and running, and `--update-examples` enables in-place updates for formatting and print statement checks."},"warnings":[{"fix":"Always run `pytest` with `--py-examples` to enable example testing. Add `--update-examples` if you intend to format or update print statements in place.","message":"pytest-examples's features (running, linting, updating examples) are enabled via command-line flags (e.g., `--py-examples`, `--update-examples`). Simply installing the plugin does not automatically activate these checks; you must explicitly include the relevant flags when running `pytest`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review changes carefully after running `pytest --update-examples`. Consider running without `--update-examples` first to see only report failures, then with it only when explicit updates are desired. Use version control to track and revert unwanted changes.","message":"When using the `--update-examples` flag, `pytest-examples` can modify your source files (e.g., to format code or insert/update print statement outputs). It's crucial to understand this behavior to avoid unintended changes, especially in CI/CD environments or when working with version control.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your example code is valid Python syntax. For docstrings, follow standard Python docstring conventions. For markdown, clearly delineate code blocks (e.g., using ````py`). Verify `pytest`'s overall test discovery is working as expected in your project setup.","message":"pytest-examples relies on `pytest`'s test discovery mechanism. If your docstrings or markdown files are not discovered, or if the code within them cannot be correctly parsed or executed by Python, `pytest-examples` might not report issues as expected or might encounter its own errors during collection.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}