user_config package¶

Submodules¶

user_config.ini module¶

ini configuration file format.

user_config.ini.ini_read(_, path, elements)¶

Read ini configuration file and populate data.

Parameters:	_ (user_config.Config) – IGNORED path (pathlib.Path) – path to configuration file elements (Dict[ConfigElement]) – configuration element tree
Raises:	`None`
Returns:
Return type:	None

Examples

..doctest:

>>> TODO

user_config.ini.ini_validate(_, elements)¶

Make sure element tree is suitable for ini files.

Parameters:	_ (user_config.Config) – IGNORED elements (Dict[ConfigElement]) – element tree
Raises:	InvalidConfigTree: – if the config tree is inappropriate for ini files
Returns:
Return type:	None

Examples

..doctest:

>>> TODO

user_config.ini.ini_write(_, elements, doc)¶

Print default ini file.

This includes data already set in the existing configuration files.

Parameters:	_ (user_config.Config) – IGNORED elements (Dict[ConfigElement]) – configuration element tree doc (Option[str]) – Config class docstring
Raises:	`None`
Returns:
Return type:	None

Examples

..doctest:

>>> TODO

user_config.ini.register_extension()¶

Register ini file format functions with user_config.

Returns:
Return type:	Dict

Examples

..doctest:

>>> register_extension()
{'read': <function ini_read at 0x...>, 'write': <function ini_write at 0x...>, 'validate': <function ini_validate at 0x...>, 'extension': 'cfg'}

Module contents¶

User config management.

class user_config.BooleanListOption(doc=None, default=None, required=True, short_name=None, long_name=None, validate=None, additive=False)¶

Bases: user_config.StringListOption

List configuration element with boolean content.

subtype¶: alias of bool

class user_config.BooleanOption(doc=None, default=None, required=True, short_name=None, long_name=None, validate=None)¶

Bases: user_config.ConfigElement

Configuration element with boolean value.

type_¶: alias of bool

class user_config.Config(file_name='config', global_path=None, user_path=None, cli=True)¶

Bases: user_config.MappingMixin

Base class for application configuration.

Keyword Arguments:
	file_name (str, optional) – name of the configuration file, defaults to config global_path (pathlib.Path, optional) – overwrite system global configuration path, defaults to None user_path (pathlib.Path, optional) – overwrite system user configuration path, defaults to None cli (bool, optional) – whether to parse commandline arguments, defaults to True
Raises:	AttributeError: – if application or author is not set InvalidConfigTree: – if configuration tree is inappropriate for file_type InvalidData: – if user supplied invalid data for a configuration element MissingData: – if an element marked as required has no value

file_type¶: str – file type to use for configuration files

application¶: str – application name

author¶: str – application author

version¶: str, optional – application version (set if your configuration is version dependent)

Examples

..doctest:

>>> TODO

application = None

author = None

version = None

class user_config.ConfigElement(doc=None, default=None, required=True, short_name=None, long_name=None, validate=None)¶

Bases: object

Base class for configuration elements.

Keyword Arguments:

doc (str, optional) – documentation for this option, defaults to None
default (Any, optional) – fallback value, defaults to None
required (bool, optional) – MUST a value be present? If no default is provided, this can result in a MissingData exception. Defaults to True
short_name (str, optional) – short name for use with command line arguments, defaults to None
long_name (str, optional) – overwrite default name for command line arguments, defaults to None
validate (Callable[Any, None], optional) – additional validation function, defaults to None

Raises:

InvalidData: – if default value does not pass validation

creation_counter¶: int – global count of config elements, used to maintain field order

element_name¶: str – name of instance, provided by containing class

type_¶: type – python type of variable that this class represents

action¶: str – action for argparse

Examples

..doctest:

>>> TODO

action = 'store'

construct_parser(parser)¶

Add self to parser.

Parameters:	parser (argparse.ArgumentParser) – the argument parser to add an option to
Raises:	`None`
Returns:
Return type:	None

Examples

..doctest:

>>> TODO

creation_counter = 0

element_name = None

extract_data_from_parser(command_line_arguments)¶

Get value from parser.

Parameters:	command_line_arguments (argparse.Namespace) – parsed arguments
Raises:	`None`
Returns:
Return type:	None

Examples

..doctest:

>>> TODO

get_default()¶: Return default value.

get_value()¶: Return current option value.

has_default()¶: Return True if element has a default value.

set_value(value)¶: Validate and store value.

type_: alias of str

validate(value)¶

Validate individual value.

Parameters:	value (Any) – to be validated
Raises:	InvalidData: – if validation fails
Returns:
Return type:	None

Examples

..doctest:

>>> TODO

validate_data()¶

Validate data.

Raises:	InvalidData: – if validation fails MissingData: – if self.required is True and our value is None
Returns:
Return type:	None

Examples

..doctest:

>>> TODO

class user_config.ConfigMeta¶

Bases: type

ORM-like magic for configuration class.

Gather all ConfigElement attributes into _elements and get correct _validate, _read and _writer functions.

