Configuration Files

Write me.

Module Functions

kaa.config.set_default(var, value)

Set default value for the given scalar config variable.

kaa.config.get_default(var)

Returns the default value for the given scalar config variable.

kaa.config.get_description(var)

Get the description for the given config variable or group.

kaa.config.get_type(var)

Returns the type of the given config variable.

If the config variable is a scalar, non-enumerated type, then the return value will be the corresponding python type (int, str, unicode, float, etc.)

If the variable is a scalar enumerated type, the return value will be a tuple of possible values for that variable.

For non-scalar types, the return value will be one of List, Dict, or Group.

kaa.config.get_schema(var)

Returns the schema for a container variable (List or Dict), or None for scalar variables.

The schema is another config object (Var, List, Dict, or Group).

>>> kaa.config.get_description(cfg.movies)
u'Your favorite movies.'
>>> schema = kaa.config.get_schema(cfg.movies)
>>> kaa.config.get_description(schema)
u'A movie name.'
>>> kaa.config.get_type(schema)
<type 'str'>

kaa.config.get_config(filename, module=None)

Returns a Config object representing the config file provided in ‘filenane’. If module is None, the specified config file must have the module specified (in the “-- module: ... --” metadata), otherwise the supplied module (string) is used. The module must be importable.

If the config module cannot be determined and one is not specified, will raise ValueError. If import fails, will raise ImportError. Otherwise will return the Config object.

Config Objects

class kaa.config.Base(name='', desc=u'', default=None)

Base class for all config objects.

Synopsis

Class Hierarchy

kaa.config.Base

Methods

add_monitor()
copy()	Returns a deep-copy of the object. Monitor callbacks are not copied.
remove_monitor()

Properties

parent	read-only

Signals

This class has no signals.

Methods

add_monitor(callback)

copy(copy_on_write=False)

Returns a deep-copy of the object. Monitor callbacks are not copied.

Parameters:copy_on_write (bool) – if False, values are copied as well, so that if the original is modified, the copy will retain the old value. If True, fetching values in the copy will fetch the original’s current value, until and unless the copy’s value has been modified. Returns:a new cloned instance of the same type.

Note that only values may be copy-on-write. Any changes to the original’s schema (including type information and defaults) will not be reflected in the copy.

remove_monitor(callback)

Properties

parent

class kaa.config.Var(name='', type='', desc=u'', default=None)

A config variable that represents some scalar value such as int, str, unicode, or bool.

Synopsis

Class Hierarchy

kaa.config.Base
└─ kaa.config.Var

Methods

copy()

Properties

This class has no properties.

Signals

This class has no signals.

Methods

copy(copy_on_write=False)

class kaa.config.List(schema, desc=u'', name='', defaults=[])

A config list.

Synopsis

Class Hierarchy

kaa.config.Base
└─ kaa.config.Container
     └─ kaa.config.List

Methods

append()
extend()
insert()
pop()
remove()

Properties

This class has no properties.

Signals

This class has no signals.

Methods

append(val)

extend(vals)

insert(idx, val)

pop(idx=-1)

remove(val)

class kaa.config.Dict(schema, desc=u'', name='', type=<type 'unicode'>, defaults={})

A config dict.

Synopsis

Class Hierarchy

kaa.config.Base
└─ kaa.config.Container
     └─ kaa.config.Dict

Methods

get()	Get group or variable with the given index. Return None if it does not exist.
items()	Return key,value list (sorted by key name)
keys()	Return the keys (sorted by name)
values()	Return value list (sorted by key name)

Properties

This class has no properties.

Signals

This class has no signals.

Methods

get(index, default=None)

Get group or variable with the given index. Return None if it does not exist.

items()

Return key,value list (sorted by key name)

keys()

Return the keys (sorted by name)

values()

Return value list (sorted by key name)

class kaa.config.Group(schema, desc=u'', name='', desc_type='default')

A config group.

Synopsis

Class Hierarchy

kaa.config.Base
└─ kaa.config.Group

Methods

add_variable()	Add a variable to the group. The name will be set into the given value. The object will _not_ be copied.
copy()

Properties

variables	read-only	List of variables for this group.

Signals

This class has no signals.

Methods

add_variable(name, value)

Add a variable to the group. The name will be set into the given value. The object will _not_ be copied.

copy(copy_on_write=False)

Properties

variables

List of variables for this group.

class kaa.config.Config(schema, desc=u'', name='', module=None)

A config object. This is a group with functions to load and save a file.

Synopsis

Class Hierarchy

kaa.config.Base
└─ kaa.Object
└─ kaa.config.Group
     └─ kaa.config.Config

Methods

copy()
load()	Load values from a config file previously saved for this schema.
save()	Save configuration file.
watch()	If argument is True (default), adds a watch to the config file and will reload the config if it changes. If INotify is available, use that, otherwise stat the file every 3 seconds.

Properties

autosave	read/write	Whether or not changes are automatically save.

Signals

reloaded	Emitted when the configuration file is automatically reloaded from disk due to watch().

Methods

copy(copy_on_write=False)

load(filename=None, sync=False)

Load values from a config file previously saved for this schema.

Parameters:

• filename (str) – filename to load values from; if None, will use the filename property.
• sync (bool) – if True, will overwrite the current file (retaining previous values, of course) if the schema has changed, or create the config file if it does not exist. (Default: False)

If no filename has been previously set with the filename property then the filename argument is required, and in that case the filename property will be set to this value.

save(filename=None, force=False)

Save configuration file.

Parameters:

• filename – the name of the file to save; if None specified, will use the name of the previously loaded file, or the value assigned to the filename property.
• force (bool) – if False (default), will only write the file if there were any changes (to either values or the schema).

watch(watch=True)

If argument is True (default), adds a watch to the config file and will reload the config if it changes. If INotify is available, use that, otherwise stat the file every 3 seconds.

If argument is False, disable any watches.

Properties

autosave

Whether or not changes are automatically save.

If True, will write the config filename (either previously passed to load() or defined by the filename property) 5 seconds after the last config value update (or program exit, whichever comes first).

Default is False.

Signals

reloaded

Emitted when the configuration file is automatically reloaded from disk due to watch().

def callback(changed_names, ...)

Param changed_names:  the names of the variables that changed Type changed_names:  list