Skip to content

livery.workshop._pytest_examples

livery.workshop._pytest_examples

Run a package's documentation examples, the python files under docs/examples/.

An example is a file a page shows whole or by named section through the snippets extension, so the code a reader sees and the code that runs are one file. This plugin, loaded through the pytest11 entry point, collects every docs/examples/**/*.py pytest is pointed at as one test item per file, executed whole in a fresh module namespace under its own path, so a failure's traceback names the example's file and line. The python extension's examples runner, the function it answers python.examples.runner with, points pytest at a package's examples directory. A package's own setup around an example, a registry capture or a recording mode, is its docs/examples/conftest.py's business through the example marker every item carries; the conftest itself is never an example.

Classes:

Name Description
ExampleFile

One example file: one item, the file run whole.

Withheld

An example as pytest's python collector sees it: nothing to collect.

ExampleItem

The run of one example file in a fresh module namespace.

Functions:

Name Description
pytest_configure

Register the marker, so a strict-markers run accepts it.

pytest_collect_file

Collect an example file; every other file is another collector's.

pytest_pycollect_makemodule

Keep pytest's python collector off an example.

Attributes:

Name Type Description
MARKER

MARKER module-attribute

MARKER = 'example'

ExampleFile

Bases: File

One example file: one item, the file run whole.

Methods:

Name Description
collect

collect

collect() -> Iterator[Item]
Source code in packages/workshop/src/livery/workshop/_pytest_examples.py
def collect(self) -> Iterator[pytest.Item]:
    item = ExampleItem.from_parent(self, name=self.path.stem)
    item.add_marker(MARKER)
    yield item

Withheld

Bases: File

An example as pytest's python collector sees it: nothing to collect.

Methods:

Name Description
collect

collect

collect() -> Iterator[Item]
Source code in packages/workshop/src/livery/workshop/_pytest_examples.py
def collect(self) -> Iterator[pytest.Item]:
    return iter(())

ExampleItem

Bases: Item

The run of one example file in a fresh module namespace.

Methods:

Name Description
runtest

Execute the file under its own path; a raise is the failure, at its line.

reportinfo

The file, its first line, and the name the report prints.

runtest

runtest() -> None

Execute the file under its own path; a raise is the failure, at its line.

Source code in packages/workshop/src/livery/workshop/_pytest_examples.py
def runtest(self) -> None:
    """Execute the file under its own path; a raise is the failure, at its line."""
    source = self.path.read_text(encoding="utf-8")
    code = compile(source, str(self.path), "exec")
    # A real module in sys.modules, not a bare dict: dataclasses
    # resolving string annotations and typing's evaluation look
    # the defining module up by name.
    module = types.ModuleType(f"docs_example_{self.name.replace('-', '_')}")
    module.__file__ = str(self.path)
    sys.modules[module.__name__] = module
    try:
        exec(code, module.__dict__)
    finally:
        del sys.modules[module.__name__]

reportinfo

reportinfo() -> tuple[Path, int, str]

The file, its first line, and the name the report prints.

Source code in packages/workshop/src/livery/workshop/_pytest_examples.py
def reportinfo(self) -> tuple[Path, int, str]:
    """The file, its first line, and the name the report prints."""
    return self.path, 0, f"example {self.path.name}"

pytest_configure

pytest_configure(config: Config) -> None

Register the marker, so a strict-markers run accepts it.

Source code in packages/workshop/src/livery/workshop/_pytest_examples.py
def pytest_configure(config: pytest.Config) -> None:
    """Register the marker, so a strict-markers run accepts it."""
    config.addinivalue_line(
        "markers", f"{MARKER}: a documentation example, a file under docs/examples/"
    )

pytest_collect_file

pytest_collect_file(file_path: Path, parent: Collector) -> Collector | None

Collect an example file; every other file is another collector's.

Source code in packages/workshop/src/livery/workshop/_pytest_examples.py
def pytest_collect_file(
    file_path: Path, parent: pytest.Collector
) -> pytest.Collector | None:
    """Collect an example file; every other file is another collector's."""
    if not is_example(file_path):
        return None
    return ExampleFile.from_parent(parent, path=file_path)

pytest_pycollect_makemodule

pytest_pycollect_makemodule(module_path: Path, parent: Collector) -> Collector | None

Keep pytest's python collector off an example.

Pytest collects a file named on its command line as a test module whatever its name, and one whose name matches python_files in a directory it walks. Either way it would import the example outside the setup its conftest gives it, and run the example's test_* functions as tests of the workspace: a function showing a reader how to test a tasks file then runs the workspace's own gate from inside it. The example stays this plugin's, run whole.

Source code in packages/workshop/src/livery/workshop/_pytest_examples.py
@pytest.hookimpl(tryfirst=True)
def pytest_pycollect_makemodule(
    module_path: Path, parent: pytest.Collector
) -> pytest.Collector | None:
    """Keep pytest's python collector off an example.

    Pytest collects a file named on its command line as a test module
    whatever its name, and one whose name matches ``python_files`` in
    a directory it walks. Either way it would import the example
    outside the setup its conftest gives it, and run the example's
    ``test_*`` functions as tests of the workspace: a function showing
    a reader how to test a tasks file then runs the workspace's own
    gate from inside it. The example stays this plugin's, run whole.
    """
    if not is_example(module_path):
        return None
    return Withheld.from_parent(parent, path=module_path)