spyder.api.plugins

Base classes for constructing and accessing top-level Spyder plugin objects.

Here, “plugins” are Qt objects that can make changes to Spyder’s main window and call/connect to other plugins directly.

There are two types of plugins available:

• SpyderPluginV2 does not create a new pane in Spyder’s main window.

  Note

  SpyderPluginV2 will be aliased to SpyderPlugin and deprecated in Spyder 6.2, and removed in Spyder 7.0.

• SpyderDockablePlugin creates a new pane in Spyder’s main window.

class spyder.api.plugins.Plugins

Bases: DockablePlugins

Pseudo-enum class listing the names of all Spyder internal plugins.

Values correspond to the plugin’s NAME.

Note

This “enum” also includes all the members from DockablePlugins via inheritance from that class.

All = 'all'

Wildcard to populate REQUIRES with all available plugins.

Appearance = 'appearance'

The Spyder Appearance plugin.

Application = 'application'

The Spyder Application plugin.

Completions = 'completions'

The Spyder Completions plugin.

ExternalTerminal = 'external_terminal'

The Spyder External Terminal plugin.

Layout = 'layout'

The Spyder Layout plugin.

MainInterpreter = 'main_interpreter'

The Spyder Main Interpreter plugin.

MainMenu = 'mainmenu'

The Spyder Main Menu plugin.

Preferences = 'preferences'

The Spyder Preferences plugin.

PythonpathManager = 'pythonpath_manager'

The Spyder PYTHONPATH Manager plugin.

RemoteClient = 'remoteclient'

The Spyder Remote Client plugin.

Run = 'run'

The Spyder Run plugin.

Shortcuts = 'shortcuts'

The Spyder Shortcuts plugin.

StatusBar = 'statusbar'

The Spyder Status Bar plugin.

Switcher = 'switcher'

The Spyder Switcher plugin.

Toolbar = 'toolbar'

The Spyder Toolbar plugin.

Tours = 'tours'

The Spyder Tours plugin.

UpdateManager = 'update_manager'

The Spyder Update Manager plugin.

WorkingDirectory = 'workingdir'

The Spyder Working Directory plugin.

class spyder.api.plugins.DockablePlugins

Bases: object

Pseudo-enum class listing the names of Spyder internal dockable plugins.

Values correspond to the plugin’s NAME.

Console = 'internal_console'

The Spyder Internal Console plugin.

Debugger = 'debugger'

The Spyder Debugger plugin.

Editor = 'editor'

The Spyder Editor plugin.

Explorer = 'explorer'

The Spyder Files plugin.

Find = 'find_in_files'

The Spyder Find plugin.

Help = 'help'

The Spyder Help plugin.

History = 'historylog'

The Spyder History plugin.

IPythonConsole = 'ipython_console'

The Spyder IPython Console plugin.

OnlineHelp = 'onlinehelp'

The Spyder Online Help plugin.

OutlineExplorer = 'outline_explorer'

The Spyder Outline plugin.

Plots = 'plots'

The Spyder Plots plugin.

Profiler = 'profiler'

The Spyder Profiler plugin.

Projects = 'project_explorer'

The Spyder Projects plugin.

Pylint = 'pylint'

The Spyder Code Analysis plugin.

VariableExplorer = 'variable_explorer'

The Spyder Variable Explorer plugin.

class spyder.api.plugins.OptionalPlugins

Bases: object

Pseudo-enum class listing the names of Spyder optional plugins.

Values correspond to the plugin’s NAME.

EnvManager = 'spyder_env_manager'

The Spyder Environment Manager plugin.

class spyder.api.plugins.SpyderPluginV2(parent: spyder.app.mainwindow.MainWindow, configuration: spyder.config.manager.ConfigurationManager | None = None)

Bases: QObject, SpyderActionMixin, SpyderConfigurationObserver, SpyderPluginObserver

Base class for all Spyder plugins.

Use this class directly for plugins that extend functionality without a dockable widget. To create a plugin that adds a new pane to the interface, use SpyderDockablePlugin.

ADDITIONAL_CONF_OPTIONS: dict[str, dict[spyder.config.types.ConfigurationKey, BasicTypes | spyder.config.user.NoDefault]] | None = None

Configuration options added by this plugin for other plugins.

Examples

ADDITIONAL_CONF_OPTIONS = {
    "section": {
        "option_1": True,
        "option_2": "default_value",
    },
}

