Overview.¶

To simplify the management of function default keyword argument values funconf introduces two new decorators. The first decorator wraps_parameters() makes it trivial to dynamically define the default values of parameters to a function. The second decorator lazy_string_cast() automatically casts basestring values to the type of the keyword default values found in the function it is wrapping and the type of the values found in the key:value object passed into its constructor.

For configuration, funconf borrows from concepts discussed in Python’s core library ConfigParser. A configuration consists of sections made up of option:value entries, or two levels of mappings that take on the form section:option:value.

The file format YAML has been chosen to allow for option values to exist as different types instead of being restricted to string type values.

$ cat my.conf
#
# Foo
#
foo:
  bar: 4
  moo:
  - how
  - are
  - you

#
# Bread
#
bread:
  butter: win
  milk: fail

config = funconf.Config()
config.set('foo', 'bar', 4)
config.set('foo', 'bar', ['how', 'are', 'you'])
config.set('bread', 'butter', 'milk')
config.set('bread', 'milk', 'fail')
print(config)

{'bread_butter': 'win',
 'bread_milk': 'fail',
 'foo_bar': 4,
 'foo_moo': ['how', 'are', 'you']}

@config
def myfunc(**kwargs):
    print(kwargs)

assert config.bread.milk == 'fail'
assert config.bread['milk'] == 'fail'
assert config['bread_milk'] == 'fail'

bread:
  butter: win
  milk: fail

@config.bread
def myfunc(**kwargs):
    print(kwargs)

Code reference guide¶

funconf.wraps_parameters(default_kwargs, hide_var_keyword=False, hide_var_positional=False)¶

Decorate a function to define and extend its positional and keyword variables.

The following example will redefine myfunc to have defaults of a=4 and b=3:

mydict = {a=4, b=3}
@wraps_parameters(mydict)
def myfunc(a, b=2):
    pass

The default_kwargs object needs to satisfy the MutableMapping interface definition. When a wrapped function is called the following transforms occur over kwargs before it is passed into the wrapped function:

1. default_kwargs is updated with new input parameters.
2. If the wrapped function has a variable keyword argument defined (i.e **k) then the keywords defined by default_kwargs that are not defined in kwargs will be copied into kwargs.
3. If the wrapped function had no variable keyword argument defined, then the keyword input parameters that don’t belong to the wrapped function’s parameters list will be discarded.

Parameters:	default_kwargs (mutable mapping) – kwargs to be fix into the wrapped function. hide_var_keyword (Boolean value default True.) – hide the variable keyword parameter. hide_var_arguments (Boolean value default True.) – hide the variable keyword parameter.
Return type:	decorated function.

funconf.lazy_string_cast(model_parameters={}, provide_defaults=True)¶

Type cast string input values if they differ from the type of the default value found in model_parameters.

The following list details how each type is handled:

int, bool, float:

If the input value string can not be cast into an int, bool, or float, the exception generated during the attempted conversion will be raised.

list:

The input value string will be split into a list shlex.split. If the default list value in model contains items, the first item is sampled an attempt to cast the entire list is made for that type.

other:

An attempt to convert other types will be made. If this fails, the input value will be passed through in its original string form.

This example demonstrates how lazy_string_cast() can be applied:

@lazy_string_cast
def main(a=4, b=[4, 2, 55]):
    pass

Or using lazy_string_cast() with wraps_parameters() to define new keyword defaults:

config = dict(a=6, b=[4])

@lazy_string_cast(config)
@wraps_parameters()
def main(a=4, b=[4, 2, 55]):
    pass

Parameters:	model_parameters (mutable mapping) – kwargs to model default type values and keys from. provide_defaults (Boolean value default True.) – If true, use model_parameters to default arguments which are empty.
Return type:	decorated function.

class funconf.Config(filenames=, []strict=False)¶

The Config class is the root container that represents configuration state set programmatically or read in from YAML config files.

The following lists the main features of this class:

1. Aggregates ConfigSection objects that are accessible through attributes.
2. Exposes a translation of the configuration into section_option:value through a standard implementation of the MutableMapping abstract type.
3. When cast to a string it outputs YAML.
4. As a decorator it utilises the wraps_parameters() to change the defaults of a variable kwargs function.

__call__(func=None, lazy=True, hide_var_positional=False, hide_var_keyword=True)¶

The Config object can be used as a function decorator.

Applying this decorator to a function which takes variable kwargs will change its signature to a set of kwargs with default values defined using the values in this Config object. The input kwargs go through the lazy_string_cast() function and are passed into this objects update routine. The wrapped function is finally called with the updated values of this object.

