Debian Codegraph @

tests/doc/test_api_coverage.py

raw
1 """Validate that every public top-level ``pyvista`` symbol is referenced in the API docs.
2
3 A 2026-04 manual audit of the Sphinx reference found 26 undocumented writer
4 classes, 17 error classes, and 37 utility functions because nothing in CI
5 caught a public symbol that lacked an ``autosummary`` entry. This test
6 closes that gap by intersecting the live ``pyvista`` namespace with the
7 names referenced under ``doc/source/api/``.
8 """
9
10 from __future__ import annotations
11
12 import inspect
13 from pathlib import Path
14 import re
15
16 import pytest
17
18 import pyvista as pv
19
20 _REPO_ROOT = Path(__file__).resolve().parents[2]
21 _API_DOC_ROOT = _REPO_ROOT / 'doc' / 'source' / 'api'
22
23 # Directives whose body is an indented block of symbol names.
24 _BLOCK_DIRECTIVES = frozenset({'autosummary'})
25
26 # Directives that name a single target on the same line.
27 _TARGET_DIRECTIVES = frozenset(
28 {
29 'autoclass',
30 'autodata',
31 'autoenum',
32 'autoexception',
33 'autofunction',
34 'automethod',
35 'automodule',
36 'autonamedtuple',
37 'autoproperty',
38 'autotypevar',
39 }
40 )
41
42 _DIRECTIVE_RE = re.compile(r'^\.\.\s+(auto\w+)::\s*(\S*)')
43 _IDENTIFIER_RE = re.compile(r'([A-Za-z_][\w\.]*)')
44
45 # Public symbols re-exported at the top level that are intentionally kept out of
46 # the user-facing reference. Each entry is a low-level VTK/NumPy helper, a
47 # decorator, or an internal base class that ships public for back-compat but is
48 # not meant to appear in the end-user Sphinx reference.
49 # ``CapsuleSource`` is a back-compat shim defined only when ``vtk_version_info < (9, 3)``;
50 # include it in the allowlist exactly when it is actually a public symbol so
51 # ``test_allowlist_stays_accurate`` does not flag a stale entry on newer VTK.
52 _VERSION_CONDITIONAL_UNDOCUMENTED: set[str] = set()
53 if pv.vtk_version_info < (9, 3):
54 _VERSION_CONDITIONAL_UNDOCUMENTED.add('CapsuleSource')
55
56 _ALLOWED_UNDOCUMENTED = frozenset(
57 {
58 'ActorProperties', # similar to Property but uses composition - should be deprecated
59 'AnnotatedIntEnum', # base class for internal int-enum types
60 'BackgroundPlotter', # deprecated and moved to pyvistaqt
61 'BasePlotter', # abstract base; Plotter subclass is documented
62 'FONTS', # internal variable
63 'Grid', # abstract base; concrete Grid subclasses are documented
64 'PointGrid', # abstract base; concrete subclasses are documented
65 'QtDeprecationError', # deprecated and moved to pyvistaqt
66 'QtInteractor', # deprecated and moved to pyvistaqt
67 'Scraper', # internal sphinx gallery tool
68 'VersionInfo', # internal version namedtuple
69 'abstract_class', # decorator, internal
70 'assert_empty_kwargs', # internal kwargs guard
71 'check_depth_peeling', # internal helper
72 'check_math_text_support', # internal matplotlib/vtk compatibility check
73 'check_matplotlib_vtk_compatibility', # internal compatibility check
74 'check_valid_vector', # internal assertion
75 'conditional_decorator', # internal decorator factory
76 'convert_string_array', # low-level VTK string conversion
77 'create_mixed_cells', # low-level cell-array builder
78 'get_mixed_cells', # low-level cell-array reader
79 'get_vtk_type', # low-level VTK dtype helper
80 'image_from_window', # internal helper
81 'ncells_from_cells', # low-level cell-array helper
82 'normalize', # internal helper
83 'numpy_to_idarr', # low-level VTK id-array helper
84 'parse_field_choice', # internal association parser
85 'parse_font_family', # internal helper
86 'raise_has_duplicates', # internal assertion
87 'raise_not_matching', # internal assertion
88 'remove_alpha', # internal helper
89 'row_array', # low-level array-by-row accessor
90 'run_image_filter', # internal helper
91 'scale_point', # internal helper
92 'system_supports_plotting', # internal helper
93 'threaded', # internal threading decorator
94 'try_callback', # internal callback guard
95 'uses_egl', # internal helper
96 'vtk_bit_array_to_char', # low-level VTK bit-array conversion
97 'vtk_id_list_to_array', # low-level VTK id-list conversion
98 'wrap_image_array', # internal helper
99 }
100 | _VERSION_CONDITIONAL_UNDOCUMENTED
101 )
102
103
104 def _is_pyvista_owned(obj: object) -> bool:
105 module = getattr(obj, '__module__', None)
106 return bool(module and module.startswith('pyvista'))
107
108
109 def _collect_public_symbols() -> set[str]:
110 """Every class/function on ``pyvista`` that is defined inside ``pyvista``."""
111 symbols: set[str] = set()
112 for name in {*dir(pv), *dir(pv.plotting)}:
113 if name.startswith('_'):
114 continue
115 obj = getattr(pv, name, None)
116 if obj is None:
117 continue
118 if not (inspect.isclass(obj) or inspect.isfunction(obj)):
119 continue
120 if not _is_pyvista_owned(obj):
121 continue
122 symbols.add(name)
123 return symbols
124
125
126 def _collect_documented_names() -> set[str]:
127 """Every identifier referenced under an autodoc directive in ``doc/source/api``.
128
129 Names are stored by their final dotted segment so that an entry like
130 ``pyvista.core.errors.MissingDataError`` matches the top-level
131 ``pyvista.MissingDataError``.
132 """
133 names: set[str] = set()
134 for rst in _API_DOC_ROOT.rglob('*.rst'):
135 lines = rst.read_text(encoding='utf-8').splitlines()
136 in_block = False
137 block_indent = -1
138 for raw in lines:
139 stripped = raw.strip()
140 match = _DIRECTIVE_RE.match(stripped)
141 if match:
142 directive, target = match.group(1), match.group(2)
143 if directive in _TARGET_DIRECTIVES and target:
144 names.add(target.rsplit('.', 1)[-1])
145 if directive in _BLOCK_DIRECTIVES:
146 in_block = True
147 block_indent = len(raw) - len(raw.lstrip())
148 else:
149 in_block = False
150 continue
151 if not in_block:
152 continue
153 if not stripped:
154 continue
155 indent = len(raw) - len(raw.lstrip())
156 if indent <= block_indent:
157 in_block = False
158 continue
159 if stripped.startswith(':'):
160 continue
161 ident = _IDENTIFIER_RE.match(stripped)
162 if ident:
163 names.add(ident.group(1).rsplit('.', 1)[-1])
164 return names
165
166
167 @pytest.fixture(scope='module')
168 def public_symbols() -> set[str]:
169 return _collect_public_symbols()
170
171
172 @pytest.fixture(scope='module')
173 def documented_names() -> set[str]:
174 return _collect_documented_names()
175
176
177 def test_public_api_is_documented(public_symbols, documented_names):
178 """Every public ``pyvista`` class/function must appear in the Sphinx reference."""
179 missing = sorted(public_symbols - documented_names - _ALLOWED_UNDOCUMENTED)
180 assert not missing, (
181 f'{len(missing)} public pyvista symbol(s) are not referenced under '
182 f'doc/source/api/. Add each to an autosummary block, or - if the '
183 f'symbol is an internal helper that should stay out of the reference '
184 f'- add it to _ALLOWED_UNDOCUMENTED with a one-line rationale:\n ' + '\n '.join(missing)
185 )
186
187
188 def test_allowlist_stays_accurate(public_symbols, documented_names):
189 """Flag stale entries so ``_ALLOWED_UNDOCUMENTED`` does not rot silently."""
190 stale_removed = _ALLOWED_UNDOCUMENTED - public_symbols
191 stale_documented = _ALLOWED_UNDOCUMENTED & documented_names
192 problems = []
193 if stale_removed:
194 problems.append(
195 'No longer public (drop from allowlist): ' + ', '.join(sorted(stale_removed))
196 )
197 if stale_documented:
198 problems.append(
199 'Now documented (drop from allowlist): ' + ', '.join(sorted(stale_documented))
200 )
201 assert not problems, '\n'.join(problems)