Sybil

10.0.1 · active · verified Wed Apr 15

Sybil is a Python library designed for automated testing of examples embedded within your code and documentation. It parses examples from various source formats (like reStructuredText, Markdown, and Python docstrings) and evaluates them as part of your standard test suite, integrating with popular test runners such as pytest and unittest. The library is actively maintained, with frequent releases, and is currently at version 10.0.1.

Warnings

gotcha pytest has its own doctest plugin which can conflict with Sybil. Ensure you disable it in your pytest configuration to avoid unexpected behavior or duplicate test runs.
Fix: Add `addopts = -p no:doctest` to your `pytest.ini`, `pyproject.toml`, or `setup.cfg` file under the `[pytest]` section.
gotcha The `path` parameter of the `Sybil` class is ignored when using pytest integration. This can be confusing for users accustomed to its behavior in unittest integration, where it's used to specify the documentation source directory.
Fix: Ensure your `pytest` invocation path allows it to discover the `conftest.py` and the documentation files specified by `pattern`. Sybil's pytest integration handles file discovery via `pytest_collect_file` hooks.
gotcha Incorrectly configuring parsers for your documentation format (e.g., using ReST parsers for Markdown files) will result in examples not being discovered or tested. Sybil provides specific parsers for reStructuredText, Markdown, MyST, and Python code blocks.
Fix: Refer to the Sybil documentation to select the correct `sybil.parsers` for your content. For example, use `sybil.parsers.myst` for MyST Markdown or `sysybil.parsers.codeblock.PythonCodeBlockParser` for Python code.
gotcha The name 'sybil' is used by other Python libraries (e.g., 'sypy' for Sybil node detection, 'sybil' for medical imaging AI). Always ensure you are installing and importing `sybil` (from simplistix/sybil on GitHub) for documentation testing to avoid conflicts or incorrect library usage.
Fix: Verify the PyPI project page (pypi.org/project/sybil) and documentation to confirm you have the correct library. Use specific import statements like `from sybil import Sybil`.

Install

pip install sybil Base installation
pip install sybil[pytest] With pytest integration

Imports

Sybil
```
from sybil import Sybil
```

DocTestParser

from sybil.parsers.doctest import DocTestParser

PythonCodeBlockParser

from sybil.parsers.codeblock import PythonCodeBlockParser

Quickstart

To integrate Sybil with pytest, create a `conftest.py` file in your documentation's root directory. This example configures Sybil to collect doctests and Python code blocks from `.rst` files, and demonstrates how to provide pytest fixtures to the document's namespace. Remember to disable pytest's native doctest plugin in `pytest.ini` or `pyproject.toml`.

import pytest
from os import chdir, getcwd
from shutil import rmtree
from tempfile import mkdtemp

from sybil import Sybil
from sybil.parsers.codeblock import PythonCodeBlockParser
from sybil.parsers.doctest import DocTestParser

@pytest.fixture(scope="module")
def tempdir():
    # Example: Create and clean up a temporary directory for tests
    path = mkdtemp()
    cwd = getcwd()
    try:
        chdir(path)
        yield path
    finally:
        chdir(cwd)
        rmtree(path)

pytest_collect_file = Sybil(
    parsers=[
        DocTestParser(),
        PythonCodeBlockParser(future_imports=['print_function']),
    ],
    pattern='*.rst', # Adjust pattern to match your documentation files
    fixtures=['tempdir'],
).pytest()

view raw JSON →