ADDITIONAL_CONF_TABS: dict[str, list[type[SpyderPreferencesTab]]] | None = None

Define additional tabs of options for other plugins’ configuration pages.

All configuration tabs should inherit from SpyderPreferencesTab.

Examples

ADDITIONAL_CONF_TABS = {"plugin_name": [MyPluginsSpyderPrefsTab]}

CAN_BE_DISABLED: bool = True

Define if a plugin can be disabled in the Spyder Preferences.

If False, the plugin is considered “core” and cannot be disabled. True by default, meaning the plugin can be disabled.

CONF_DEFAULTS: list[tuple[str, dict[spyder.config.types.ConfigurationKey, BasicTypes | spyder.config.user.NoDefault]]] | None = None

Define configuration defaults if using a separate file.

List of tuples, with the first item in the tuple being the section name and the second item being the default options dictionary.

Examples

CONF_DEFAULTS = [
    (
        "section-name",
        {
            "option-1": "some-value",
            "option-2": True,
        },
    ),
    (
        "another-section-name",
        {
            "option-3": "some-other-value",
            "option-4": [1, 2, 3],
        },
    ),
]

CONF_FILE: bool = True

Whether to use a separate configuration file for the plugin.

Should always be set to True for external plugins.

If True (the default), use a separate configuration file. If False, use the main Spyder config file.

CONF_SECTION: str | None = None

Name of the Spyder configuration section for the plugin’s data.

Used to record the plugin’s permanent data in Spyder config system (i.e. in spyder.ini).

CONF_VERSION: str | None = None

Define the configuration version if using a separate file.

• If you want to change the default value of a current option, you need to do a MINOR update in config version, e.g. from 3.0.0 to 3.1.0.

• If you want to remove options that are no longer needed or if you want to rename options, then you need to do a MAJOR update in version, e.g. from 3.0.0 to 4.0.0.

• You don’t need to touch this value if you’re just adding a new option.

CONF_WIDGET_CLASS: type[PluginConfigPage] | None = None

Widget to be used as this plugin’s entry in Spyder Preferences dialog.

If None, the default, the plugin will not have a configuration page in Spyder’s Preferences.

CONTAINER_CLASS: type[PluginMainContainer] | None = None

Container class object to instantiate for the plugin.

This must subclass a PluginMainContainer for non-dockable plugins that create a widget, like a status bar widget, a toolbar, a menu, etc.

For non-dockable plugins that do not define widgets of any kind, for example a plugin that only exposes a configuration page, this can be None,

CONTEXT_NAME: str | None = None

The name under which to store actions, toolbars, toolbuttons and menus.

CUSTOM_LAYOUTS: list[type[spyder.plugins.layout.api.BaseGridLayoutType]] = []

Define custom layout classes that the plugin wants to be registered.

The custom classes should extend from spyder.plugins.layout.api.BaseGridLayoutType.

IMG_PATH: str | None = None

Path for images relative to the plugin path.

A Python package can include one or several Spyder plugins. If the latter, the package may be using images from a directory outside that of the plugin itself.

INTERFACE_FONT_SIZE_DELTA: int = 0

The interface (UI) font size delta relative to Spyder default, in points.

MONOSPACE_FONT_SIZE_DELTA: int = 0

The monospace (code) font size delta relative to Spyder default, in points.

NAME: str = None

Name of the plugin that will be used to refer to it.

This name must be unique and will only be loaded once.

OPTIONAL: list[str] = []

List of names of optional dependencies for this plugin.

Optional dependencies are useful for when a plugin can offer specific features by connecting to another plugin, but does not depend on the other plugin for its core functionality. For example, the Help plugin might render information from the Editor, IPython Console or another source, but it does not depend on either of those plugins to work.

Note

Plugin names are defined in the Plugins pseudo-enum class.

Examples

OPTIONAL = [Plugins.Plots, Plugins.IPythonConsole, ...]

REQUIRES: list[str] = []

List of names of required dependencies for this plugin.

Note

Plugin names are defined in the Plugins pseudo-enum class.

Examples

REQUIRES = [Plugins.Plots, Plugins.IPythonConsole, ...]

REQUIRE_WEB_WIDGETS: bool = False

Declare whether the plugin needs to use Qt web widgets (QtWebEngine).

