spyder.api.plugin_registration.decorators

spyder.api.plugin_registration.decorators#

Spyder API plugin registration decorators.

Functions

on_plugin_available([func, plugin])

Decorate a method to be called back when a specific plugin becomes ready.

on_plugin_teardown([func, plugin])

Decorate a method to be called back when tearing down a specific plugin.
spyder.api.plugin_registration.decorators.on_plugin_available(func: Callable | None = None, plugin: str | None = None) → Callable[source]#

Decorate a method to be called back when a specific plugin becomes ready.

The decorated method must be a member of a SpyderPluginV2 subclass for the decorator to work as intended.

Methods to be decorated must have the signature

def method(self):
    ...

when observing a single plugin, or

def method(self, plugin: str):
    ...

when observing all plugins listed as dependencies.

Caution

Any plugin(s) specified must be listed under either the REQUIRES or OPTIONAL class constants of the plugin’s SpyderPluginV2 class. If not, a SpyderAPIError will be raised when the plugin class is initialized.

Parameters:

  • func (Callable | None, optional) – Method to decorate, passed automatically when applying the decorator.

  • plugin (str | None, optional) – Name of the requested plugin whose availability triggers func. If None (the default), observes all plugins listed as dependencies. Must be listed under the class’ ‘REQUIRES or OPTIONAL class constants, or else a SpyderAPIError will be raised.

Returns:

func – The method passed as func with the plugin listener set up.

Return type:

Callable

Raises:

SpyderAPIError – When initializing a plugin class with decorated methods, if trying to watch a plugin that is not listed in the plugin class’ REQUIRES or OPTIONAL class constants.

spyder.api.plugin_registration.decorators.on_plugin_teardown(func: Callable | None = None, plugin: str | None = None) → Callable[source]#

Decorate a method to be called back when tearing down a specific plugin.

The decorated method must be a member of a SpyderPluginV2 subclass for the decorator to work as intended.

The decorator will be called before the specified plugin is deleted and also before the plugin that uses the decorator is destroyed.

Methods that use this decorator must have the signature

def method(self):
    ...

Important

A plugin name must be passed to plugin. While a default of None is accepted due to technical limitations, it will raise a ValueError at runtime.

Caution

Any plugin(s) specified must be listed under either the REQUIRES or OPTIONAL class constants of the plugin’s SpyderPluginV2 class. If not, a SpyderAPIError will be raised when the plugin class is initialized.

Parameters:

  • func (Callable | None, optional) – Method to decorate, passed automatically when applying the decorator.

  • plugin (str) – Name of the requested plugin whose teardown triggers func. While None, the default, is accepted for technical reasons, ValueError is raised if a plugin name is not passed. Must be listed under the class’ ‘REQUIRES or OPTIONAL class constants, or else a SpyderAPIError will be raised.

Returns:

func – The method passed as func with the plugin listener set up.

Return type:

Callable

Raises:

  • ValueError – If an explicit plugin name is not passed to plugin.

  • SpyderAPIError – When initializing a plugin class with decorated methods, if trying to watch a plugin that is not listed in the plugin class’ REQUIRES or OPTIONAL class constants.

Contents