spyder.api.config.mixins

spyder.api.config.mixins#

Spyder API configuration helper mixins.

Module Attributes

BasicTypes

Type alias for the set of basic Python types supported as config values.

Classes

SpyderConfigurationAccessor()

Mixin to access options stored in the Spyder configuration system.

SpyderConfigurationObserver()

Methods to receive and respond to changes in Spyder's configuration.
spyder.api.config.mixins.BasicTypes#

Type alias for the set of basic Python types supported as config values.

alias of bool | int | str | tuple | list | dict

class spyder.api.config.mixins.SpyderConfigurationAccessor[source]#

Bases: object

Mixin to access options stored in the Spyder configuration system.

CONF_SECTION: str | None = None#

Name of the default configuration section to use for this object.

Will be used to record its permanent data in Spyder’s config system.

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

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.config.user.NoDefault | BasicTypes, 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, 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.

Return type:

BasicTypes

Raises:

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

get_conf_options(section: str | None = None) → list[str][source]#

Get all option names from the given section.

Parameters:

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

Returns:

values – List of option names (keys) in the configuration section.

Return type:

list[str]

Raises:

configparser.NoOptionError – If section does not exist in the configuration.

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

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 (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, 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

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

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, 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

get_conf_default(option: spyder.config.types.ConfigurationKey, section: str | None = None) → NoDefault | spyder.api.config.mixins.BasicTypes[source]#

Get an option’s default value from the Spyder configuration system.

Parameters:

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

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

Returns:

The option’s default value, or spyder.config.user.NoDefault if one is not set.

Return type:

spyder.config.user.NoDefault | BasicTypes

property spyder_conf_version: str#

Get current version of the Spyder configuration system.

Returns:

The current Spyder spyder.config.manager.CONF_VERSION, as a string of MAJOR.MINOR.MICRO.

Return type:

str

property old_spyder_conf_version: str#

Get previous version of the Spyder configuration system.

Returns:

The previous Spyder spyder.config.manager.CONF_VERSION prior to the most recent Spyder update, as a string of MAJOR.MINOR.MICRO.

Return type:

str

class spyder.api.config.mixins.SpyderConfigurationObserver[source]#

Bases: SpyderConfigurationAccessor

Methods to receive and respond to changes in Spyder’s configuration.

This mixin enables a class to receive configuration updates seamlessly, by registering methods using the on_conf_change() decorator, which takes a configuration section and option to observe.

When a change occurs on any of the registered configuration options, the corresponding registered method is called with the new config value.

__init__() → None[source]#

Create a new SpyderConfigurationObserver.

Important

Classes or their parents implementing this mixin must define a CONF_SECTION class attribute with the name of their default configuration section.

Return type:

None

__del__() → None[source]#

Remove an object from the configuration observer.

on_configuration_change(option: spyder.config.types.ConfigurationKey, section: str, value: spyder.api.config.mixins.BasicTypes) → None[source]#

Handle configuration value updates for a config option.

Parameters:

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

  • section (str) – Name of the section containing option, e.g. "shortcuts".

  • value (BasicTypes) – New value of the configuration option that produced the event.

Return type:

None

add_configuration_observer(func: Callable, option: spyder.config.types.ConfigurationKey, section: str | None = None) → None[source]#

Add a callable to observe changes to a specific configuration option.

Parameters:

  • func (Callable) – Function/method that will be called when option changes.

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

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

Return type:

None

Notes

  • This is only necessary if you need to add a callable that is not a class method to observe an option. Otherwise, you only need to decorate your method with on_conf_change().

Contents