Qt Web Widgets is a heavy dependency for many packagers, e.g. Conda-Forge. We thus ask plugins to declare whether or not they need web widgets to make it easier to distribute Spyder without them.

See Spyder issue #22196 for more information.

__init__(parent: spyder.app.mainwindow.MainWindow, configuration: spyder.config.manager.ConfigurationManager | None = None)

Initialize the plugin object (called automatically by Spyder).

Important

Plugins are initialized automatically by Spyder, so they shouldn’t call or override this method directly.

Parameters:

• parent (spyder.app.mainwindow.MainWindow) – Parent Spyder window of this plugin.

• configuration (spyder.config.manager.ConfigurationManager) – The Spyder configuration manager object for the plugin to access.

Return type:

None

after_configuration_update(options: list[spyder.config.types.ConfigurationKey]) → None

Perform additional operations after updating the plugin config options.

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

Parameters:

options (list[spyder.config.types.ConfigurationKey]) – A list that contains the option names that were updated.

Return type:

None

after_container_creation() → None

Perform necessary operations before setting up the container.

This must be reimplemented by plugins whose containers emit signals that need to be connected before applying options to Spyder’s config system.

Return type:

None

after_long_process(message: str = '') → None

Perform actions required after starting a long-running process.

Clears the message in the Spyder main window’s status bar and restores the mouse pointer to the OS default.

Parameters:

message (str, optional) – Message to show in the status bar when the long process finishes. An empty message by default, clearing the previous message.

Return type:

None

apply_conf(options_set: set[spyder.config.types.ConfigurationKey], notify: bool = True) → None

Handle applying a set of options to this plugin’s widget.

Parameters:

• options_set (set[spyder.config.types.ConfigurationKey]) – The set of option names that were changed.

• notify (bool, optional) – If True, the default, call after_configuration_update() to perform plugin-specific additional operations after applying the configuration changes. If False, don’t call the method.

Return type:

None

before_long_process(message: str) → None

Perform actions required before starting a long-running process.

Shows a message in the main window’s status bar, and changes the mouse pointer to a wait cursor.

Parameters:

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

Return type:

None

before_mainwindow_visible() → None

Actions to be performed after setup but before showing the main window.

Return type:

None

can_close() → bool

Determine if the plugin can be closed.

Returns:

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

Return type:

bool

static check_compatibility() → tuple[bool, str]

Check compatibility of a plugin with the user’s current environment.

Intended for plugin-specific checks, so needs to be reimplemented by the plugin subclass to do anything meaningful.

Returns:

valid, message – The first value, valid, tells Spyder if the plugin has passed the compatibility test defined in this method.

The second value, message, must (if valid is False) explain to 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:

tuple[bool, str]

static create_icon(name) → QIcon

Retrieve an icon from the theme and icon manager.

Parameters:

name (str) – The name of the icon to retrieve.

Returns:

The specified icon, as a QIcon instance.

Return type:

QIcon

disable_conf(option: spyder.config.types.ConfigurationKey, section: str | None = None) → None

Disable notifications for an option in the Spyder configuration system.

Parameters:

• option (spyder.config.types.ConfigurationKey) – Name of the option, either a string or a tuple of strings.

• section (str | None, optional) – Name of the configuration section to use, e.g. "shortcuts". If None, the default, then the value of CONF_SECTION is used.

Return type:

None

Raises:

SpyderAPIError – If section is not passed and CONF_SECTION is not defined.

get_color_scheme() → dict[str, str | tuple[str, bool, bool]] | None

Get the Editor’s current color scheme.

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

Returns:

Dictionary with properties and colors of the color scheme used in the Editor, or None if the Spyder configuration object is not available (usually only ever the case in tests).

Return type:

dict[str, str | tuple[str, bool, bool]] | None

get_command_line_options() → argparse.Namespace

Get the command line options passed by the user when starting Spyder.

See spyder.app.cli_options for the option names.

Returns:

Namespace of the passed option keys and values.

Return type:

argparse.Namespace

get_conf(option: spyder.config.types.ConfigurationKey, default: spyder.config.user.NoDefault | BasicTypes = <class 'spyder.config.user.NoDefault'>, section: str | None = None, secure: bool = False) → BasicTypes | None

Retrieve an option’s value from the Spyder configuration system.

Parameters:

• option (spyder.config.types.ConfigurationKey) – Name/tuple path of the configuration option value to get.

