settings: Save/access tool interface values¶
settings: Save/access tool interface values¶
Basic Usage¶
This module provides a convenient way for tools to remember preferred settings.
To do so you create a subclass of this module’s Settings
class and
populate it with setting names and default values. There are two varieties of
settings, ones that are automatically saved to disk when they’re set, and ones
that only save to disk when the Settings.save() method is called. The former
might be used for minor conveniences in the interface, like remembering which
file format the user last used, whereas the latter would be used if a tool
presents an explicit Save button for preserving configuration information.
The settings are presented as attributes of the Settings instance, so therefore the setting name has to be legal as an attribute, i.e. no spaces, just alphanumeric characters plus underscore. Also, leading underscores are not allowed.
Example
setup
use
saving
As mentioned above, the AUTO_SAVE/EXPLICIT_SAVE keys have to be legal to use
as attribute names. The values can be just plain Python values, in which case
their repr()
will be saved to disk, or they can be more complex
entities, like enumerations or class instances. In the latter case you have
to use the Value
class to tell the settings
mechanism how to save and restore the value and perhaps check that the value is
within its legal range of values. The three arguments to Value() are:
The default value.
A function to convert text to the value, or an object that can convert the text into the needed value by following the
Annotation
abstract class protocol.A function that converts a value to text.
There are many Annotation subclasses in the cli
module that can be used as the second argument to Value() and that also
perform range checking.
Advanced Usage¶
- Adding a setting
One simply adds the definition into the appropriate dictionary, and increases the minor part of the Settings version number. The version number is provided as a keyword argument (named version) to the Settings constructor. It defaults to “1”.
- Moving/deleting settings
This involves adding properties to your Settings subclass and is discussed in detail in the
configfile
documentation.
- class Settings(session, tool_name, version='1')¶
Bases:
ConfigFile
Supported API. Save/remember tool interface settings
A tool remembers interface setting across tool invocations with this class. There are two types of settings supported: ones that save to disk immediately when changed, and ones that are saved to disk only when the
save()
method is called.A tools uses Settings by subclassing and defining class dictionaries named AUTO_SAVE and EXPLICIT_SAVE containing the names of the settings and their default values. This is explained in detail in the
settings
module documentation.- Parameters:
- AUTO_SAVE¶
Class dictionary containing setting names and default values. Such settings will be saved to disk immediately when changed.
- Type:
Dict
- EXPLICIT_SAVE¶
Class dictionary containing setting names and default values. Such settings will be saved to disk only when the
save()
method is called.- Type:
Dict
- triggers¶
When a setting changes its current value, the ‘setting changed’ trigger will be activated with (attr_name, prev_val, new_val) as the data provided with the trigger.
- Type:
- reset()¶
Supported API . Reset (revert to default) all settings.
- restore()¶
Supported API . Restore (revert to saved) all settings.
- save(setting=None, *, settings=None)¶
Supported API . Save settings to disk. Only needed for EXPLICIT_SAVE settings. AUTO_SAVE settings are immediately saved to disk when changed.
If ‘setting’ or ‘settings’ is specified, save only those settings (don’t change saved value of any other setting. Otherwise, save all settings.
- update(*args, **kw)¶
Experimental API . Update all corresponding items from dict or iterator or keywords.
Treat preferences as a dictionary and
update()
them.- Parameters:
dict_iter (dict/iterator)
**kw (optional name, value items)