pytest-codeblock
Test your documentation code blocks.
pytest-codeblock is a Pytest plugin that discovers Python code examples in your reStructuredText and Markdown documentation files and runs them as part of your test suite. This ensures your docs stay correct and up-to-date.
Features
reStructuredText and Markdown support: Automatically find and test code blocks in reStructuredText (.rst) and Markdown (.md) files. Async code snippets are supported as well.
Grouping: Split a single example across multiple code blocks; the plugin concatenates them into one test.
Pytest markers support: Add existing or custom pytest markers to the code blocks and hook into the tests life-cycle using conftest.py.
Pytest fixtures support: Request existing or custom pytest fixtures for the code blocks.
Prerequisites
Documentation
Documentation is available on Read the Docs.
For reStructuredText, see a dedicated reStructuredText docs.
For Markdown, see a dedicated Markdown docs.
Both reStructuredText docs and Markdown docs have extensive documentation on pytest markers and corresponding conftest.py hooks.
For guidelines on contributing check the Contributor guidelines.
Installation
Install with pip:
pip install pytest-codeblockOr install with uv:
uv pip install pytest-codeblockConfiguration
For most use cases, no configuration needed.
By default, all code blocks with a name starting with test_ will be collected and executed as tests. This allows you to have both test and non-test code blocks in your documentation, giving you flexibility in how you structure your examples.
However, if you want to test all code blocks, you can set test_nameless_codeblocks to true in your pyproject.toml:
Filename: pyproject.toml
[tool.pytest-codeblock]
test_nameless_codeblocks = trueIf you still want to skip some code blocks, you can use built-in or custom pytest markers.
See the dedicated reStructuredText docs and Markdown docs to learn more about pytestmark directive.
Note, that nameless code blocks have limitations when it comes to grouping.
By default, all code .rst and .md files shall be picked automatically.
However, if you need to add another file extension or use or another language identifier for python in codeblock, you could configure that.
See the following example of pyproject.toml configuration:
Filename: pyproject.toml
[tool.pytest-codeblock]
rst_user_codeblocks = ["c_py"]
rst_user_extensions = [".rst.txt"]
md_user_codeblocks = ["c_py"]
md_user_extensions = [".md.txt"]See customisation docs for more.
Usage
reStructruredText usage
Any code directive, such as .. code-block:: python, .. code:: python, or literal blocks with a preceding .. codeblock-name: <name>, will be collected and executed automatically by pytest.
code-block directive example
Filename: README.rst
.. code-block:: python
:name: test_basic_example
import math
result = math.pow(3, 2)
assert result == 9literalinclude directive example
Filename: README.rst
.. literalinclude:: examples/python/basic_example.py
:name: test_li_basic_exampleSee a dedicated reStructuredText docs for more.
Markdown usage
Any fenced code block with a recognized Python language tag (e.g., python, py) will be collected and executed automatically by pytest.
Filename: README.md
```python name=test_basic_example
import math
result = math.pow(3, 2)
assert result == 9
```See a dedicated Markdown docs for more.
Tests
Run the tests with pytest:
pytestTroubleshooting
If something doesn’t work, try to add this to your pyproject.toml:
Filename: pyproject.toml
[tool.pytest.ini_options]
testpaths = [
"**/*.rst",
"**/*.md",
]Writing documentation
Keep the following hierarchy.
=====
title
=====
header
======
sub-header
----------
sub-sub-header
~~~~~~~~~~~~~~
sub-sub-sub-header
^^^^^^^^^^^^^^^^^^
sub-sub-sub-sub-header
++++++++++++++++++++++
sub-sub-sub-sub-sub-header
**************************License
MIT
Support
For security issues contact me at the e-mail given in the Author section.
For overall issues, go to GitHub.
1 maintainer
Release files for pytest-codeblock 0.5.10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pytest_codeblock-0.5.10.tar.gz | 32.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pytest_codeblock-0.5.10-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 66.9 kB
Release files / pytest_codeblock-0.5.10.tar.gz
| Download URL | pytest_codeblock-0.5.10.tar.gz |
|---|---|
| Size | 32.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8a0e7705f3c2225028d06982dba5feec49382fb9b6fed13149d72070cc789b92
|
|
BLAKE2b-256 checksum How to use checksums |
6f4bed0f5647ed7a6fef0ab4a7357fa7c7ae90c2130aa849852b4bfb3762289d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.11
|
Release files / pytest_codeblock-0.5.10-py3-none-any.whl
| Download URL | pytest_codeblock-0.5.10-py3-none-any.whl |
|---|---|
| Size | 34.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7fe1712aec9d999fd085f2c0ced2cd933815441acf3afb3126886ff0b627e143
|
|
BLAKE2b-256 checksum How to use checksums |
accc820b29c62e26c4e3d046beeac6ab814af12fd9326ad67f12587f5e8a3f0f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.11
|
