register_plotter_component

register_plotter_component(

name: str,

target_cls: type | None = None,

*,

override: bool = False,

) → Callable[[type], type]

Register a custom namespaced component on a PyVista plotter class.

Once registered, the component becomes available as plotter.<name>.<method>(...) on every instance of target_cls and its subclasses. The component class is instantiated lazily on first access and cached on the plotter instance, so subsequent accesses return the same component object.

Components participate in the plotter lifecycle: if the class defines __plotter_close__ it is invoked when the plotter closes; if it defines __plotter_deep_clean__ it is invoked from BasePlotter.deep_clean. Both hooks fire only on components that were actually constructed (touched at least once).

Mirrors register_dataset_accessor() on the registration surface so plugin authors learn one decorator pattern.

Added in version 0.48.0.

Parameters:

namestr

The namespace the component will be attached under. Must be a valid Python identifier that does not start with an underscore.

target_clstype, optional

The plotter class (or base class) to attach the component to. Defaults to pyvista.BasePlotter, which exposes the component on every plotter subclass (including pyvistaqt.QtInteractor).

overridebool, default: False

If True, allow registering a name that shadows an existing built-in attribute on target_cls (a method, property, or any other non-component attribute). The prior attribute is restored on unregister_plotter_component().

Returns:

callable()

Decorator that registers the component class passed to it and returns that class unchanged.

Raises:

ValueError

If name is empty, not a valid identifier, starts with _, or shadows a built-in attribute on target_cls without override=True.

TypeError

If target_cls is not a class, or name is not a string.

Warns:

UserWarning

If name already refers to a registered component on target_cls or any ancestor. Pass override=True to silence the warning when replacement is intentional.

See also

pyvista.unregister_plotter_component

pyvista.registered_plotter_components

pyvista.PlotterComponent

Examples

Register a minimal component on the plotter.

>>> import pyvista as pv
>>> @pv.register_plotter_component('demo')
... class DemoComponent:
...     def __init__(self, plotter):
...         self._plotter = plotter
...
...     def title(self):
...         return self._plotter.title
>>> pl = pv.Plotter()
>>> pl.demo.title() == pl.title
True

Components are cached per plotter. Repeated access returns the same object.

>>> pl.demo is pl.demo
True

Clean up so the namespace is not visible to later doctest examples.

>>> pv.unregister_plotter_component('demo')
>>> pl.close()