examples

frequenz.repo.config.pytest.examples

Utility to enable linting of code examples in docstrings.

Code examples are often wrapped in triple backticks (```python) within our docstrings. This plugin extracts these code examples and validates them using pylint.

The main utility function is get_sybil_arguments(), which returns a dictionary that can be used to pass to the Sybil() constructor.

You still need to create a conftest.py file in the root of your project's sources, typically src/conftest.py, with the following contents:

from frequenz.repo.config.pytest import examples
from sybil import Sybil

pytest_collect_file = Sybil(**examples.get_sybil_arguments()).pytest()

Classes

frequenz.repo.config.pytest.examples.MyPythonCodeBlockParser

Bases: PythonCodeBlockParser

Custom Python code block parser that uses the custom code block parser.

Source code in frequenz/repo/config/pytest/examples.py

class MyPythonCodeBlockParser(PythonCodeBlockParser):
    """Custom Python code block parser that uses the custom code block parser."""

    codeblock_parser_class: type[_CustomPythonCodeBlockParser] = (
        _CustomPythonCodeBlockParser
    )

Functions

frequenz.repo.config.pytest.examples.get_sybil_arguments

get_sybil_arguments() -> dict[str, Any]

Get the arguments to pass when instantiating the Sybil object to lint docs examples.

RETURNS	DESCRIPTION
dict[str, Any]	The arguments to pass when instantiating the Sybil object.

Source code in frequenz/repo/config/pytest/examples.py

def get_sybil_arguments() -> dict[str, Any]:
    """Get the arguments to pass when instantiating the Sybil object to lint docs examples.

    Returns:
        The arguments to pass when instantiating the Sybil object.
    """
    return {
        "parsers": [MyPythonCodeBlockParser()],
        "patterns": ["*.py"],
        # This is a hack because Sybil seems to have issues with `__init__.py` files.
        # See https://github.com/frequenz-floss/frequenz-repo-config-python/issues/113
        # for details
        "excludes": ["__init__.py"],
    }