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