For example:

myconfig = Config('my.conf')

@myconfig
def func(**k):
    pass

Parameters:	func (function or method) – Decorator parameter. The function or method to be wrapped. lazy (Boolean value default True) – Factory parameter. Turns lazy_string_cast on or off.
Return type:	As a factory returns decorator function. As a decorator function returns a decorated function.

__dir__()¶

Return a list of section names and the Base class attributes.

__getattribute__(y)¶

Return a section where y is the section name. Else, return the value of a reserved word.

__getitem__(y)¶

Return the option value for y where y is section_option.

__init__(filenames=, []strict=False)¶

Construct a new Config object.

This is the root object for a function configuration set. It is the container for the configuration sections.

Parameters:	filenames (list of filepaths) – YAML configuration files. strict (False) – If True, raise ConfigAttributeError if a ConfigSection doesn’t exist.

__iter__()¶

Iterate all of the section_option keys.

__len__()¶

Return the number of options defined in this Config object

__setattr__(x, y)¶

Only attributes that are a reserved words can be set in this object.

__setitem__(x, y)¶

Set the option value of y for x where x is section_option.

__str__()¶

Return a YAML formated string object that represents this object.

load(stream)¶

Parse the first YAML document from stream then load the section:option:value elements into this Config object.

Parameters:	stream (stream object) – the configuration to be loaded using yaml.load.

read(filenames)¶

Read and parse a filename or a list of filenames.

Files that cannot be opened are silently ignored; this is designed so that you can specify a list of potential configuration file locations (e.g. current directory, user’s home directory, system wide directory), and all existing configuration files in the list will be read. A single filename may also be given.

Parameters:	filenames (list of filepaths) – YAML configuration files.
Return type:	list of successfully read files.

set(section, option, value)¶

Set an option.

In the event of setting an option name or section name to a reserved word a ValueError will be raised. A complete set of reserved words for both section and option can be seen by:

print(dir(funconf.Config))
print(dir(funconf.ConfigOption))

Parameters:	section (str) – Name of the section to add the option into. option (str) – Name of the option. value – Value assigned to this option.

class funconf.ConfigSection(section, options)¶

The ConfigSection class is a mutable mapping object that represents the option:value items for a configuration section.

The following lists the main features of this class:

1. Exposes a configuration option:value through a standard implementation of the MutableMapping abstract type.
2. When cast to a string it outputs YAML.
3. As a decorator it utilises the wraps_parameters() to change the defaults of a variable kwargs function.

__call__(func=None, lazy=True, hide_var_positional=False, hide_var_keyword=True)¶

The ConfigSection object can be used as a function decorator.

Applying this decorator to a function which takes variable kwargs will change its signature to a set of kwargs with default values defined using the values in this ConfigSection object. The input kwargs go through the lazy_string_cast() function and are passed into this objects update routine. The wrapped function is finally called with the updated values of this object.

For example:

myconfig = Config('my.conf')

@myconfig.mysection
def func(**k):
    pass

Parameters:	func (function or method) – Decorator parameter. The function or method to be wrapped. lazy (Boolean value default True) – Factory parameter. Turns lazy_string_cast on or off.
Return type:	As a factory returns decorator function. As a decorator function returns a decorated function.

__dir__()¶

Return a list of option names and the Base class attributes.

__getattribute__(y)¶

Return a option value where y is the option name. Else, return the value of a reserved word.

__getitem__(y)¶

Return the option value for y where y is option.

__init__(section, options)¶

Construct a new ConfigSection object.

This object represents a section which contains the mappings between the section’s options and their respective values.

Parameters:	section (str) – defines the name for this section. options (mutable mapping) – kwargs to initialise this ConfigSection‘s option:value

__iter__()¶

Iterate all of the ‘option’ keys.

__len__()¶

Return the number of options defined in this ConfigSection object

__setattr__(x, y)¶

Only attributes that are a reserved words can be set in this object.

__setitem__(x, y)¶

Set the option value of y for x where x is option.

__str__()¶

Return a YAML formated string object that represents this object.

dirty¶

The dirty property is a convenience property which is set when a change has occurred to one of the options under this section. Once this property is read, it is reset to False.

This property is particularly useful if you’re software system has the ability to change the configuration state during runtime. It means that you no longer need to remember the state of the options, you just need to know that when the dirty property is set, there has been a change in the configuration for this section.

Return type:	boolean value of dirty.