• default (spyder.api.config.mixins.BasicTypes | spyder.config.user.NoDefault, optional) – Fallback value to return if the option is not found on the configuration system. No default value if not passed.

• section (str | None, optional) – Name of the configuration section to use, e.g. "shortcuts". If None, the default, then the value of CONF_SECTION is used.

• secure (bool, optional) – If True, the option will be retrieved from secure storage using the keyring Python package. Otherwise, will be retrieved from Spyder’s normal configuration (the default).

Returns:

value – Value of option in the configuration section, or None if the Spyder configuration object is not available (typically only the case in tests).

Return type:

spyder.api.config.mixins.BasicTypes | None

Raises:

• SpyderAPIError – If section is not passed and CONF_SECTION is not defined.

• configparser.NoOptionError – If the section does not exist in Spyder’s configuration.

get_configuration() → spyder.config.manager.ConfigurationManager | None

Return the Spyder configuration object.

Returns:

The Spyder configuration manager object.

Return type:

spyder.config.manager.ConfigurationManager

get_container() → PluginMainWidget | PluginMainContainer | None

Return the plugin’s main container object.

Returns:

The plugin’s main container object (i.e. an instance of CONTAINER_CLASS), or None if it doesn’t have one set (e.g. for simple plugins that don’t define any widgets).

Return type:

PluginMainContainer | None

static get_description() → str

Return the plugin’s localized description.

Note

This method needs to be decorated with staticmethod().

Returns:

Localized description of the plugin.

Return type:

str

get_dockable_plugins() → list[SpyderDockablePlugin]

Get a list of dockable plugin instances that this plugin depends on.

Only required plugins (listed under REQUIRES) that extend SpyderDockablePlugin are returned.

Returns:

List of dockable plugin object instances (those with graphical panes in the UI) that this plugin requires as dependencies.

Return type:

list[SpyderDockablePlugin]

classmethod get_font(font_type: str) → QFont

Return the font object for one of the font types used in Spyder.

All plugins in Spyder use the same, global fonts. In case a plugin wants to use a different font size than on the default, it can set the MONOSPACE_FONT_SIZE_DELTA or INTERFACE_FONT_SIZE_DELTA class constants.

Parameters:

font_type (str) – The kind of font to return the object for, as listed under the SpyderFontType pseudo-enum class. See that class’ documentation for more details.

Returns:

QFont object for the specified font_type, to be passed to other Qt widgets.

Return type:

QFont

classmethod get_icon() → QIcon

Return the plugin’s associated icon.

Note

This method needs to be decorated with classmethod() or staticmethod().

Returns:

The plugin’s icon, as a QIcon instance.

Return type:

QIcon

get_main() → spyder.app.mainwindow.MainWindow

Return the Spyder main window.

Returns:

The Spyder main window.

Return type:

spyder.app.mainwindow.MainWindow

static get_name() → str

Return the plugin’s localized name.

Note

This method needs to be decorated with staticmethod().

Returns:

Localized name of the plugin.

Return type:

str

get_path() → str

Return the path on disk to the plugin’s root module directory.

Returns:

The path to the directory containing the module with the plugin class (SpyderPluginV2 or SpyderDockablePlugin).

Return type:

str

get_plugin(plugin_name, error=True) → SpyderPluginV2 | None

Get a plugin instance object by its name.

Parameters:

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

• error (bool, optional) – If True (the default), raise an error if the plugin instance with the given plugin_name cannot be found, and the plugin is a required dependency of this one (listed in :attr`REQUIRES`). If False, runtime errors finding plugin_name pass silently (unless plugin_name is not listed in REQUIRES or OPTIONAL, which raises an error unconditionally).

Returns:

The plugin object with name plugin_name, or None if it cannot be found and is either an optional dependency of this plugin (listed under OPTIONAL), or error is False.

Return type:

SpyderPluginV2 | None

Raises:

SpyderAPIError – If plugin_name is not listed under either the REQUIRES or OPTIONAL attributes of this plugin, or plugin_name is not found (if a required dependency and error is True).

initialize() → None

Initialize a plugin instance.

Caution

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

Return type:

None

is_plugin_available(plugin_name: str) → bool

Determine if a given plugin is loaded and ready.

Parameters:

plugin_name (str) – The name of the plugin to check.

Returns:

True if plugin_name is loaded and ready, else False.

Return type:

bool

