spyder.api.plugins.new_api

New API for plugins.

All plugins in Spyder 5+ must inherit from the classes present in this file.

Classes

SpyderDockablePlugin(parent, configuration)	A Spyder plugin to enhance functionality with a dockable widget.
SpyderPluginV2(parent[, configuration])	A Spyder plugin to extend functionality without a dockable widget.

class spyder.api.plugins.new_api.SpyderPluginV2(parent, configuration=None)

Bases: QObject, SpyderActionMixin, SpyderConfigurationObserver, SpyderPluginObserver

A Spyder plugin to extend functionality without a dockable widget.

If you want to create a plugin that adds a new pane, please use SpyderDockablePlugin.

sig_free_memory_requested

This signal can be emitted to request the main application to garbage collect deleted objects.

sig_plugin_ready

This signal can be emitted to reflect that the plugin was initialized.

sig_quit_requested

This signal can be emitted to request the main application to quit.

sig_restart_requested

This signal can be emitted to request the main application to restart.

sig_status_message_requested

This signal can be emitted to request the main application to display a message in the status bar.

Parameters:

• message (str) – The actual message to display.

• timeout (int) – The timeout before the message disappears.

sig_redirect_stdio_requested

This signal can be emitted to request the main application to redirect standard output/error when using Open/Save/Browse dialogs within widgets.

Parameters:

enable (bool) – Enable/Disable standard input/output redirection.

sig_exception_occurred

This signal can be emitted to report an exception from any plugin.

Parameters:

error_data (dict) –

The dictionary containing error data. The expected keys are:

error_data = {
    "text": str,
    "is_traceback": bool,
    "repo": str,
    "title": str,
    "label": str,
    "steps": str,
}

Notes

The is_traceback key indicates if text contains plain text or a Python error traceback.

The title and repo keys indicate how the error data should customize the report dialog and Github error submission.

The label and steps keys allow customizing the content of the error dialog.

This signal is automatically connected to the main container/widget.

sig_mainwindow_resized

This signal is emitted when the main window is resized.

Parameters:

resize_event (QResizeEvent) – The event triggered on main window resize.

Notes

To be used by plugins tracking main window size changes.

sig_mainwindow_moved

This signal is emitted when the main window is moved.

Parameters:

move_event (QMoveEvent) – The event triggered on main window move.

Notes

To be used by plugins tracking main window position changes.

sig_unmaximize_plugin_requested

This signal is emitted to inform the main window that it needs to unmaximize the currently maximized plugin, if any.

Parameters:

plugin_instance (SpyderDockablePlugin) – Unmaximize plugin only if it is not plugin_instance.

sig_mainwindow_state_changed

This signal is emitted when the main window state has changed (for instance, between maximized and minimized states).

Parameters:

window_state (Qt.WindowStates) – The window state.

sig_focused_plugin_changed

This signal is emitted when the plugin with keyboard focus changes.

Parameters:

plugin (Optional[SpyderDockablePlugin]) – The plugin that currently has keyboard focus, or None if no dockable plugin has focus.

get_path()

Return the plugin’s system path.

get_container()

Return the plugin main container.

get_configuration()

Return the Spyder configuration object.

get_main()

Return the Spyder main window..

get_plugin(plugin_name, error=True) → SpyderPluginV2

Get a plugin instance by providing its name.

Parameters:

• plugin_name (str) – Name of the plugin from which its instance will be returned.

• error (bool) – Whether to raise errors when trying to return the plugin’s instance.

is_plugin_enabled(plugin_name)

Determine if a given plugin is going to be loaded.

is_plugin_available(plugin_name)

Determine if a given plugin is available.

get_dockable_plugins()

Return a list of the required plugin instances.

Only required plugins that extend SpyderDockablePlugin are returned.

get_conf(option, default=<class 'spyder.config.user.NoDefault'>, section=None, secure=False)

Get an option from Spyder configuration system.

Parameters:

• option (str) – Name of the option to get its value from.