Parameters:	cls_name (str) – class name cls_parents (Tuple[class]) – class parents cls_attributes (Dict) – class attributes
Raises:	AttributeError: – if class tries to overwrite a reserved attribute ImportError: – if no appropriate entry_point could be found for file_type

Examples

..doctest:

>>> TODO

class user_config.FloatListOption(doc=None, default=None, required=True, short_name=None, long_name=None, validate=None, additive=False)¶

Bases: user_config.StringListOption

List configuration element with float content.

subtype¶: alias of float

class user_config.FloatOption(doc=None, default=None, required=True, short_name=None, long_name=None, validate=None)¶

Bases: user_config.ConfigElement

Configuration element with float value.

type_¶: alias of float

class user_config.IntegerListOption(doc=None, default=None, required=True, short_name=None, long_name=None, validate=None, additive=False)¶

Bases: user_config.StringListOption

List configuration element with integer content.

subtype¶: alias of int

class user_config.IntegerOption(doc=None, default=None, required=True, short_name=None, long_name=None, validate=None)¶

Bases: user_config.ConfigElement

Configuration element with integer value.

type_¶: alias of int

exception user_config.InvalidConfigTree¶

Bases: Exception

Inappropriate configuration tree for file type.

exception user_config.InvalidData¶

Bases: Exception

User supplied invalid data for a configuration element.

class user_config.MappingMixin¶

Bases: object

Methods for emulating a mapping type.

get(key, default)¶: Get items without risking a KeyError.

items()¶: Return a view of dictionary key, value pairs.

keys()¶: Return a view of dictionary keys.

update(*args, **kwargs)¶: Update more than one key at a time.

values()¶: Return a view of dictionary values.

exception user_config.MissingData¶

Bases: Exception

An element marked as required is missing a value.

class user_config.Section(required=True, validate=None)¶

Bases: user_config.ConfigElement, user_config.MappingMixin

Named container that contains ConfigElements.

Keyword Arguments:
	required (bool, optional) – MUST section be present? If no default is provided for any required content elements, this can result in a MissingData exception. to find out if an optional section is complete, see self.incomplete_count. Defaults to True validate (Callable[Any, None], optional) – additional validation function, defaults to None
Raises:	AttributeError: – if content element is not a ConfigElement

creation_counter¶: int – global count of config elements, used to maintain field order

element_name¶: str – name of instance, provided by containing class

type_¶: type – python type of variable that this class represents

action¶: str – action for argparse

incomplete_count¶: int – Number of content elements which are required, but do not have a value. Useful for sections which are not marked as required, but do have required elements.

Examples

..doctest:

>>> TODO

construct_parser(parser)¶

extract_data_from_parser(command_line_arguments)¶

get_elements()¶: Return raw element tree, use with caution.

get_value()¶: Return current content value.

has_default()¶: Return True because Section always has a default value.

incomplete_count = 0

set_value(value)¶: Validate and store value.

type_: alias of dict

validate(value)¶

validate_data()¶

class user_config.StringListOption(doc=None, default=None, required=True, short_name=None, long_name=None, validate=None, additive=False)¶

Bases: user_config.ConfigElement

Configuration element with list value.

Keyword Arguments:

doc (str, optional) – documentation for this option, defaults to None
default (Any, optional) – fallback value, defaults to None
required (bool, optional) – MUST a value be present? If no default is provided, this can result in a MissingData exception. Defaults to True
short_name (str, optional) – short name for use with command line arguments, defaults to None
long_name (str, optional) – overwrite default name for command line arguments, defaults to None
validate (Callable[Any, None], optional) – additional validation function, defaults to None
additive (bool, optional) – whether to add all found lists together instead of overwrite them, defaults to False

Raises:

InvalidData: – if default value does not pass validation

creation_counter¶: int – global count of config elements, used to maintain field order

element_name¶: str – name of instance, provided by containing class

type_¶: type – python type of variable that this class represents

subtype¶: type – python type of list items

action¶: str – action for argparse

Examples

..doctest:

>>> TODO

action = 'append'

append(value)¶: Append value to option.

count(value)¶: Count occurrence of value.

extend(extension)¶: Extend value of option with extension.

extract_data_from_parser(command_line_arguments)¶

index(value)¶: Return index of first occurrence of value.

insert(index, value)¶: Insert value at index.

pop(index=-1)¶: Remove and return value at index.

remove(value)¶: Remove value.

reverse()¶: Reverse list in place.

set_value(value)¶

sort(key=None, reverse=False)¶: Sort list in place.

subtype: alias of str

type_: alias of list

validate(value)¶

class user_config.StringOption(doc=None, default=None, required=True, short_name=None, long_name=None, validate=None)¶

Bases: user_config.ConfigElement

Configuration element with string value.

type_¶: alias of str

user_config.with_metaclass(meta, *bases)¶

Create a base class with a metaclass.

Drops the middle class upon creation. Source: http://lucumr.pocoo.org/2013/5/21/porting-to-python-3-redux/

Parameters:	meta (type) – meta class or function bases (object*) – parents of class to be created
Raises:	`None`
Returns:
Return type:	class of type name

Examples

..doctest:

>>> TODO