{"id":6903,"library":"sybil","title":"Sybil","description":"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.","status":"active","version":"10.0.1","language":"en","source_language":"en","source_url":"https://github.com/simplistix/sybil","tags":["testing","documentation","doctest","pytest","unittest","code examples"],"install":[{"cmd":"pip install sybil","lang":"bash","label":"Base installation"},{"cmd":"pip install sybil[pytest]","lang":"bash","label":"With pytest integration"}],"dependencies":[{"reason":"Required for pytest test runner integration.","package":"pytest","optional":true},{"reason":"Required for MyST (Markdown) documentation parsing.","package":"myst-parser","optional":true}],"imports":[{"symbol":"Sybil","correct":"from sybil import Sybil"},{"symbol":"DocTestParser","correct":"from sybil.parsers.doctest import DocTestParser"},{"symbol":"PythonCodeBlockParser","correct":"from sybil.parsers.codeblock import PythonCodeBlockParser"}],"quickstart":{"code":"import pytest\nfrom os import chdir, getcwd\nfrom shutil import rmtree\nfrom tempfile import mkdtemp\n\nfrom sybil import Sybil\nfrom sybil.parsers.codeblock import PythonCodeBlockParser\nfrom sybil.parsers.doctest import DocTestParser\n\n@pytest.fixture(scope=\"module\")\ndef tempdir():\n    # Example: Create and clean up a temporary directory for tests\n    path = mkdtemp()\n    cwd = getcwd()\n    try:\n        chdir(path)\n        yield path\n    finally:\n        chdir(cwd)\n        rmtree(path)\n\npytest_collect_file = Sybil(\n    parsers=[\n        DocTestParser(),\n        PythonCodeBlockParser(future_imports=['print_function']),\n    ],\n    pattern='*.rst', # Adjust pattern to match your documentation files\n    fixtures=['tempdir'],\n).pytest()","lang":"python","description":"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`."},"warnings":[{"fix":"Add `addopts = -p no:doctest` to your `pytest.ini`, `pyproject.toml`, or `setup.cfg` file under the `[pytest]` section.","message":"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.","severity":"gotcha","affected_versions":"All versions when using pytest"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions when using pytest integration"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}