is_plugin_enabled(plugin_name: str) → bool

Determine if a given plugin is going to be loaded.

Parameters:

plugin_name (str) – The name of the plugin to check.

Returns:

True if plugin_name will be loaded, else False.

Return type:

bool

property main: spyder.app.mainwindow.MainWindow

Spyder main window to which this plugin belongs; i.e. its parent.

on_close(cancelable: bool = False) → None

Perform actions before the plugin is closed.

Caution

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

Parameters:

cancelable (bool, optional) – True if the close operation can potentially be canceled; False by default.

Return type:

None

on_first_registration() → None

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.

Return type:

None

on_initialize() → None

Set up the plugin.

Caution

Any calls performed in this method should not call other plugins.

Return type:

None

on_mainwindow_visible() → None

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

Return type:

None

remove_conf(option: spyder.config.types.ConfigurationKey, section: str | None = None, secure: bool = False) → None

Remove an option from the Spyder configuration system.

Parameters:

• option (spyder.config.types.ConfigurationKey) – Name/tuple path of the configuration option to remove.

• section (str | None, optional) – Name of the configuration section to use, e.g. "shortcuts". If None, the default, then the value of CONF_SECTION is used.

• secure (bool, optional) – If True, the option will be removed from secure storage using the keyring Python package. Otherwise, will be removed from Spyder’s normal configuration (the default).

Return type:

None

Raises:

SpyderAPIError – If section is not passed and CONF_SECTION is not defined.

restore_conf(option: spyder.config.types.ConfigurationKey, section: str | None = None) → None

Restore notifications for an option in the Spyder configuration system.

Parameters:

• option (spyder.config.types.ConfigurationKey) – Name of the option, either a string or a tuple of strings.

• section (str | None, optional) – Name of the configuration section to use, e.g. "shortcuts". If None, the default, then the value of CONF_SECTION is used.

Return type:

None

Raises:

SpyderAPIError – If section is not passed and CONF_SECTION is not defined.

set_conf(option: spyder.config.types.ConfigurationKey, value: BasicTypes, section: str | None = None, recursive_notification: bool = True, secure: bool = False) → None

Set an option’s value in the Spyder configuration system.

Parameters:

• option (spyder.config.types.ConfigurationKey) – Name/tuple path of the configuration option to set.

• value (spyder.api.config.mixins.BasicTypes) – Value to set for the given configuration option.

• section (str | None, optional) – Name of the configuration section to use, e.g. "shortcuts". If None, the default, then the value of CONF_SECTION is used.

• recursive_notification (bool, optional) – If True, all objects that observe all changes on the configuration section as well as objects that observe partial tuple paths are notified. For example, if the option opt of section sec changes, then all 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 all notified.

• secure (bool, optional) – If True, the option will be saved in secure storage using the keyring Python package. Otherwise, will be saved in Spyder’s normal configuration (the default).

Return type:

None

Raises:

SpyderAPIError – If section is not passed and CONF_SECTION is not defined.

show_status_message(message: str, timeout: int = 0) → None

Show a message in the Spyder status bar.

Parameters:

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

• timeout (int) – The amount of time, in milliseconds, to display the message. If 0, the default, the message will be shown until a plugin calls show_status_message() again.

Return type:

None

sig_exception_occurred(PyQt_PyObject): Signal

Report an exception from a plugin.

Parameters:

error_data (dict[str, str | bool]) –

The dictionary containing error data. The expected keys are:

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

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.

sig_focused_plugin_changed(PyQt_PyObject): Signal

Emitted when the plugin with keyboard focus changes.

Parameters:

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

sig_free_memory_requested: Signal

Request the main application garbage collect deleted objects.

sig_mainwindow_moved(QMoveEvent): Signal

Emitted when the main window is moved.

Used by plugins to track main window position changes.

Parameters:

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

sig_mainwindow_resized(QResizeEvent): Signal

Emitted when the main window is resized.

Used by plugins to track main window size changes.

Parameters:

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

sig_mainwindow_state_changed(PyQt_PyObject): Signal

Emitted when the main window state has changed (e.g. maximized/minimized).

Parameters:

window_state (WindowStates) – The new main window state.

sig_plugin_ready: Signal

Emitted once the plugin is initialized.

sig_quit_requested: Signal

Request that the main Spyder application quit.

sig_redirect_stdio_requested(bool): Signal