• default (bool, int, str, tuple, list, dict, NoDefault) – Value to get from the configuration system, passed as a Python object.

• section (str) – Section in the configuration system, e.g. shortcuts.

• secure (bool) – If True, the option will be retrieved securely using the keyring Python package.

Returns:

Value associated with option.

Return type:

bool, int, str, tuple, list, dict

set_conf(option, value, section=None, recursive_notification=True, secure=False)

Set an option in Spyder configuration system.

Parameters:

• option (str) – Name of the option (e.g. ‘case_sensitive’)

• value (bool, int, str, tuple, list, dict) – Value to save in the configuration system, passed as a Python object.

• section (str) – Section in the configuration system, e.g. shortcuts.

• recursive_notification (bool) – If True, all objects that observe all changes on the configuration section and objects that observe partial tuple paths are notified. For example if the option opt of section sec changes, then the observers for section sec are notified. Likewise, if the option (a, b, c) changes, then observers for (a, b, c), (a, b) and a are notified as well.

• secure (bool) – If True, the option will be saved securely using the keyring Python package.

remove_conf(option, section=None, secure=False)

Delete an option in the Spyder configuration system.

Parameters:

• option (Union[str, Tuple[str, ...]]) – Name of the option, either a string or a tuple of strings.

• section (str) – Section in the configuration system.

• secure (bool) – If True, the option will be removed securely using the keyring Python package.

apply_conf(options_set, notify=True)

Apply options_set to this plugin’s widget.

disable_conf(option, section=None)

Disable notifications for an option in the Spyder configuration system.

Parameters:

• option (Union[str, Tuple[str, ...]]) – Name of the option, either a string or a tuple of strings.

• section (str) – Section in the configuration system.

restore_conf(option, section=None)

Restore notifications for an option in the Spyder configuration system.

Parameters:

• option (Union[str, Tuple[str, ...]]) – Name of the option, either a string or a tuple of strings.

• section (str) – Section in the configuration system.

show_status_message(message, timeout=0)

Show message in status bar.

Parameters:

• message (str) – Message to display in the status bar.

• timeout (int) – Amount of time to display the message.

before_long_process(message)

Show a message in main window’s status bar and change the mouse pointer to Qt.WaitCursor when starting a long process.

Parameters:

message (str) – Message to show in the status bar when the long process starts.

after_long_process(message='')

Clear main window’s status bar after a long process and restore mouse pointer to the OS deault.

Parameters:

message (str) – Message to show in the status bar when the long process finishes.

get_color_scheme()

Get the current color scheme.

Returns:

Dictionary with properties and colors of the color scheme used in the Editor.

Return type:

dict

Notes

This is useful to set the color scheme of all instances of CodeEditor used by the plugin.

initialize()

Initialize a plugin instance.

Notes

This method should be called to initialize the plugin, but it should not be overridden, since it internally calls on_initialize and emits the sig_plugin_ready signal.

static create_icon(name)

Provide icons from the theme and icon manager.

classmethod get_font(font_type)

Return one of font types used in Spyder.

Parameters:

font_type (str) – There are three types of font types in Spyder: SpyderFontType.Monospace, used in the Editor, IPython console, and History; SpyderFontType.Interface, used by the entire Spyder app; and SpyderFontType.MonospaceInterface, used by the Variable Explorer, Find, Debugger and others.

Returns:

QFont object to be passed to other Qt widgets.

Return type:

QFont

Notes

All plugins in Spyder use the same, global fonts. In case some a plugin wants to use a delta font size based on the default one, they can set the MONOSPACE_FONT_SIZE_DELTA or INTERFACE_FONT_SIZE_DELTA class constants.

get_command_line_options()

Get command line options passed by the user when they started Spyder in a system terminal.

See app/cli_options.py for the option names.

static get_name()

Return the plugin localized name.

Returns:

Localized name of the plugin.

Return type:

str

Notes

This method needs to be decorated with staticmethod.

static get_description()

Return the plugin localized description.

Returns:

Localized description of the plugin.

Return type:

str

Notes

