Debian Codegraph @

pyvista/core/utilities/accessor_registry.py

raw
1 """Registry for third-party dataset accessors.
2
3 This module implements the pandas/xarray-style accessor pattern for PyVista
4 dataset classes. Plugin packages attach a namespaced accessor to a target
5 class at import time; the accessor is constructed lazily on first access
6 per dataset instance and cached on the instance.
7
8 Two registration paths are supported:
9
10 1. **Explicit import.** A plugin's module runs the
11 :func:`register_dataset_accessor` decorator at import time, so any
12 user that does ``import plugin`` gets the accessor attached.
13 2. **Entry points.** A plugin declares a ``pyvista.accessors`` entry
14 point in its ``pyproject.toml`` pointing at its accessor module.
15 PyVista reads the entry-point metadata lazily (no plugin module is
16 imported at ``import pyvista`` time). The plugin module imports only
17 when a user first accesses ``dataset.<name>`` on any dataset and the
18 normal attribute lookup misses. That isolates broken or slow plugins
19 from the main ``import pyvista`` path.
20
21 See Also
22 --------
23 pyvista.register_dataset_accessor
24 pyvista.unregister_dataset_accessor
25 pyvista.registered_accessors
26
27 """
28
29 from __future__ import annotations
30
31 import contextlib
32 from importlib import import_module
33 from importlib.metadata import entry_points
34 from typing import TYPE_CHECKING
35 from typing import Any
36 from typing import NamedTuple
37 from typing import Protocol
38 from typing import TypedDict
39 from typing import runtime_checkable
40
41 from pyvista._warn_external import warn_external
42
43 if TYPE_CHECKING:
44 from collections.abc import Callable
45
46
47 ACCESSOR_ENTRY_POINT_GROUP = 'pyvista.accessors'
48
49
50 @runtime_checkable
51 class DataSetAccessor(Protocol):
52 """Structural protocol for third-party accessor classes.
53
54 An accessor class must accept the dataset instance as its single
55 ``__init__`` argument. Any public methods on the class become
56 available as ``dataset.<namespace>.<method>(...)`` once the class is
57 registered with :func:`~pyvista.register_dataset_accessor`.
58
59 This Protocol exists primarily for static type analysis: plugin
60 authors can annotate ``accessor_cls: type[DataSetAccessor]`` (or
61 use it as a return annotation) to have mypy/pyright check that
62 their accessor class conforms. The runtime ``isinstance`` check is
63 intentionally permissive (every class has ``__init__``), so prefer
64 the static-typing use.
65
66 .. versionadded:: 0.48.0
67
68 Examples
69 --------
70 Declare an accessor that satisfies the protocol.
71
72 >>> from pyvista import DataSetAccessor
73 >>> class MyAccessor:
74 ... def __init__(self, dataset):
75 ... self._dataset = dataset
76 >>> isinstance(MyAccessor(None), DataSetAccessor)
77 True
78
79 """
80
81 def __init__(self, dataset: Any) -> None: ...
82
83
84 class AccessorRegistration(NamedTuple):
85 """Describe one registered dataset accessor.
86
87 Returned by :func:`~pyvista.registered_accessors`.
88
89 .. versionadded:: 0.48.0
90
91 Attributes
92 ----------
93 name : str
94 The namespace the accessor is attached under (e.g. ``'meshfix'``).
95 target : type
96 The PyVista dataset class (or base class) the accessor is
97 registered against.
98 accessor : type
99 The accessor class itself.
100 source : str
101 Human-readable origin in the form ``'module.qualname'`` — useful
102 for debugging which plugin registered a given accessor.
103
104 """
105
106 name: str
107 target: type
108 accessor: type
109 source: str
110
111
112 class _AccessorRegistryState(TypedDict):
113 """Stored registry state used for test isolation.
114
115 Records every ``(target_cls, name)`` the registry has touched along
116 with the value that was present on the class dictionary before the
117 accessor replaced it (sentinel if the attribute did not exist).
118 """
119
120 registrations: list[AccessorRegistration]
121 # Per (target, name), the exact attribute that was in target.__dict__
122 # before registration, or _MISSING if no attribute existed.
123 prior: dict[tuple[type, str], Any]
124 # Snapshot of each target class's current binding for each registered
125 # name so restore can diff against "live" state.
126 attached: dict[tuple[type, str], Any]
127 # Whether entry-point metadata has already been scanned. Tests that
128 # mock ``entry_points`` reset this to force a re-scan.
129 entry_points_loaded: bool
130 # Accessor names declared via entry points that have not yet had
131 # their plugin module imported. Populated by ``_ensure_entry_points``
132 # and consumed by ``_resolve_pending_accessor`` on first attribute
133 # miss.
134 pending: dict[str, str]
135
136
137 class _CachedAccessor:
138 """Non-data descriptor implementing the pandas/xarray accessor pattern.
139
140 The first time ``obj.<name>`` is accessed, ``accessor_cls(obj)`` is
141 constructed and stored in ``obj.__dict__[name]``. Subsequent lookups
142 bypass the descriptor and hit ``__dict__`` directly because a
143 non-data descriptor yields to instance ``__dict__``.
144
145 When the target class uses ``__slots__`` and no ``__dict__`` is
146 available, the accessor is constructed fresh on each access — slower
147 but still correct.
148 """
149
150 def __init__(self, name: str, accessor_cls: type) -> None:
151 self._name = name
152 self._accessor_cls = accessor_cls
153
154 def __repr__(self) -> str: # pragma: no cover - trivial
155 return f'<_CachedAccessor name={self._name!r} cls={self._accessor_cls!r}>'
156
157 def __get__(self, obj: Any, objtype: type | None = None) -> Any:
158 if obj is None:
159 # Class-level access returns the accessor class itself so
160 # ``help(cls.<name>)`` shows the accessor docstring.
161 return self._accessor_cls
162 accessor_instance = self._accessor_cls(obj)
163 # Skip the cache on ``__slots__`` targets (no ``__dict__``) and
164 # construct fresh on each access.
165 with contextlib.suppress(AttributeError):
166 obj.__dict__[self._name] = accessor_instance
167 return accessor_instance
168
169
170 # ``_MISSING`` marks "attribute did not exist on the target class dict
171 # before we touched it" so unregister can tell the difference between
172 # "restore nothing" and "restore a prior value of None".
173 _MISSING: Any = object()
174
175 _registrations: list[AccessorRegistration] = []
176 _prior_values: dict[tuple[type, str], Any] = {}
177 _entry_points_loaded: bool = False
178 _pending_accessors: dict[str, str] = {}
179
180
181 def _save_registry_state() -> _AccessorRegistryState:
182 """Snapshot the current registry state for later restoration."""
183 attached: dict[tuple[type, str], Any] = {}
184 for record in _registrations:
185 key = (record.target, record.name)
186 attached[key] = record.target.__dict__.get(record.name, _MISSING)
187 return {
188 'registrations': list(_registrations),
189 'prior': dict(_prior_values),
190 'attached': attached,
191 'entry_points_loaded': _entry_points_loaded,
192 'pending': dict(_pending_accessors),
193 }
194
195
196 def _restore_registry_state(state: _AccessorRegistryState) -> None:
197 """Restore registry state from a snapshot.
198
199 Removes any accessors that have been added since the snapshot was
200 taken and re-attaches any that were removed, putting prior built-in
201 attributes back if override had shadowed them.
202 """
203 global _entry_points_loaded # noqa: PLW0603
204 current_keys = {(r.target, r.name) for r in _registrations}
205 snapshot_keys = {(r.target, r.name) for r in state['registrations']}
206
207 # Remove anything that was not in the snapshot.
208 for record in _registrations:
209 key = (record.target, record.name)
210 if key in snapshot_keys:
211 continue
212 attr = record.target.__dict__.get(record.name)
213 if isinstance(attr, _CachedAccessor):
214 delattr(record.target, record.name)
215 prior = _prior_values.pop(key, _MISSING)
216 if prior is not _MISSING:
217 setattr(record.target, record.name, prior)
218
219 # Re-add anything that was in the snapshot but has since been
220 # removed, restoring the descriptor binding that was live at
221 # snapshot time.
222 for record in state['registrations']:
223 key = (record.target, record.name)
224 attached_at_snapshot = state['attached'].get(key, _MISSING)
225 if attached_at_snapshot is _MISSING:
226 if record.name in record.target.__dict__:
227 delattr(record.target, record.name)
228 elif (
229 key not in current_keys
230 or record.target.__dict__.get(record.name) is not attached_at_snapshot
231 ):
232 setattr(record.target, record.name, attached_at_snapshot)
233
234 _registrations.clear()
235 _registrations.extend(state['registrations'])
236 _prior_values.clear()
237 _prior_values.update(state['prior'])
238 _entry_points_loaded = state['entry_points_loaded']
239 _pending_accessors.clear()
240 _pending_accessors.update(state['pending'])
241
242
243 def _find_accessor_on_mro(target_cls: type, name: str) -> type | None:
244 """Return the class whose ``__dict__`` owns the accessor.
245
246 Walks ``target_cls.__mro__`` and returns the first class whose
247 ``__dict__`` holds a :class:`_CachedAccessor` under ``name``, or
248 ``None`` if none exists.
249 """
250 for klass in target_cls.__mro__:
251 attr = klass.__dict__.get(name)
252 if isinstance(attr, _CachedAccessor):
253 return klass
254 return None
255
256
257 def _find_shadow_on_mro(target_cls: type, name: str) -> type | None:
258 """Return the class shadowing ``name`` with a non-accessor attribute.
259
260 Walks ``target_cls.__mro__`` (skipping ``object``) and returns the
261 first class that defines a non-accessor attribute under ``name``, or
262 ``None`` if none exists. Used to detect built-in attribute
263 shadowing.
264 """
265 for klass in target_cls.__mro__:
266 if klass is object:
267 continue
268 if name not in klass.__dict__:
269 continue
270 attr = klass.__dict__[name]
271 if isinstance(attr, _CachedAccessor):
272 return None # an accessor wins over any further shadow search
273 return klass
274 return None
275
276
277 def _validate_name(name: object) -> str:
278 """Normalize and validate an accessor name.
279
280 Accepts ``object`` so the ``isinstance`` check is reachable for
281 callers that bypass static typing (e.g. dynamic plugin loaders or
282 tests that intentionally pass the wrong type).
283 """
284 if not isinstance(name, str):
285 msg = f'Accessor name must be a string, got {type(name).__name__}.'
286 raise TypeError(msg)
287 normalized = name.strip()
288 if not normalized:
289 msg = 'Accessor name must not be empty.'
290 raise ValueError(msg)
291 if normalized.startswith('_'):
292 msg = (
293 f'Accessor name must not start with an underscore, got {name!r}. '
294 'Leading underscores are reserved for PyVista internals.'
295 )
296 raise ValueError(msg)
297 if not normalized.isidentifier():
298 msg = f'Accessor name must be a valid Python identifier, got {name!r}.'
299 raise ValueError(msg)
300 return normalized
301
302
303 def _validate_target(target_cls: Any) -> type:
304 """Validate that ``target_cls`` is a class."""
305 if not isinstance(target_cls, type):
306 msg = f'target_cls must be a class, got {type(target_cls).__name__}.'
307 raise TypeError(msg)
308 return target_cls
309
310
311 def register_dataset_accessor(
312 name: str,
313 target_cls: type,
314 *,
315 override: bool = False,
316 ) -> Callable[[type], type]:
317 """Register a custom namespaced accessor on a PyVista dataset class.
318
319 Mirrors the accessor pattern used by
320 `pandas <https://pandas.pydata.org/docs/development/extending.html#registering-custom-accessors>`_
321 and `xarray <https://docs.xarray.dev/en/stable/internals/extending-xarray.html>`_.
322 Once registered, the accessor becomes available as
323 ``dataset.<name>.<method>(...)`` on every instance of ``target_cls``
324 and its subclasses. The accessor class is instantiated lazily on
325 first access and cached on the dataset instance, so subsequent
326 accesses return the same accessor object.
327
328 .. versionadded:: 0.48.0
329
330 Parameters
331 ----------
332 name : str
333 The namespace the accessor will be attached under. Must be a
334 valid Python identifier that does not start with an underscore.
335
336 target_cls : type
337 The PyVista dataset class (or base class) to attach the accessor
338 to. Registering against :class:`~pyvista.DataSet` exposes the
339 accessor on every subclass (``PolyData``, ``UnstructuredGrid``,
340 ``ImageData``, and so on). Registering against
341 :class:`~pyvista.DataObject` additionally covers
342 :class:`~pyvista.MultiBlock`.
343
344 override : bool, default: False
345 If ``True``, allow registering a name that shadows an existing
346 built-in attribute on ``target_cls`` (a filter method, property,
347 or any other non-accessor attribute). The prior attribute is
348 restored on :func:`~pyvista.unregister_dataset_accessor`.
349
350 Returns
351 -------
352 callable
353 Decorator that registers the accessor class passed to it and
354 returns that class unchanged.
355
356 Raises
357 ------
358 ValueError
359 If ``name`` is empty, not a valid identifier, starts with ``_``,
360 or shadows a built-in attribute on ``target_cls`` without
361 ``override=True``.
362
363 TypeError
364 If ``target_cls`` is not a class, or ``name`` is not a string.
365
366 Warns
367 -----
368 UserWarning
369 If ``name`` already refers to a registered accessor on
370 ``target_cls`` or any ancestor. Emitting a warning rather than
371 raising matches pandas' behavior and avoids hard-failing when
372 two plugins collide.
373
374 See Also
375 --------
376 pyvista.unregister_dataset_accessor
377 pyvista.registered_accessors
378 pyvista.DataSetAccessor
379
380 Examples
381 --------
382 Register a minimal accessor on :class:`~pyvista.PolyData`.
383
384 >>> import pyvista as pv
385 >>> @pv.register_dataset_accessor('demo', pv.PolyData)
386 ... class DemoAccessor:
387 ... def __init__(self, mesh):
388 ... self._mesh = mesh
389 ...
390 ... def n_points_doubled(self):
391 ... return self._mesh.n_points * 2
392 >>> sphere = pv.Sphere()
393 >>> sphere.demo.n_points_doubled() == sphere.n_points * 2
394 True
395
396 The accessor is cached per instance. Repeated access returns the
397 same object.
398
399 >>> sphere.demo is sphere.demo
400 True
401
402 Clean up so the namespace is not visible to later doctest examples.
403
404 >>> pv.unregister_dataset_accessor('demo', pv.PolyData)
405
406 """
407 normalized = _validate_name(name)
408 target = _validate_target(target_cls)
409
410 # Accept ``object`` so the runtime guard is reachable when callers
411 # (e.g. dynamic plugin loaders) bypass static typing.
412 def decorator(accessor_cls: object) -> type:
413 if not isinstance(accessor_cls, type):
414 msg = f'Accessor must be a class, got {type(accessor_cls).__name__}.'
415 raise TypeError(msg)
416 _attach_accessor(normalized, target, accessor_cls, override=override)
417 return accessor_cls
418
419 return decorator
420
421
422 def _attach_accessor(
423 name: str,
424 target_cls: type,
425 accessor_cls: type,
426 *,
427 override: bool,
428 ) -> None:
429 """Attach ``accessor_cls`` as a ``_CachedAccessor`` on ``target_cls``.
430
431 Performs collision detection before attaching.
432 """
433 accessor_owner = _find_accessor_on_mro(target_cls, name)
434 if accessor_owner is not None:
435 existing = accessor_owner.__dict__.get(name)
436 if (
437 accessor_owner is target_cls
438 and isinstance(existing, _CachedAccessor)
439 and existing._accessor_cls is accessor_cls
440 ):
441 # Idempotent re-registration: the exact same accessor class is
442 # already bound directly on this target under this name. This
443 # happens when a module that registers an accessor is imported
444 # twice (e.g. ``pytest --cov`` re-executes it). It is a true
445 # no-op, not a plugin collision, so do not warn or re-bind --
446 # warning here would be fatal for downstream packages running
447 # under ``filterwarnings=error``.
448 return
449 # Accessor-vs-accessor collision — warn and replace (pandas style).
450 if accessor_owner is target_cls:
451 location = target_cls.__qualname__
452 else:
453 location = f'{accessor_owner.__qualname__} (inherited by {target_cls.__qualname__})'
454 warn_external(
455 f'Registering accessor {name!r} on {target_cls.__qualname__} '
456 f'replaces an existing registered accessor on {location}.',
457 )
458 else:
459 shadow_owner = _find_shadow_on_mro(target_cls, name)
460 if shadow_owner is not None and not override:
461 if shadow_owner is target_cls:
462 location = target_cls.__qualname__
463 else:
464 location = f'{shadow_owner.__qualname__} (inherited by {target_cls.__qualname__})'
465 msg = (
466 f'Cannot register accessor {name!r} on '
467 f'{target_cls.__qualname__}: shadows built-in attribute on '
468 f'{location}. Pass override=True to force.'
469 )
470 raise ValueError(msg)
471
472 # Record the prior attribute value only on first registration for
473 # this (target, name) pair so repeated override+register cycles do
474 # not forget the very first built-in attribute.
475 key = (target_cls, name)
476 if key not in _prior_values:
477 _prior_values[key] = target_cls.__dict__.get(name, _MISSING)
478
479 setattr(target_cls, name, _CachedAccessor(name, accessor_cls))
480
481 source = f'{accessor_cls.__module__}.{accessor_cls.__qualname__}'
482 # Remove any previous registration record for this (target, name) pair
483 # so the registry state never reports duplicates.
484 _registrations[:] = [
485 r for r in _registrations if not (r.target is target_cls and r.name == name)
486 ]
487 _registrations.append(
488 AccessorRegistration(
489 name=name,
490 target=target_cls,
491 accessor=accessor_cls,
492 source=source,
493 ),
494 )
495
496
497 def unregister_dataset_accessor(name: str, target_cls: type) -> None:
498 """Remove an accessor previously attached to a target class.
499
500 The inverse of :func:`~pyvista.register_dataset_accessor`. Restores
501 any built-in attribute that was shadowed via ``override=True`` when
502 the accessor was registered.
503
504 .. versionadded:: 0.48.0
505
506 Parameters
507 ----------
508 name : str
509 Namespace of the accessor to remove.
510 target_cls : type
511 Target class the accessor was registered against. Only accessors
512 attached directly on ``target_cls`` can be unregistered; an
513 accessor inherited from a parent class must be unregistered on
514 that parent.
515
516 Raises
517 ------
518 ValueError
519 If no accessor named ``name`` is attached directly to
520 ``target_cls``.
521
522 TypeError
523 If ``target_cls`` is not a class, or ``name`` is not a string.
524
525 Examples
526 --------
527 >>> import pyvista as pv
528 >>> @pv.register_dataset_accessor('tmp', pv.PolyData)
529 ... class TmpAccessor:
530 ... def __init__(self, mesh):
531 ... self._mesh = mesh
532 >>> pv.unregister_dataset_accessor('tmp', pv.PolyData)
533
534 """
535 normalized = _validate_name(name)
536 target = _validate_target(target_cls)
537
538 attr = target.__dict__.get(normalized)
539 if not isinstance(attr, _CachedAccessor):
540 # ValueError (not TypeError) — the shape of the target is valid,
541 # the caller just did not have an accessor to remove.
542 msg = f'No registered accessor {name!r} attached directly to {target.__qualname__}.'
543 raise ValueError(msg) # noqa: TRY004
544
545 key = (target, normalized)
546 prior = _prior_values.pop(key, _MISSING)
547 if prior is _MISSING:
548 delattr(target, normalized)
549 else:
550 setattr(target, normalized, prior)
551
552 _registrations[:] = [
553 r for r in _registrations if not (r.target is target and r.name == normalized)
554 ]
555
556
557 def _ensure_entry_points() -> None:
558 """Scan ``pyvista.accessors`` entry-point metadata once.
559
560 Populates :data:`_pending_accessors` with a mapping of
561 ``name -> module_path`` for every declared entry point. The plugin
562 modules themselves are **not** imported here; the cost of this
563 function is one ``importlib.metadata.entry_points`` call. The
564 plugin import is deferred to :func:`_resolve_pending_accessor`,
565 which runs only when the corresponding accessor is actually
566 accessed on a dataset.
567 """
568 global _entry_points_loaded # noqa: PLW0603
569 if _entry_points_loaded:
570 return
571
572 # Flip the flag before iterating so a plugin that happens to import
573 # pyvista recursively does not loop back into this function.
574 _entry_points_loaded = True
575 for accessor_entry_point in entry_points(group=ACCESSOR_ENTRY_POINT_GROUP):
576 _pending_accessors[accessor_entry_point.name] = accessor_entry_point.value
577
578
579 def _resolve_pending_accessor(name: str) -> bool:
580 """Import the plugin module registered under ``name``, if any.
581
582 Called from :meth:`pyvista.DataObject.__getattr__` when a normal
583 attribute lookup misses. Ensures entry-point metadata has been
584 scanned, pops the pending entry for ``name``, and imports the
585 corresponding plugin module. Importing the module triggers any
586 ``@register_dataset_accessor`` decorators inside it and attaches
587 the accessor as a side effect.
588
589 Returns
590 -------
591 bool
592 ``True`` if a plugin was loaded for ``name`` (and the attribute
593 lookup should be retried). ``False`` if no pending plugin
594 matches ``name``, or if the plugin failed to import.
595
596 Notes
597 -----
598 A plugin that fails to import emits a ``UserWarning`` and is
599 dropped from the pending list, so subsequent lookups of the same
600 name fall straight through without re-triggering the import or
601 re-emitting the warning.
602
603 """
604 _ensure_entry_points()
605 module_path = _pending_accessors.pop(name, None)
606 if module_path is None:
607 return False
608 try:
609 import_module(module_path)
610 except Exception as exc: # noqa: BLE001
611 msg = (
612 f'Failed to load {ACCESSOR_ENTRY_POINT_GROUP} entry point '
613 f'"{name}" from {module_path}: {exc}'
614 )
615 warn_external(msg)
616 return False
617 return True
618
619
620 def _pending_accessor_names() -> tuple[str, ...]:
621 """Return every pending accessor name without importing any plugin.
622
623 Used by :meth:`pyvista.DataObject.__dir__` so that IPython /
624 Jupyter / REPL tab completion surfaces accessors contributed by
625 installed plugins even before those plugins have been imported. The
626 plugin module itself is **not** loaded — only the entry-point
627 metadata is consulted.
628 """
629 _ensure_entry_points()
630 return tuple(_pending_accessors)
631
632
633 def registered_accessors() -> tuple[AccessorRegistration, ...]:
634 """Return every accessor currently registered.
635
636 Forces discovery of any pending entry-point plugins so the returned
637 list reflects every plugin visible to PyVista, not just the ones
638 that have been touched already via attribute access. A plugin that
639 fails to import emits a ``UserWarning`` and is skipped; the rest
640 still appear in the result.
641
642 .. versionadded:: 0.48.0
643
644 Returns
645 -------
646 tuple[AccessorRegistration, ...]
647 Ordered by registration time. Each record exposes ``name``,
648 ``target``, ``accessor``, and ``source``.
649
650 Examples
651 --------
652 >>> import pyvista as pv
653 >>> @pv.register_dataset_accessor('demo_listed', pv.PolyData)
654 ... class DemoListedAccessor:
655 ... def __init__(self, mesh):
656 ... self._mesh = mesh
657 >>> [r.name for r in pv.registered_accessors() if r.name == 'demo_listed']
658 ['demo_listed']
659 >>> pv.unregister_dataset_accessor('demo_listed', pv.PolyData)
660
661 """
662 _ensure_entry_points()
663 for pending_name in list(_pending_accessors):
664 _resolve_pending_accessor(pending_name)
665 return tuple(_registrations)