Request the main app redirect standard out/error within file pickers.

This will redirect stdin, stdout, and stderr when using Open, Save, and Browse dialogs within a plugin’s widgets.

Parameters:

enable (bool) – Enable (True) or disable (False) standard input/output redirection.

sig_restart_requested: Signal

Request that the main Spyder application perform a restart.

sig_status_message_requested(QString, int): Signal

Request that the main application display a status bar message.

Parameters:

• message (str) – The message to display.

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

sig_unmaximize_plugin_requested(), (PyQt_PyObject): Signal

Request the main window unmaximize the currently maximized plugin, if any.

Parameters:

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

update_font() → None

Modify the font used in the plugin’s interface.

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

• spyder.plugins.onlinehelp.plugin

Return type:

None

update_style() → None

Modify the interface styling used by the plugin.

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.

Return type:

None

PLUGIN_NAME: str

Plugin name in the action, toolbar, toolbutton & menu registries.

Usually the same as NAME, but may be different from CONTEXT_NAME.

is_compatible: bool | None

Whether the plugin has passed Spyder’s compatibility checks.

True if it has, False if it hasn’t, and None if the checks haven’t been run yet.

is_registered: bool | None

Whether the plugin is enabled and registered with Spyder.

True if it has been registered, False if it has been unregistered, and None if the plugin hasn’t been set up yet.

class spyder.api.plugins.SpyderDockablePlugin(parent: spyder.app.mainwindow.MainWindow, configuration: spyder.config.manager.ConfigurationManager)

Bases: SpyderPluginV2

Subclass for plugins with a dockable widget (pane) in the interface.

CAN_HANDLE_EDIT_ACTIONS: bool = False

Whether the plugin can handle editing actions.

If set to True, then the undo(), redo(), cut(), copy(), paste() and select_all() methods will be called to handle the corresponding actions.

If set to False, the default, the corresponding actions fall back to calling these methods on the Editor.

Individual actions can be disabled with the spyder.plugins.application.plugin.enable_edit_action() method in the Application plugin.

CAN_HANDLE_FILE_ACTIONS: bool = False

Whether the plugin declares it can handle file actions.

If set to True, then the create_new_file(), open_last_closed_file(), save_file(), save_file_as(), save_copy_as(), save_all(), revert_file(), close_file() and close_all() methods will be called to handle the corresponding actions.

If set to False, the default, the corresponding actions fall back to calling these methods on the Editor.

Individual actions can be disabled with the spyder.plugins.application.plugin.enable_file_action() method in the Application plugin.

CAN_HANDLE_SEARCH_ACTIONS = False

Whether the plugin can handle search actions.

If set to True, then the find(), find_next(), find_previous() and replace() methods will be called to handle the corresponding actions.

If set to False, the default, the corresponding actions fall back to calling these methods on the Editor.

Individual actions can be disabled with the spyder.plugins.application.plugin.enable_search_action() method in the Application plugin.

DISABLE_ACTIONS_WHEN_HIDDEN: bool = True

Disable the plugin’s actions in the main menu when the plugin is hidden.

If True, disable the plugin’s actions when it is not shown (default); if False, keep them enabled.

FILE_EXTENSIONS: list[str] = []

List of file extensions which the plugin can open.

If the user opens a file with one of these extensions, then the file will open in this plugin using its open_file() method.

Examples

For example, in the Spyder-Notebook plugin to open Jupyter notebooks:

FILE_EXTENSIONS = [".ipynb"]

RAISE_AND_FOCUS: bool = False

Give the plugin focus on switch to plugin calls.

If True, the plugin will be given focus when switched to. If False, the default, the plugin’s widget will still be raised to the foreground, but it will not be given focus until the switch action is called a second time.

TABIFY: list[str] = []

Define a list of plugins next to which we want to tabify this plugin.

Examples

TABIFY = [Plugins.Editor]

WIDGET_CLASS: type[PluginMainWidget] = None

This is the main widget of the dockable plugin.

It must be a subclass of spyder.api.widgets.main_widget.PluginMainWidget.

__init__(parent: spyder.app.mainwindow.MainWindow, configuration: spyder.config.manager.ConfigurationManager)

Initialize the plugin object (called automatically by Spyder).

Important

Plugins are initialized automatically by Spyder, so they shouldn’t call or override this method directly.

Parameters:

• parent (spyder.app.mainwindow.MainWindow) – Parent Spyder window of this plugin.

• configuration (spyder.config.manager.ConfigurationManager) – The Spyder configuration manager object for the plugin to access.

Raises:

SpyderAPIError – If WIDGET_CLASS is not set to a subclass of spyder.api.widgets.main_widget.PluginMainWidget.

Return type:

None

after_long_process(message: str = '') → None

Perform actions required after starting a long-running process.

Clears the message in the Spyder main window’s status bar, restores the mouse pointer to the OS default, and stops spinner.

Parameters:

message (str, optional) – Message to show in the status bar when the long process finishes. An empty message by default, clearing the previous message.

Return type:

None

before_long_process(message: str) → None

Perform actions required before starting a long-running process.

Shows a message in the main window’s status bar, changes the mouse pointer to a wait cursor, and starts a spinner.

Parameters:

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

Return type:

None

change_visibility(state: bool, force_focus: bool = False) → None

Raise the plugin’s dockwidget to the foreground, and/or grab its focus.

Parameters:

• state (bool) – Whether the plugin’s widget is being raised to the foreground (True) or set as not in the foreground (False). The latter does not actually send it to the background, but does configure it for not being actively shown (e.g. it disables its empty pane graphics).

• force_focus (bool | None, optional) – If True, always give the plugin’s widget keyboard focus when raising or un-raising it with this method. If None, only give it focus when showing, not hiding (setting state to True), and only if RAISE_AND_FOCUS is True. If False, the default, don’t give it focus regardless.

Return type:

None

close_all() → None

Close all opened files.

This method will be called if the File ‣ Close all menu item is selected, the plugin has focus, and CAN_HANDLE_FILE_ACTIONS is set to True.

Return type:

None

close_file() → None

Close the current file.

This method will be called if the File ‣ Close menu item is selected, the plugin has focus, and CAN_HANDLE_FILE_ACTIONS is set to True.

Return type:

None

close_window(save_undocked: bool = False) → None

Close the plugin’s undocked window, optionally saving its state.

This is a convenience wrapper to close an undocked plugin.

Parameters:

save_undocked (bool, optional) – True if the window state (size and position) should be saved. If False, the default, don’t persist the window state.

Return type:

None

copy() → None

Copy the current selection.

This method will be called if the Edit ‣ Copy menu item is selected, the plugin has focus, and CAN_HANDLE_EDIT_ACTIONS is set to True.

Return type:

None

create_dockwidget(mainwindow: spyder.app.mainwindow.MainWindow) → spyder.widgets.dock.SpyderDockWidget

Create a new dock widget for this plugin.

Parameters:

mainwindow (spyder.app.mainwindow.MainWindow) – The main window to set as the dockwidget’s parent.

Returns:

The new dock widget created for the plugin.

Return type:

spyder.widgets.dock.SpyderDockWidget

create_new_file() → None

Create a new file inside the plugin.

This method 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.

Return type:

None

create_window() → None

Create an undocked window for the plugin.

Return type:

None

current_file_is_temporary() → bool

Return whether the currently displayed file is a temporary file.

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

Returns:

True if the plugin’s currently displayed file is a temporary one, False otherwise.

Return type:

bool

cut() → None

Copy and remove the current selection.

This method will be called if the Edit ‣ Cut menu item is selected, the plugin has focus, and CAN_HANDLE_EDIT_ACTIONS is set to True.

Return type:

None

property dockwidget: spyder.widgets.dock.SpyderDockWidget

The dockable widget (pane) for this plugin.

find() → None

Search for text in the plugin.

This method will be called if the Search ‣ Find text menu item is selected, the plugin has focus, and CAN_HANDLE_SEARCH_ACTIONS is set to True.

Return type:

None

find_next() → None

Move to the next occurrence of found text in the plugin.

This method will be called if the Search ‣ Find next menu item is selected, the plugin has focus, and CAN_HANDLE_SEARCH_ACTIONS is set to True.

Return type:

None

find_previous() → None

Move to the previous occurrence of found text in the plugin.

This method will be called if the Search ‣ Find previous menu item is selected, the plugin has focus, and CAN_HANDLE_SEARCH_ACTIONS is set to True.

Return type:

None

get_current_filename() → str | None

Return the name of the file that is currently displayed.

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

This method is used in the Open file action to initialize the Open file dialog.

Returns:

