| 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) |