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

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

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

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

    codeblock_parser_class: type[_CustomPythonCodeBlockParser] = (
        _CustomPythonCodeBlockParser
    )
    """The code block parser class used to validate the examples."""

Attributes

codeblock_parser_class class-attribute instance-attribute

codeblock_parser_class: type[
    _CustomPythonCodeBlockParser
] = _CustomPythonCodeBlockParser

The code block parser class used to validate the examples.

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 src/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"],
    }