This method needs to be decorated with staticmethod.

classmethod get_icon()

Return the plugin associated icon.

Returns:

QIcon instance

Return type:

QIcon

Notes

This method needs to be decorated with classmethod or staticmethod.

on_initialize()

Setup the plugin.

Notes

All calls performed on this method should not call other plugins.

static check_compatibility()

This method can be reimplemented to check compatibility of a plugin with the user’s current environment.

Returns:

The first value tells Spyder if the plugin has passed the compatibility test defined in this method. The second value is a message that must explain users why the plugin was found to be incompatible (e.g. ‘This plugin does not work with PyQt4’). It will be shown at startup in a QMessageBox.

Return type:

(bool, str)

on_first_registration()

Actions to be performed the first time the plugin is started.

It can also be used to perform actions that are needed only the first time this is loaded after installation.

This method is called after the main window is visible.

before_mainwindow_visible()

Actions to be performed after setup but before the main window’s has been shown.

on_mainwindow_visible()

Actions to be performed after the main window’s has been shown.

on_close(cancelable=False)

Perform actions before the plugin is closed.

This method must only operate on local attributes and not other plugins.

can_close() → bool

Determine if a plugin can be closed.

Returns:

close – True if the plugin can be closed, False otherwise.

Return type:

bool

update_font()

This must be reimplemented by plugins that need to adjust their fonts.

The following plugins illustrate the usage of this method:

• spyder/plugins/help/plugin.py

• spyder/plugins/onlinehelp/plugin.py

update_style()

This must be reimplemented by plugins that need to adjust their style.

Changing from the dark to the light interface theme might require specific styles or stylesheets to be applied. When the theme is changed by the user through our Preferences, this method will be called for all plugins.

after_container_creation()

Perform necessary operations before setting up the container.

This must be reimplemented by plugins whose containers emit signals in on_option_update that need to be connected before applying those options to our config system.

after_configuration_update(options: List[str | tuple])

Perform additional operations after updating the plugin configuration values.

This can be implemented by plugins that do not have a container and need to act on configuration updates.

Parameters:

options (List[Union[str, tuple]]) – A list that contains the options that were updated.

class spyder.api.plugins.new_api.SpyderDockablePlugin(parent, configuration)

Bases: SpyderPluginV2

A Spyder plugin to enhance functionality with a dockable widget.

sig_focus_changed

This signal is emitted to inform the focus of this plugin has changed.

sig_toggle_view_changed

This action is emitted to inform the visibility of a dockable plugin has changed.

This is triggered by checking/unchecking the entry for a pane in the Window > Panes menu.

Parameters:

visible (bool) – New visibility of the dockwidget.

sig_switch_to_plugin_requested

This signal can be emitted to inform the main window that this plugin requested to be displayed.

Notes

This is automatically connected to main container/widget at plugin’s registration.

sig_update_ancestor_requested

This signal is emitted to inform the main window that a child widget needs its ancestor to be updated.

create_new_file() → None

Create a new file inside the plugin.

This function will be called if the user creates a new file using the File > New menu item or the “New file” button in the main toolbar, and CAN_HANDLE_FILE_ACTIONS is set to True.

open_file(filename: str)

Open file inside plugin.

This method will be called if the user wants to open a file with one of the file name extensions listed in FILE_EXTENSIONS, so you need to define that variable too.

Parameters:

filename (str) – The name of the file to be opened.

get_current_filename() → str | None

Return file name of the file that is currently displayed.

This is meant for plugins like the Editor or Notebook plugin which can edit or display files. Return None if no file is displayed or if this does not display files.

This function is used in the Open file action to initialize the “Open file” dialog.

current_file_is_temporary() → bool

Return whether the currently displayed file is a temporary file.

This function should only be called if a file is displayed, that is, if self.get_current_filename() does not return None.

open_last_closed_file() → None

Open the last closed file again.

This function will be called if the File > Open last closed menu item is selected while the plugin has focus and CAN_HANDLE_FILE_ACTIONS is set to True.

