sybil-extras

What it is and what it does

sybil-extras is a companion package to Sybil that adds optional evaluators and parsers for testing code examples embedded in documentation. It lets you run multiple evaluators on the same code block, execute shell commands (like mypy) against examples, accumulate code blocks for grouped testing, and define custom skip directives with thread-safe semantics. The package is designed for projects that use reStructuredText, Markdown, MyST, MDX, or Djot formats and want to validate that documentation code examples actually work.

You install it alongside Sybil and use its evaluators and parsers in your Sybil configuration. Common workflows include wrapping a custom validation function in MultiEvaluator to apply multiple checks, using ShellCommandEvaluator to run linters or type checkers on code blocks, or using ThreadSafeSkipParser when pytest runs examples concurrently across threads. The package handles file I/O, temporary file creation, and namespace management so you focus on what to test.

Use it for:

• Run mypy or other type checkers on Python code blocks in documentation to catch type errors before release
• Apply multiple validation rules to the same code example using MultiEvaluator (e.g., length checks plus execution)
• Test code examples concurrently across threads without race conditions in skip-directive evaluation
• Accumulate related code blocks from a single document to test them as a group or sequence
• Format or auto-fix code blocks and write the changes back to the source documentation

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides specialized evaluators and parsers that extend Sybil, a documentation testing tool, enabling multi-evaluator chains, shell command execution, code block accumulation, and custom skip directives for testing code examples in documentation.

Yes. sybil-extras fills a real gap for projects that test documentation code examples and need more control than Sybil's built-in evaluators provide. It is actively maintained, has no known vulnerabilities, installs cleanly, and supports current Python versions (3.11–3.14). Install it if you use Sybil and need shell command execution, multi-evaluator chains, or thread-safe concurrent testing.

Install

sybil-extras on PyPI

pip install sybil-extras

uv add sybil-extras

poetry add sybil-extras

Installing sybil-extras

Before you install

Low friction install with a pure-Python wheel. Actively maintained with a recent release (26 days old) and no known vulnerabilities. Requires Python 3.11 or later and depends on four runtime packages including sybil, beartype, and markdown-it-py.

License in practice

MIT license permits free use, modification, and distribution with minimal restrictions, making it suitable for both open-source and commercial projects.

Quickstart

pip install sybil-extras

from sybil import Sybil
from sybil.parsers.rest.codeblock import CodeBlockParser
from sybil_extras.evaluators.multi import MultiEvaluator
from sybil_extras.evaluators.python import PythonEvaluator

evaluators = [PythonEvaluator()]
multi = MultiEvaluator(evaluators=evaluators)
parser = CodeBlockParser(language="python", evaluator=multi)
sybil = Sybil(parsers=[parser])
pytest_collect_file = sybil.pytest()

Requires Python 3.11 or later; Sybil must be installed as a runtime dependency.

Verify before relying

• Whether ThreadSafeSkipParser fully resolves race conditions in all concurrent evaluation scenarios beyond the documented simplistix/sybil#166 issue
• Performance characteristics when accumulating large numbers of code blocks or running shell evaluators across many examples

Package facts

Evidence: sybil_extras-2026.7.19-py3-none-any.whl

Keywords: markdown, rst, sphinx, sybil, testing

Tags

More Testing packages