Plugins

class UserDefaults(filepath, defaults=None, header='Settings')

Support for reading and writing settings files in .ini format.

This can be used to provide state persistence for UI elements of a plugin.

Examples:

Initialize a new config object, modify and then save it:

>>> filepath = os.path.join(os.path.dirname(os.path.abspath(__file__)), "res", "settings.ini")
>>> defaults = UserDefaults(filepath=filepath)
>>> defaults.Set('key', 'value')
>>> defaults.Save()

If filepath points to an existing file, it will use that file and initializing a new config object by reading from it.

If you later want to read in the config file:

>>> defaults.Read()
>>> print(defaults.Get('setting'))
value
>>> print(defaults.Get('does-not-exist', default='use default instead'))
use default instead

Parameters:

• filepath (str) – usually res/settings.ini relative to the source code file of the plugin, that uses the config store.
• defaults – dict default values to be used if the config file needs to be created. It is also possible to pass None here and then use the Set() and Save() functions to set inidividual settings after creation of the config object.
• header (str) – the name for a section in the .ini file. Usually you can get away with leaving it at the default. This will add a header [Settings] under which your settings will appear. If you have more advanced uses you are advised to modify the config parser state directly through self.state.

Get(self, name, section=None, default=None, valuetype="str")

Retrieve a previously stored value from the config object.

Parameters:

• name (str) – name of the setting
• section (str) – the section name. self.header if None.
• default (any) – a default value to use in case name wasn’t found.
• valuetype (str) – type of the value to get. can be one of [str, bool, int, float].

Returns:

str on success, None or default on failure. this will always return a string even if the value was stored as another type previously. So the caller is responsible for the convertion to the wanted data type.

GetInt(self, name, section=None, default=None)

Retrieve a previously stored integer value from the config object.

Parameters:

• name (str) – name of the setting
• section (str) – the section name. self.header if None.
• default (any) – a default value to use in case name wasn’t found.

Returns:

int on success, None or ‘default’ on failure.

GetFloat(self, name, section=None, default=None)

Retrieve a previously stored float value from the config object.

Parameters:

• name (str) – name of the setting
• section (str) – the section name. self.header if None.
• default (any) – a default value to use in case name wasn’t found.

Returns:

float on success, None or ‘default’ on failure.

GetBool(self, name, section=None, default=None)

Retrieve a previously stored boolean value from the config object.

Parameters:

• name (str) – name of the setting
• section (str) – the section name. self.header if None.
• default (any) – a default value to use in case name wasn’t found.

Returns:

bool on success, None or ‘default’ on failure.

Set(self, name, value, section=None)

Store a value in the config object for later retrieval.

Parameters:

• name (str) – name of the setting
• value (any) – value to set.
• section (str) – the section name. self.header if None.

Returns:

True if successful, False otherwise.

Read(self)

Read state from configuration file.

Returns:True if successful. Raises OSError:if config file couldn’t be read.

Save(self, config=None, filepath=None)

Save settings to a configuration file.

Parameters:

• config (ConfigParser) – the config object to save. If None, uses self.config instead.
• filepath (str) – allows for specifying another path than self.filepath in order to save a copy of the config object.

Returns:

True if successful, False otherwise.