spyder.api.widgets.mixins

Spyder API Mixins.

Classes

SpyderActionMixin()	Provide methods to create, add and get actions in a unified way.
SpyderMainWindowMixin()	Mixin with additional functionality for the QMainWindow's used in Spyder.
SpyderMenuMixin()	Provide methods to create, add and get menus.
SpyderToolButtonMixin()	Provide methods to create, add and get toolbuttons.
SpyderToolbarMixin()	Provide methods to create, add and get toolbars.
SpyderWidgetMixin([class_parent, parent])	Basic functionality for all Spyder widgets and Qt items.
SvgToScaledPixmap()	Mixin to transform an SVG to a QPixmap that is scaled according to the factor set by users in Preferences.

class spyder.api.widgets.mixins.SpyderToolButtonMixin

Bases: object

Provide methods to create, add and get toolbuttons.

create_toolbutton(name, text=None, icon=None, tip=None, toggled=None, triggered=None, autoraise=True, text_beside_icon=False, section=None, option=None, register=True)

Create a Spyder toolbutton.

get_toolbutton(name: str, context: str | None = None, plugin: str | None = None) → QToolButton

Return toolbutton by name, plugin and context.

Parameters:

• name (str) – Name of the toolbutton to retrieve.

• context (Optional[str]) – Widget or context identifier under which the toolbutton was stored. If None, then CONTEXT_NAME is used instead

• plugin (Optional[str]) – Name of the plugin where the toolbutton was defined. If None, then PLUGIN_NAME is used.

Returns:

toolbutton – The corresponding toolbutton stored under the given name, context and plugin.

Return type:

QToolButton

Raises:

KeyError – If either of name, context or plugin keys do not exist in the toolbutton registry.

get_toolbuttons(context: str | None = None, plugin: str | None = None) → Dict[str, QToolButton]

Return all toolbuttons defined by a context on a given plugin.

Parameters:

• context (Optional[str]) – Widget or context identifier under which the toolbuttons were stored. If None, then CONTEXT_NAME is used instead

• plugin (Optional[str]) – Name of the plugin where the toolbuttons were defined. If None, then PLUGIN_NAME is used.

Returns:

toolbuttons – A dictionary that maps string keys to their corresponding toolbuttons.

Return type:

Dict[str, QToolButton]

class spyder.api.widgets.mixins.SpyderToolbarMixin

Bases: object

Provide methods to create, add and get toolbars.

add_item_to_toolbar(action_or_widget, toolbar, section=None, before=None, before_section=None)

If you provide a before action, the action will be placed before this one, so the section option will be ignored, since the action will now be placed in the same section as the before action.

create_stretcher(id_=None)

Create a stretcher widget to be used in a Qt toolbar.

create_toolbar(name: str, register: bool = True) → SpyderToolbar

Create a Spyder toolbar.

Parameters:

• name (str) – Name of the toolbar to create.

• register (bool) – Whether to register the toolbar in the global registry.

get_toolbar(name: str, context: str | None = None, plugin: str | None = None) → QToolBar

Return toolbar by name, plugin and context.

Parameters:

• name (str) – Name of the toolbar to retrieve.

• context (Optional[str]) – Widget or context identifier under which the toolbar was stored. If None, then CONTEXT_NAME is used instead

• plugin (Optional[str]) – Name of the plugin where the toolbar was defined. If None, then PLUGIN_NAME is used.

Returns:

toolbar – The corresponding toolbar stored under the given name, context and plugin.

Return type:

QToolBar

Raises:

KeyError – If either of name, context or plugin keys do not exist in the toolbar registry.

get_toolbars(context: str | None = None, plugin: str | None = None) → Dict[str, QToolBar]

Return all toolbars defined by a context on a given plugin.

Parameters:

• context (Optional[str]) – Widget or context identifier under which the toolbars were stored. If None, then CONTEXT_NAME is used instead

• plugin (Optional[str]) – Name of the plugin where the toolbars were defined. If None, then PLUGIN_NAME is used.

