apptools.preferences.scoped_preferences module

A preferences node that adds the notion of preferences scopes.

class apptools.preferences.scoped_preferences.ScopedPreferences(**traits)

Bases: Preferences

A preferences node that adds the notion of preferences scopes.

Scopes provide a way to access preferences in a precedence order, usually depending on where they came from, for example from the command-line, or set by the user in a preferences file, or the defaults (set by the developer).

By default, this class provides two scopes - ‘application’ which is persistent and ‘default’ which is not.

Path names passed to ‘ScopedPreferences’ nodes can be either:

a) a preference path as used in a standard 'Preferences' node, e.g::

'acme.widget.bgcolor'.

In this case the operation either takes place in the primary scope
(for operations such as 'set' etc), or on all scopes in precedence
order (for operations such as 'get' etc).

or

b) a preference path that refers to a specific scope e.g::

'default/acme.widget.bgcolor'

In this case the operation takes place *only* in the specified scope.

There is one drawback to this scheme. If you want to access a scope node itself via the ‘clear’, ‘keys’, ‘node’, ‘node_exists’ or ‘node_names’ methods then you have to append a trailing ‘/’ to the path. Without that, the node would try to perform the operation in the primary scope.

e.g. To get the names of the children of the ‘application’ scope, use:

scoped.node_names('application/')

If you did this:

scoped.node_names('application')

Then the node would get the primary scope and try to find its child node called ‘application’.

Of course you can just get the scope via:

application_scope = scoped.get_scope('application')

and then call whatever methods you like on it - which is definitely more intentional and is highly recommended:

application_scope.node_names()

add_preferences_listener(listener, path='')

Add a listener for changes to a node’s preferences.

clear(path='')

Remove all preference from the node at the specified path.

dump(indent='')

Dump the preferences hierarchy to stdout.

get(path, default=None, inherit=False)

Get the value of the preference at the specified path.

get_scope(scope_name)

Return the scope with the specified name.

Return None if no such scope exists.

keys(path='')

Return the preference keys of the node at the specified path.

load(file_or_filename=None)

Load preferences from a file.

This loads the preferences into the primary scope.

fixme: I’m not sure it is worth providing an implentation here. I think it would be better to encourage people to explicitly reference a particular scope.

node(path='')

Return the node at the specified path.

node_exists(path='')

Return True if the node at the specified path exists.

node_names(path='')

Return the names of the children of the node at the specified path.

remove(path)

Remove the preference at the specified path.

remove_preferences_listener(listener, path='')

Remove a listener for changes to a node’s preferences.

save(file_or_filename=None)

Save the node’s preferences to a file.

This asks each scope in turn to save its preferences.

If a file or filename is specified then it is only passed to the primary scope.

set(path, value)

Set the value of the preference at the specified path.