Coverage for packages/workshop/src/livery/workshop/_pytest_examples.py: 81%

Measured by coverage.py 7.16.2 on CPython 3.14 while the suites of tests, packages/workshop, packages/extensions/ty, packages/extensions/ruff, packages/extensions/python, packages/extensions/pytest, packages/extensions/pyrefly, packages/extensions/nanobind, packages/extensions/mypy, packages/extensions/mkdocstrings, packages/extensions/lfs, packages/extensions/docs, packages/extensions/cpp, packages/extensions/coverage, packages/extensions/conan, packages/extensions/cmake, packages/extensions/claude, packages/extensions/clang-tidy, packages/extensions/clang-format, packages/extensions/changelog, packages/extensions/basedpyright ran.

1"""Run a package's documentation examples, the python files under ``docs/examples/``.
2
3An example is a file a page shows whole or by named section through
4the snippets extension, so the code a reader sees and the code that
5runs are one file. This plugin, loaded through the ``pytest11`` entry
6point, collects every ``docs/examples/**/*.py`` pytest is pointed at
7as one test item per file, executed whole in a fresh module namespace
8under its own path, so a failure's traceback names the example's file
9and line. The python extension's examples runner, the function it
10answers ``python.examples.runner`` with, points pytest at a package's
11examples directory. A package's own setup around an example, a
12registry capture or a recording mode, is its
13``docs/examples/conftest.py``'s business through the ``example``
14marker every item carries; the conftest itself is never an example.
15"""
16
17from __future__ import annotations(empty)
18
19import sys(empty)
20import types(empty)
21from pathlib import Path(empty)
22from typing import TYPE_CHECKING(empty)
23
24import pytest(empty)
25
26from livery.workshop import is_example(empty)
27
28if TYPE_CHECKING:(empty)
29 from collections.abc import Iterator
30
31#: The marker every example item carries, for a conftest's hooks.
32MARKER = "example"(empty)
33
34
35def pytest_configure(config: pytest.Config) -> None:(empty)
36 """Register the marker, so a strict-markers run accepts it."""
37 config.addinivalue_line(
38 "markers", f"{MARKER}: a documentation example, a file under docs/examples/"
39 )
40
41
42def pytest_collect_file((empty)
43 file_path: Path, parent: pytest.Collector
44) -> pytest.Collector | None:
45 """Collect an example file; every other file is another collector's."""
46 if not is_example(file_path):
47 return None
48 return ExampleFile.from_parent(parent, path=file_path)(empty)
49
50
51@pytest.hookimpl(tryfirst=True)(empty)
52def pytest_pycollect_makemodule((empty)
53 module_path: Path, parent: pytest.Collector
54) -> pytest.Collector | None:
55 """Keep pytest's python collector off an example.
56
57 Pytest collects a file named on its command line as a test module
58 whatever its name, and one whose name matches ``python_files`` in
59 a directory it walks. Either way it would import the example
60 outside the setup its conftest gives it, and run the example's
61 ``test_*`` functions as tests of the workspace: a function showing
62 a reader how to test a tasks file then runs the workspace's own
63 gate from inside it. The example stays this plugin's, run whole.
64 """
65 if not is_example(module_path):
66 return None
67 return Withheld.from_parent(parent, path=module_path)(empty)
68
69
70class ExampleFile(pytest.File):(empty)
71 """One example file: one item, the file run whole."""
72
73 def collect(self) -> Iterator[pytest.Item]:(empty)
74 item = ExampleItem.from_parent(self, name=self.path.stem)(empty)
75 item.add_marker(MARKER)(empty)
76 yield item(empty)
77
78
79class Withheld(pytest.File):(empty)
80 """An example as pytest's python collector sees it: nothing to collect."""
81
82 def collect(self) -> Iterator[pytest.Item]:(empty)
83 return iter(())(empty)
84
85
86class ExampleItem(pytest.Item):(empty)
87 """The run of one example file in a fresh module namespace."""
88
89 def runtest(self) -> None:(empty)
90 """Execute the file under its own path; a raise is the failure, at its line."""
91 source = self.path.read_text(encoding="utf-8")
92 code = compile(source, str(self.path), "exec")
93 # A real module in sys.modules, not a bare dict: dataclasses
94 # resolving string annotations and typing's evaluation look
95 # the defining module up by name.
96 module = types.ModuleType(f"docs_example_{self.name.replace('-', '_')}")
97 module.__file__ = str(self.path)
98 sys.modules[module.__name__] = module
99 try:
100 exec(code, module.__dict__)
101 finally:
102 del sys.modules[module.__name__]
103
104 def reportinfo(self) -> tuple[Path, int, str]:(empty)
105 """The file, its first line, and the name the report prints."""
106 return self.path, 0, f"example {self.path.name}"(empty)