Returns:

toolbars – A dictionary that maps string keys to their corresponding toolbars.

Return type:

Dict[str, QToolBar]

class spyder.api.widgets.mixins.SpyderMenuMixin

Bases: object

Provide methods to create, add and get menus.

This mixin uses a custom menu object that allows for the creation of sections in a simple way.

add_item_to_menu(action_or_menu, menu, section=None, before=None, before_section=None)

Add a SpyderAction or a QWidget to the menu.

create_menu(menu_id: str, title: str | None = None, icon: QIcon | None = None, reposition: bool | None = True, register: bool = True) → SpyderMenu

Create a menu for Spyder.

Parameters:

• menu_id (str) – Unique str identifier for the menu.

• title (str or None) – Localized text string for the menu.

• icon (QIcon or None) – Icon to use for the menu.

• reposition (bool, optional (default True)) – Whether to vertically reposition the menu due to its padding.

• register (bool) – Whether to register the menu in the global registry.

Returns:

The created menu.

Return type:

SpyderMenu

get_menu(name: str, context: str | None = None, plugin: str | None = None) → SpyderMenu

Return a menu by name, plugin and context.

Parameters:

• name (str) – Name of the menu to retrieve.

• context (Optional[str]) – Widget or context identifier under which the menu was stored. If None, then CONTEXT_NAME is used instead

• plugin (Optional[str]) – Name of the plugin where the menu was defined. If None, then PLUGIN_NAME is used.

Returns:

menu – The corresponding menu stored under the given name, context and plugin.

Return type:

SpyderMenu

Raises:

KeyError – If either of name, context or plugin keys do not exist in the menu registry.

get_menus(context: str | None = None, plugin: str | None = None) → Dict[str, SpyderMenu]

Return all menus defined by a context on a given plugin.

Parameters:

• context (Optional[str]) – Widget or context identifier under which the menus were stored. If None, then CONTEXT_NAME is used instead

• plugin (Optional[str]) – Name of the plugin where the menus were defined. If None, then PLUGIN_NAME is used.

Returns:

menus – A dictionary that maps string keys to their corresponding menus.

Return type:

Dict[str, SpyderMenu]

class spyder.api.widgets.mixins.SpyderActionMixin

Bases: object

Provide methods to create, add and get actions in a unified way.

This mixin uses a custom action object.

create_action(name, text, icon=None, icon_text='', tip=None, toggled=None, triggered=None, data=None, shortcut=None, shortcut_context=None, context=3, initial=None, register_shortcut=False, section=None, option=None, parent=None, register_action=True, overwrite=False, context_name=None, menurole=None)

name: str

unique identifiable name for the action

text: str

Localized text for the action

icon: QIcon,

Icon for the action when applied to menu or toolbutton.

icon_text: str

Icon for text in toolbars. If True, this will also disable the tooltip on this toolbutton if part of a toolbar.

tip: str

Tooltip to define for action on menu or toolbar.

toggled: Optional[Union[Callable, bool]]

If True, then the action modifies the configuration option on the section specified. Otherwise, it should be a callable to use when toggling this action. If None, then the action does not behave like a checkbox.

triggered: callable

The callable to use when triggering this action.

data: Any

Data to be set on the action.

shortcut_context: str

Set the str context of the shortcut.

context: Qt.ShortcutContext

Set the context for the shortcut.

initial: object

Sets the initial state of a togglable action. This does not emit the toggled signal.

section: Optional[str]

Name of the configuration section whose option is going to be modified. If None, and option is not None, then it defaults to the class CONF_SECTION attribute.

option: ConfigurationKey

Name of the configuration option whose value is reflected and affected by the action.

register_shortcut: bool, optional

If True, main window will expose the shortcut in Preferences. The default value is False.

parent: QWidget (None)

Define the parent of the widget. Use self if not provided.

register_action: bool, optional

If True, the action will be registered and searchable. The default value is True.

