user_config package — user_config 1.0a4 documentation

# user_config package

## Submodules

## user_config.ini module

ini configuration file format.

`user_config.ini.` `ini_read`(_, path, elements, data)

  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 data (Dict) – data 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, data, 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 data (Dict) – data 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.` `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`

  Bases: `user_config.MappingMixin`

  Base class for application configuration.

  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: | InvalidArgument: – if default value does not pass validation

  `element_name`

    str – name of instance, provided by containing class

  `type_`

    type – python type of variable that this class represents

  Examples

  ..doctest:

      >>> TODO

  `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

  `element_name` = None
  `extract_data_from_parser`(command_line_arguments, data)

    Get value from parser.

    Parameters: | command_line_arguments (argparse.Namespace) – parsed arguments data (Dict) – dictionary to put values in (assumes tree structure is already in place)
    Raises: | `None`
    Returns: |
    Return type: | None

    Examples

    ..doctest:

        >>> TODO

  `get_default`()

    Return default value.

  `has_default`()

    Return True if element has a default 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`(data)

    Validate data.

    Parameters: | data (Dict) – data structure in which to find and validate our own element
    Raises: | InvalidData: – if validation fails MissingData: – if self.required is True and our value in data 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.` `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.` `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`(doc=None, default=None, required=True, short_name=None, long_name=None, validate=None, **content)

  Bases: `user_config.ConfigElement`, `user_config.MappingMixin`

  Named container that contains ConfigElements.

  Keyword Arguments:
  | doc (str, optional) – documentation for this option, defaults to None default (Any, optional) – IGNORED 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 short_name (str, optional) – IGNORED long_name (str, optional) – IGNORED validate (Callable[Any, None], optional) – additional validation function, defaults to None **content (ConfigElement, optional) – content of section
  Raises: | AttributeError: – if content element is not a ConfigElement

  `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_default`()

    Fetch and store default Section elements.

  `get_elements`()

    Return elements and data.

  `has_default`()

    Return True because Section always has a default value.

  `incomplete_count` = 0
  `validate`(value)
  `validate_data`(_)

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