save_file() → None

Save the current file.

This function will be called if the user saves the current file using the File > Save menu item or the “Save file” button in the main toolbar, the plugin has focus, and CAN_HANDLE_FILE_ACTIONS is set to True.

save_file_as() → None

Save the current file under a different name.

This function will be called if the File > Save as menu item is selected while the plugin has focus and CAN_HANDLE_FILE_ACTIONS is set to True.

save_copy_as() → None

Save a copy of the current file under a different name.

This function will be called if the File > Save copy as menu item is selected while the plugin has focus and CAN_HANDLE_FILE_ACTIONS is set to True.

save_all() → None

Save all files that are opened in the plugin.

This function will be called if the user saves all files using the File > Save all menu item or the “Save all” button in the main toolbar, the plugin has focus, and CAN_HANDLE_FILE_ACTIONS is set to True.

revert_file() → None

Revert the current file to the version stored on disk.

This function will be called if the File > Revert menu item is selected while the plugin has focus and CAN_HANDLE_FILE_ACTIONS is set to True.

close_file() → None

Close the current file.

This function will be called if the File > Close menu item is selected while the plugin has focus and CAN_HANDLE_FILE_ACTIONS is set to True.

close_all() → None

Close all opened files.

This function will be called if the File > Close all menu item is selected while the plugin has focus and CAN_HANDLE_FILE_ACTIONS is set to True.

undo() → None

Undo last edition.

This function will be called if the Edit > Undo menu item is selected while the plugin has focus and CAN_HANDLE_EDIT_ACTIONS is set to True.

redo() → None

Redo last edition.

This function will be called if the Edit > Redo menu item is selected while the plugin has focus and CAN_HANDLE_EDIT_ACTIONS is set to True.

cut() → None

Cut selection.

This function will be called if the Edit > Cut menu item is selected while the plugin has focus and CAN_HANDLE_EDIT_ACTIONS is set to True.

copy() → None

Copy selection.

This function will be called if the Edit > Copy menu item is selected while the plugin has focus and CAN_HANDLE_EDIT_ACTIONS is set to True.

paste() → None

Paste clipboard.

This function will be called if the Edit > Paste menu item is selected while the plugin has focus and CAN_HANDLE_EDIT_ACTIONS is set to True.

select_all() → None

Select all text in the plugin.

This function will be called if the Edit > Select All menu item is selected while the plugin has focus and CAN_HANDLE_EDIT_ACTIONS is set to True.

find() → None

Find text in the plugin.

This function will be called if the Search > Find text menu item is selected while the plugin has focus and CAN_HANDLE_SEARCH_ACTIONS is set to True.

find_next() → None

Move to next find text occurrence in the plugin.

This function will be called if the Search > Find next menu item is selected while the plugin has focus and CAN_HANDLE_SEARCH_ACTIONS is set to True.

find_previous() → None

Move to previous find text occurrence in the plugin.

This function will be called if the Search > Find previous menu item is selected while the plugin has focus and CAN_HANDLE_SEARCH_ACTIONS is set to True.

replace() → None

Replace text occurrence in the plugin.

This function will be called if the Search > Replace text menu item is selected while the plugin has focus and CAN_HANDLE_SEARCH_ACTIONS is set to True.

before_long_process(message)

Show a message in main window’s status bar, change the mouse pointer to Qt.WaitCursor and start spinner when starting a long process.

Parameters:

message (str) – Message to show in the status bar when the long process starts.

after_long_process(message='')

Clear main window’s status bar after a long process, restore mouse pointer to the OS deault and stop spinner.

Parameters:

message (str) – Message to show in the status bar when the long process finishes.

get_widget() → PluginMainWidget

Return the plugin main widget.

update_title()

Update plugin title, i.e. dockwidget or window title.

update_margins(margin)

Update margins of main widget inside dockable plugin.

switch_to_plugin(force_focus=False)

Switch to plugin and define if focus should be given or not.

set_ancestor(ancestor_widget)

Update the ancestor/parent of child widgets when undocking.