The filename currently displayed in the plugin as a string, or None if no file is opened.

Return type:

str | None

get_widget() → PluginMainWidget

Return the plugin’s main widget.

Returns:

The plugin’s main widget, an instance of WIDGET_CLASS.

Return type:

spyder.api.widgets.main_widget.PluginMainWidget

open_file(filename: str) → None

Open a file inside the 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 that attribute needs to be set too in order to use this method.

Parameters:

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

Return type:

None

open_last_closed_file() → None

Reopen the last closed file.

This method 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.

Return type:

None

property options_menu: PluginMainWidgetOptionsMenu

The options (“hamburger”) menu widget for this plugin.

paste() → None

Paste the current clipboard contents.

This method will be called if the Edit ‣ Paste menu item is selected, the plugin has focus, and CAN_HANDLE_EDIT_ACTIONS is set to True.

Return type:

None

redo() → None

Redo the most recently undone change.

This method will be called if the Edit ‣ Redo menu item is selected, the plugin has focus, and CAN_HANDLE_EDIT_ACTIONS is set to True.

Return type:

None

replace() → None

Replace occurrence of text in the plugin.

This method will be called if the Search ‣ Replace text menu item is selected, the plugin has focus, and CAN_HANDLE_SEARCH_ACTIONS is set to True.

Return type:

None

revert_file() → None

Revert the current file to the version stored on disk.

This method will be called if the File ‣ Revert menu item is selected, the plugin has focus, and CAN_HANDLE_FILE_ACTIONS is set to True.

Return type:

None

save_all() → None

Save all files that are opened in the plugin.

This method will be called if the user saves all open file 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.

Return type:

None

save_copy_as() → None

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

This method will be called if the user saves the current file using the File ‣ Save copy as menu item, the plugin has focus, and CAN_HANDLE_FILE_ACTIONS is set to True.

Return type:

None

save_file() → None

Save the current file.

This method 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.

Return type:

None

save_file_as() → None

Save the current file under a different name.

This method will be called if the user saves the current file using the File ‣ Save as menu item, the plugin has focus, and CAN_HANDLE_FILE_ACTIONS is set to True.

Return type:

None

select_all() → None

Select all content in the plugin.

This method will be called if the Edit ‣ Select all menu item is selected, the plugin has focus, and CAN_HANDLE_EDIT_ACTIONS is set to True.

Return type:

None

set_ancestor(ancestor_widget: QWidget) → None

Update the ancestor/parent of child widgets when undocking.

Parameters:

ancestor_widget (QWidget) – The window widget to set as a parent of this one.

Return type:

None

sig_focus_changed: Signal

Report the focus state of this plugin has changed.

sig_switch_to_plugin_requested(PyQt_PyObject, bool): Signal

Request the main window show this plugin’s widget.

Parameters:

• plugin (SpyderDockablePlugin) – The plugin object to show.

• force_focus (bool) – If True, always give the plugin’s widget focus when showing or hiding it with this method. If False, the default, don’t give it focus.

sig_toggle_view_changed(bool): Signal

Report that 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) – Whether the dockwidget has been shown (True) or hidden (False).

sig_update_ancestor_requested: Signal

Notify the main window that a child widget needs its ancestor updated.

switch_to_plugin(force_focus: bool = False) → None

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

Parameters:

force_focus (bool | None, optional) – If True, always give the plugin’s widget focus when showing or hiding it with this method. If False, the default, don’t give it focus.

Return type:

None

toggle_view(value: bool) → None

Show or hide the plugin’s dockwidget in the Spyder interface.

Used to show or hide it from the from the Window ‣ Panes menu.

Parameters:

value (bool) – Whether to show (True) or hide (False) the dockwidget.

Return type:

None

property toggle_view_action: spyder.utils.qthelpers.SpyderAction

The QAction for showing/hiding this plugin’s pane.

undo() → None

Undo the most recent change.

This method will be called if the Edit ‣ Undo menu item is selected, the plugin has focus, and CAN_HANDLE_EDIT_ACTIONS is set to True.

Return type:

None

update_margins(margin: int | None) → None

Update the margins of the main widget inside this dockable plugin.

Parameters:

margin (int | None) – The margins to use for the main widget, or None for the default margins.

Return type:

None

update_title() → None

Update the plugin widget’s title, i.e. its dockwidget or window title.

Return type:

None

Modules