overwrite: bool, optional

If True, in case of action overwriting no warning will be shown. The default value is False

context_name: Optional[str]

Name of the context that holds the action in case of registration. The combination of name and context_name is unique so trying to register an action with the same name and context_name will cause a warning unless overwrite is set to True.

menurole: QAction.MenuRole, optional

Menu role for the action (it only has effect on macOS).

Notes

There is no need to set shortcuts right now. We only create actions with this (and similar methods) and these are then exposed as possible shortcuts on plugin registration in the main window with the register_shortcut argument.

If icon_text is True, this will also disable the tooltip.

If a shortcut is found in the default config then it is assigned, otherwise it’s left blank for the user to define one for it.

get_action(name: str, context: str | None = None, plugin: str | None = None) → Any

Return an action by name, context and plugin.

Parameters:

• name (str) – Name of the action to retrieve.

• context (Optional[str]) – Widget or context identifier under which the action was stored. If None, then CONTEXT_NAME is used instead

• plugin (Optional[str]) – Name of the plugin where the action was defined. If None, then PLUGIN_NAME is used.

Returns:

action – The corresponding action stored under the given name, context and plugin.

Return type:

SpyderAction

Raises:

KeyError – If either of name, context or plugin keys do not exist in the action registry.

get_actions(context: str | None = None, plugin: str | None = None) → dict

Return all actions defined by a context on a given plugin.

Parameters:

• context (Optional[str]) – Widget or context identifier under which the actions were stored. If None, then CONTEXT_NAME is used instead

• plugin (Optional[str]) – Name of the plugin where the actions were defined. If None, then PLUGIN_NAME is used.

Returns:

actions – A dictionary that maps string keys to their corresponding actions.

Return type:

Dict[str, SpyderAction]

Notes

1. Actions should be created once. Creating new actions on menu popup is highly discouraged.

2. Actions can be created directly on a PluginMainWidget or PluginMainContainer subclass. Child widgets can also create actions, but they need to subclass SpyderWidgetMixin.

3. PluginMainWidget or PluginMainContainer will collect any actions defined in subwidgets (if defined) and expose them in the get_actions method at the plugin level.

4. Any action created this way is now exposed as a possible shortcut automatically without manual shortcut registration. If an option is found in the config system then it is assigned, otherwise it’s left with an empty shortcut.

5. There is no need to override this method.

update_actions(options)

Update the state of exposed actions.

Exposed actions are actions created by the create_action method.

class spyder.api.widgets.mixins.SpyderWidgetMixin(class_parent=None, parent=None)

Bases: SpyderActionMixin, SpyderMenuMixin, SpyderToolbarMixin, SpyderToolButtonMixin, SpyderShortcutsMixin

Basic functionality for all Spyder widgets and Qt items.

This provides a simple management of widget options, as well as Qt helpers for defining the actions a widget provides.

static create_icon(name)

Create an icon by name using the spyder Icon manager.

update_style()

Update stylesheet and style of the widget.

This method will be called recursively on all widgets on theme change.

update_translation()

Update localization of the widget.

This method will be called recursively on all widgets on language change.

class spyder.api.widgets.mixins.SpyderMainWindowMixin

Bases: object

Mixin with additional functionality for the QMainWindow’s used in Spyder.

move_to_primary_screen()

Move the window to the primary screen if necessary.

class spyder.api.widgets.mixins.SvgToScaledPixmap

Bases: SpyderConfigurationAccessor

Mixin to transform an SVG to a QPixmap that is scaled according to the factor set by users in Preferences.

svg_to_scaled_pixmap(svg_file, rescale=None, in_package=True)

Transform svg to a QPixmap that is scaled according to the factor set by users in Preferences.

Parameters:

• svg_file (str) – Name of or path to the svg file.

• rescale (float, optional) – Rescale pixmap according to a factor between 0 and 1.

• in_package (bool, optional) – Get svg from the images folder in the Spyder package.