sybil

library10.1.0pypypi✓ verified 85d ago

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.

testing

pip install sybil

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · SYBIL

sybil

testingpythonv10.1.0

Install

2.1s avg

Import

46ms

Disk

30MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v9.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.940 runs

installs and imports cleanly · install 0.0s · import 0.048s · 31.2MB

glibc

py 3.10–3.940 runs

installs and imports cleanly · install 2.1s · import 0.044s · 32MB

30MB installed

● package 30MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Sybil

✓ from sybil import Sybil

DocTestParser

✓ from sybil.parsers.doctest import DocTestParser

PythonCodeBlockParser

✓ from sybil.parsers.codeblock import PythonCodeBlockParser

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()

sybil --version

Debug

Known issues

gotchapytest 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.

affects: All versions when using pytest

gotchaThe `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.

affects: All versions when using pytest integration

gotchaIncorrectly 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.

affects: All versions

gotchaThe 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`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'sybil'

The `sybil` library is not installed in the Python environment where `pytest` or your script is being run.

fix

Run `pip install sybil` in your project's virtual environment.

sybil.exceptions.SybilError: Can't parse code block ...

A code example within your documentation or source files contains a syntax error, unexpected output, or an issue preventing `sybil` from parsing or executing it correctly.

fix

Carefully review the indicated code block in your documentation or source file for syntax errors, incorrect indentation, or discrepancies between expected and actual output.

============================= no tests ran in X.YZs ==============================

`sybil`'s pytest integration is either missing or incorrectly configured in your `conftest.py` file, or the paths checked by `pytest` do not contain any `sybil`-parsable examples.

fix

Ensure your `conftest.py` includes `pytest_collect_file = sybil.integration.pytest.pytest_collect_file(...)` with the correct parsers and paths, and verify that `pytest` is run from a directory where it can discover this `conftest.py` and your example files.

TypeError: expected 'sybil.example.ExampleParser' but got <class 'str'>

You are passing parser names as strings (e.g., 'sybil.parsers.doctest') instead of their actual parser objects (e.g., `sybil.parsers.doctest`) to `sybil.integration.pytest.pytest_collect_file` in `conftest.py`.

fix

Pass the actual parser objects (e.g., `sybil.parsers.doctest`, `sybil.parsers.restructuredtext`) directly to the `pytest_collect_file` function.

Upgrade

Version history

10.1.0latest on PyPI · released Jun 13, 2026

Audit

Dependencies

pytestoptionalRequired for pytest test runner integration.

myst-parseroptionalRequired for MyST (Markdown) documentation parsing.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/simplistix/sybil ↗

packagehttps://pypi.org/project/sybil/ ↗

docshttps://sybil.readthedocs.org/en/latest/ ↗

changeloghttps://sybil.readthedocs.io/en/latest/changes.html ↗