API Documentation

This part of the documentation covers the interfaces used to develop with confuse.

Core

Worry-free YAML configuration files.

class confuse.core.ConfigView

Bases: object

A configuration “view” is a query into a program’s configuration data. A view represents a hypothetical location in the configuration tree; to extract the data from the location, a client typically calls the view.get() method. The client can access children in the tree (subviews) by subscripting the parent view (i.e., view[key]).

add(value)

Set the default value for this configuration view. The specified value is added as the lowest-priority configuration data source.

all_contents()

Iterates over all subviews from collections at this view from all sources. If the object for this view in any source is not iterable, then a ConfigTypeError is raised. This method is intended to be used when the view indicates a list; this method will concatenate the contents of the list from all sources.

as_choice(choices)

Get the value from a list of choices. Equivalent to get(Choice(choices)).

Sequences, dictionaries and Enum types are supported, see confuse.templates.Choice for more details.

as_filename()

Get the value as a path. Equivalent to get(Filename()).

as_number()

Get the value as any number type: int or float. Equivalent to get(Number()).

as_pairs(default_value=None)

Get the value as a sequence of pairs of two strings. Equivalent to get(Pairs(default_value=default_value)).

as_path()

Get the value as a pathlib.Path object. Equivalent to get(Path()).

as_str()

Get the value as a (Unicode) string. Equivalent to get(unicode) on Python 2 and get(str) on Python 3.

as_str_expanded()

Get the value as a (Unicode) string, with env vars expanded by os.path.expandvars().

as_str_seq(split=True)

Get the value as a sequence of strings. Equivalent to get(StrSeq(split=split)).

exists()

Determine whether the view has a setting in any source.

first()

Return a (value, source) pair for the first object found for this view. This amounts to the first element returned by resolve. If no values are available, a NotFoundError is raised.

flatten(redact=False)

Create a hierarchy of OrderedDicts containing the data from this view, recursively reifying all views to get their represented values.

If redact is set, then sensitive values are replaced with the string “REDACTED”.

get(template=<object object>)

Retrieve the value for this view according to the template.

The template against which the values are checked can be anything convertible to a Template using as_template. This means you can pass in a default integer or string value, for example, or a type to just check that something matches the type you expect.

May raise a ConfigValueError (or its subclass, ConfigTypeError) or a NotFoundError when the configuration doesn’t satisfy the template.

get_redactions()

Get the set of currently-redacted sub-key-paths at this view.

items()

Iterates over (key, subview) pairs contained in dictionaries from all sources at this view. If the object for this view in any source is not a dict, then a ConfigTypeError is raised.

keys()

Returns a list containing all the keys available as subviews of the current views. This enumerates all the keys in all dictionaries matching the current view, in contrast to view.get(dict).keys(), which gets all the keys for the first dict matching the view. If the object for this view in any source is not a dict, then a ConfigTypeError is raised. The keys are ordered according to how they appear in each source.

name = None

The name of the view, depicting the path taken through the configuration in Python-like syntax (e.g., foo['bar'][42]).

property redact

Whether the view contains sensitive information and should be redacted from output.

resolve()

The core (internal) data retrieval method. Generates (value, source) pairs for each source that contains a value for this view. May raise ConfigTypeError if a type error occurs while traversing a source.

root()

The RootView object from which this view is descended.

sequence()

Iterates over the subviews contained in lists from the first source at this view. If the object for this view in the first source is not a list or tuple, then a ConfigTypeError is raised.

set(value)

Override the value for this configuration view. The specified value is added as the highest-priority configuration data source.

set_args(namespace, dots=False)

Overlay parsed command-line arguments, generated by a library like argparse or optparse, onto this view’s value.

Parameters:

• namespace (dict or Namespace) – Dictionary or Namespace to overlay this config with. Supports nested Dictionaries and Namespaces.

• dots (bool) –

  If True, any properties on namespace that contain dots (.) will be broken down into child dictionaries. :Example:

  {‘foo.bar’: ‘car’} # Will be turned into {‘foo’: {‘bar’: ‘car’}}

set_redaction(path, flag)

Add or remove a redaction for a key path, which should be an iterable of keys.

values()

Iterates over all the subviews contained in dictionaries from all sources at this view. If the object for this view in any source is not a dict, then a ConfigTypeError is raised.

class confuse.core.Configuration(appname, modname=None, read=True, loader=<class 'confuse.yaml_util.Loader'>)

Bases: RootView

_add_default_source()

Add the package’s default configuration settings. This looks for a YAML file located inside the package for the module modname if it was given.

_add_user_source()

Add the configuration options from the YAML file in the user’s configuration directory (given by config_dir) if it exists.

config_dir()

Get the path to the user configuration directory. The directory is guaranteed to exist as a postcondition (one may be created if none exist).

If the application’s ...DIR environment variable is set, it is used as the configuration directory. Otherwise, platform-specific standard configuration locations are searched for a config.yaml file. If no configuration file is found, a fallback path is used.

dump(full=True, redact=False)

Dump the Configuration object to a YAML file.

The order of the keys is determined from the default configuration file. All keys not in the default configuration will be appended to the end of the file.

Parameters:

• full – Dump settings that don’t differ from the defaults as well

• redact – Remove sensitive information (views with the redact flag set) from the output

read(user=True, defaults=True)

Find and read the files for this configuration and set them as the sources for this configuration. To disable either discovered user configuration files or the in-package defaults, set user or defaults to False.

reload()

Reload all sources from the file system.

This only affects sources that come from files (i.e., YamlSource objects); other sources, such as dictionaries inserted with add or set, will remain unchanged.

set_env(prefix=None, sep='__')

Create a configuration overlay at the highest priority from environment variables.

After prefix matching and removal, environment variable names will be converted to lowercase for use as keys within the configuration. If there are nested keys, list-like dicts (ie, {0: ‘a’, 1: ‘b’}) will be converted into corresponding lists (ie, [‘a’, ‘b’]). The values of all environment variables will be parsed as YAML scalars using the self.loader Loader class to ensure type conversion is consistent with YAML file sources. Use the EnvSource class directly to load environment variables using non-default behavior and to enable full YAML parsing of values.

Parameters:

• prefix – The prefix to identify the environment variables to use. Defaults to uppercased self.appname followed by an underscore.

• sep – Separator within variable names to define nested keys.

set_file(filename, base_for_paths=False)

Parses the file as YAML and inserts it into the configuration sources with highest priority.

Parameters:

• filename – Filename of the YAML file to load.

• base_for_paths – Indicates whether the directory containing the YAML file will be used as the base directory for resolving relative path values stored in the YAML file. Otherwise, by default, the directory returned by config_dir() will be used as the base.

user_config_path()

Points to the location of the user configuration.

The file may not exist.

class confuse.core.LazyConfig(appname, modname=None)

Bases: Configuration

A Configuration at reads files on demand when it is first accessed. This is appropriate for using as a global config object at the module level.

add(value)

Set the default value for this configuration view. The specified value is added as the lowest-priority configuration data source.

clear()

Remove all sources from this configuration.

read(user=True, defaults=True)

Find and read the files for this configuration and set them as the sources for this configuration. To disable either discovered user configuration files or the in-package defaults, set user or defaults to False.

resolve()

The core (internal) data retrieval method. Generates (value, source) pairs for each source that contains a value for this view. May raise ConfigTypeError if a type error occurs while traversing a source.

set(value)

Override the value for this configuration view. The specified value is added as the highest-priority configuration data source.

class confuse.core.RootView(sources)

Bases: ConfigView

The base of a view hierarchy. This view keeps track of the sources that may be accessed by subviews.

add(obj)

Set the default value for this configuration view. The specified value is added as the lowest-priority configuration data source.

clear()

Remove all sources (and redactions) from this configuration.

get_redactions()

Get the set of currently-redacted sub-key-paths at this view.

resolve()

The core (internal) data retrieval method. Generates (value, source) pairs for each source that contains a value for this view. May raise ConfigTypeError if a type error occurs while traversing a source.

root()

The RootView object from which this view is descended.

set(value)

Override the value for this configuration view. The specified value is added as the highest-priority configuration data source.

set_redaction(path, flag)

Add or remove a redaction for a key path, which should be an iterable of keys.

class confuse.core.Subview(parent, key)

Bases: ConfigView

A subview accessed via a subscript of a parent view.

add(value)

Set the default value for this configuration view. The specified value is added as the lowest-priority configuration data source.

get_redactions()

Get the set of currently-redacted sub-key-paths at this view.

resolve()

The core (internal) data retrieval method. Generates (value, source) pairs for each source that contains a value for this view. May raise ConfigTypeError if a type error occurs while traversing a source.

root()

The RootView object from which this view is descended.

set(value)

Override the value for this configuration view. The specified value is added as the highest-priority configuration data source.

set_redaction(path, flag)

Add or remove a redaction for a key path, which should be an iterable of keys.

Exceptions

exception confuse.exceptions.ConfigError

Bases: Exception

Base class for exceptions raised when querying a configuration.

exception confuse.exceptions.ConfigReadError(name, reason=None)

Bases: ConfigError

A configuration source could not be read.

exception confuse.exceptions.ConfigTemplateError

Bases: ConfigError

Base class for exceptions raised because of an invalid template.

exception confuse.exceptions.ConfigTypeError

Bases: ConfigValueError

The value in the configuration did not match the expected type.

exception confuse.exceptions.ConfigValueError

Bases: ConfigError

The value in the configuration is illegal.

exception confuse.exceptions.NotFoundError

Bases: ConfigError

A requested value could not be found in the configuration trees.

Sources

class confuse.sources.ConfigSource(value, filename=None, default=False, base_for_paths=False)

Bases: dict

A dictionary augmented with metadata about the source of the configuration.

classmethod of(value)

Given either a dictionary or a ConfigSource object, return a ConfigSource object. This lets a function accept either type of object as an argument.

class confuse.sources.EnvSource(prefix, sep='__', lower=True, handle_lists=True, parse_yaml_docs=False, loader=<class 'confuse.yaml_util.Loader'>)

Bases: ConfigSource

A configuration data source loaded from environment variables.

classmethod _convert_dict_lists(obj)

Recursively search for dicts where all of the keys are integers from 0 to the length of the dict, and convert them to lists.

load()

Load configuration data from the environment.

class confuse.sources.YamlSource(filename=None, default=False, base_for_paths=False, optional=False, loader=<class 'confuse.yaml_util.Loader'>)

Bases: ConfigSource

A configuration data source that reads from a YAML file.

load()

Load YAML data from the source’s filename.

Templates

class confuse.templates.AttrDict

Bases: dict

A dict subclass that can be accessed via attributes (dot notation) for convenience.

class confuse.templates.Choice(choices, default=<object object>)

Bases: Template

A template that permits values from a sequence of choices.

Sequences, dictionaries and Enum types are supported, see __init__() for usage.

__init__(choices, default=<object object>)

Create a template that validates any of the values from the iterable choices.

If choices is a map, then the corresponding value is emitted. Otherwise, the value itself is emitted.

If choices is a Enum, then the enum entry with the value is emitted.

convert(value, view)

Ensure that the value is among the choices (and remap if the choices are a mapping).

class confuse.templates.Filename(default=<object object>, cwd=None, relative_to=None, in_app_dir=False, in_source_dir=False)

Bases: Template

A template that validates strings as filenames.

Filenames are returned as absolute, tilde-free paths.

Relative paths are relative to the template’s cwd argument when it is specified. Otherwise, if the paths come from a file, they will be relative to the configuration directory (see the config_dir method) by default or to the base directory of the config file if either the source has base_for_paths set to True or the template has in_source_dir set to True. Paths from sources without a file are relative to the current working directory. This helps attain the expected behavior when using command-line options.

__init__(default=<object object>, cwd=None, relative_to=None, in_app_dir=False, in_source_dir=False)

relative_to is the name of a sibling value that is being validated at the same time.

in_app_dir indicates whether the path should be resolved inside the application’s config directory (even when the setting does not come from a file).

in_source_dir indicates whether the path should be resolved relative to the directory containing the source file, if there is one, taking precedence over the application’s config directory.

value(view, template=None)

Get the value for a ConfigView.

May raise a NotFoundError if the value is missing (and the template requires it) or a ConfigValueError for invalid values.

class confuse.templates.Integer(default=<object object>)

Bases: Template

An integer configuration value template.

convert(value, view)

Check that the value is an integer. Floats are rounded.

class confuse.templates.MappingTemplate(mapping)

Bases: Template

A template that uses a dictionary to specify other types for the values for a set of keys and produce a validated AttrDict.

__init__(mapping)

Create a template according to a dict (mapping). The mapping’s values should themselves either be Types or convertible to Types.

value(view, template=None)

Get a dict with the same keys as the template and values validated according to the value types.

class confuse.templates.MappingValues(subtemplate)

Bases: Template

A template used to validate mappings of similar items, based on a given subtemplate applied to the values.

All keys in the mapping are considered valid, but values must pass validation by the subtemplate. Similar to the Sequence template but for mappings.

__init__(subtemplate)

Create a template for a mapping with variable keys and item values validated on a given subtemplate.

value(view, template=None)

Get a dict with the same keys as the view and the value of each item validated against the subtemplate.

class confuse.templates.Number(default=<object object>)

Bases: Template

A numeric type: either an integer or a floating-point number.

convert(value, view)

Check that the value is an int or a float.

class confuse.templates.OneOf(allowed, default=<object object>)

Bases: Template

A template that permits values complying to one of the given templates.

__init__(allowed, default=<object object>)

Create a template with a given default value.

If default is the sentinel REQUIRED (as it is by default), then an error will be raised when a value is missing. Otherwise, missing values will instead return default.

convert(value, view)

Ensure that the value follows at least one template.

value(view, template)

Get the value for a ConfigView.

May raise a NotFoundError if the value is missing (and the template requires it) or a ConfigValueError for invalid values.

class confuse.templates.Optional(subtemplate, default=None, allow_missing=True)

Bases: Template

A template that makes a subtemplate optional.

If the value is present and not null, it must validate against the subtemplate. However, if the value is null or missing, the template will still validate, returning a default value. If allow_missing is False, the template will not allow missing values while still permitting null.

__init__(subtemplate, default=None, allow_missing=True)

Create a template with a given default value.

If default is the sentinel REQUIRED (as it is by default), then an error will be raised when a value is missing. Otherwise, missing values will instead return default.

value(view, template=None)

Get the value for a ConfigView.

May raise a NotFoundError if the value is missing (and the template requires it) or a ConfigValueError for invalid values.

class confuse.templates.Pairs(default_value=None)

Bases: StrSeq

A template for ordered key-value pairs.

This can either be given with the same syntax as for StrSeq (i.e. without values), or as a list of strings and/or single-element mappings such as:

- key: value
- [key, value]
- key

The result is a list of two-element tuples. If no value is provided, the default_value will be returned as the second element.

__init__(default_value=None)

Create a new template.

default is the dictionary value returned for items that are not a mapping, but a single string.

class confuse.templates.Path(default=<object object>, cwd=None, relative_to=None, in_app_dir=False, in_source_dir=False)

Bases: Filename

A template that validates strings as pathlib.Path objects.

Filenames are parsed equivalent to the Filename template and then converted to pathlib.Path objects.

value(view, template=None)

Get the value for a ConfigView.

May raise a NotFoundError if the value is missing (and the template requires it) or a ConfigValueError for invalid values.

confuse.templates.REQUIRED = <object object>

A sentinel indicating that there is no default value and an exception should be raised when the value is missing.

class confuse.templates.Sequence(subtemplate)

Bases: Template

A template used to validate lists of similar items, based on a given subtemplate.

__init__(subtemplate)

Create a template for a list with items validated on a given subtemplate.

value(view, template=None)

Get a list of items validated against the template.

class confuse.templates.StrSeq(split=True, default=<object object>)

Bases: Template

A template for values that are lists of strings.

Validates both actual YAML string lists and single strings. Strings can optionally be split on whitespace.

__init__(split=True, default=<object object>)

Create a new template.

split indicates whether, when the underlying value is a single string, it should be split on whitespace. Otherwise, the resulting value is a list containing a single string.

convert(value, view)

Convert the YAML-deserialized value to a value of the desired type.

Subclasses should override this to provide useful conversions. May raise a ConfigValueError when the configuration is wrong.

class confuse.templates.String(default=<object object>, pattern=None, expand_vars=False)

Bases: Template

A string configuration value template.

__init__(default=<object object>, pattern=None, expand_vars=False)

Create a template with the added optional pattern argument, a regular expression string that the value should match.

convert(value, view)

Check that the value is a string and matches the pattern.

class confuse.templates.Template(default=<object object>)

Bases: object

A value template for configuration fields.

The template works like a type and instructs Confuse about how to interpret a deserialized YAML value. This includes type conversions, providing a default value, and validating for errors. For example, a filepath type might expand tildes and check that the file exists.

__init__(default=<object object>)

Create a template with a given default value.

If default is the sentinel REQUIRED (as it is by default), then an error will be raised when a value is missing. Otherwise, missing values will instead return default.

convert(value, view)

Convert the YAML-deserialized value to a value of the desired type.

Subclasses should override this to provide useful conversions. May raise a ConfigValueError when the configuration is wrong.

fail(message, view, type_error=False)

Raise an exception indicating that a value cannot be accepted.

type_error indicates whether the error is due to a type mismatch rather than a malformed value. In this case, a more specific exception is raised.

get_default_value(key_name='default')

Get the default value to return when the value is missing.

May raise a NotFoundError if the value is required.

value(view, template=None)

Get the value for a ConfigView.

May raise a NotFoundError if the value is missing (and the template requires it) or a ConfigValueError for invalid values.

class confuse.templates.TypeTemplate(typ, default=<object object>)

Bases: Template

A simple template that checks that a value is an instance of a desired Python type.

__init__(typ, default=<object object>)

Create a template that checks that the value is an instance of typ.

convert(value, view)

Convert the YAML-deserialized value to a value of the desired type.

Subclasses should override this to provide useful conversions. May raise a ConfigValueError when the configuration is wrong.

confuse.templates.as_template(value)

Convert a simple “shorthand” Python value to a Template.

Utility

confuse.util.build_dict(obj, sep='', keep_none=False)

Recursively builds a dictionary from an argparse.Namespace, optparse.Values, or dict object.

Additionally, if sep is a non-empty string, the keys will be split by sep and expanded into a nested dict. Keys with a None value are dropped by default to avoid unsetting options but can be kept by setting keep_none to True.

Parameters:

• obj (argparse.Namespace or optparse.Values or dict or *) – Namespace, Values, or dict to iterate over. Other values will simply be returned.

• sep (str) – Separator to use for splitting properties/keys of obj for expansion into nested dictionaries.

• keep_none (bool) – Whether to keep keys whose value is None.

Returns:

A new dictionary or the value passed if obj was not a dict, Namespace, or Values.

Return type:

dict or *

confuse.util.config_dirs()

Return a platform-specific list of candidates for user configuration directories on the system.

The candidates are in order of priority, from highest to lowest. The last element is the “fallback” location to be used when no higher-priority config file exists.

confuse.util.find_package_path(name)

Returns the path to the package containing the named module or None if the path could not be identified (e.g., if name == "__main__").

confuse.util.iter_first(sequence)

Get the first element from an iterable or raise a ValueError if the iterator generates no values.

confuse.util.namespace_to_dict(obj)

If obj is argparse.Namespace or optparse.Values we’ll return

a dict representation of it, else return the original object.

Redefine this method if using other parsers.

Parameters:

obj –

Returns:

Return type:

dict or *

confuse.util.xdg_config_dirs()

Returns a list of paths taken from the XDG_CONFIG_DIRS and XDG_CONFIG_HOME environment varibables if they exist

YAML Utility

class confuse.yaml_util.Dumper(stream, default_style=None, default_flow_style=False, canonical=None, indent=None, width=None, allow_unicode=None, line_break=None, encoding=None, explicit_start=None, explicit_end=None, version=None, tags=None, sort_keys=True)

Bases: SafeDumper

A PyYAML Dumper that represents OrderedDicts as ordinary mappings (in order, of course).

represent_bool(data)

Represent bool as ‘yes’ or ‘no’ instead of ‘true’ or ‘false’.

represent_list(data)

If a list has less than 4 items, represent it in inline style (i.e. comma separated, within square brackets).

represent_none(data)

Represent a None value with nothing instead of ‘none’.

class confuse.yaml_util.Loader(stream)

Bases: SafeLoader

A customized YAML loader. This loader deviates from the official YAML spec in a few convenient ways:

• All strings as are Unicode objects.

• All maps are OrderedDicts.

• Strings can begin with % without quotation.

static add_constructors(loader)

Modify a PyYAML Loader class to add extra constructors for strings and maps. Call this method on a custom Loader class to make it behave like Confuse’s own Loader

confuse.yaml_util.load_yaml(filename, loader=<class 'confuse.yaml_util.Loader'>)

Read a YAML document from a file. If the file cannot be read or parsed, a ConfigReadError is raised. loader is the PyYAML Loader class to use to parse the YAML. By default, this is Confuse’s own Loader class, which is like SafeLoader with extra constructors.

confuse.yaml_util.load_yaml_string(yaml_string, name, loader=<class 'confuse.yaml_util.Loader'>)

Read a YAML document from a string. If the string cannot be parsed, a ConfigReadError is raised. yaml_string is a string to be parsed as a YAML document. name is the name to use in error messages. loader is the PyYAML Loader class to use to parse the YAML. By default, this is Confuse’s own Loader class, which is like SafeLoader with extra constructors.

confuse.yaml_util.parse_as_scalar(value, loader=<class 'confuse.yaml_util.Loader'>)

Parse a value as if it were a YAML scalar to perform type conversion that is consistent with YAML documents. value should be a string. Non-string inputs or strings that raise YAML errors will be returned unchanged. Loader is the PyYAML Loader class to use for parsing, defaulting to Confuse’s own Loader class.

Examples with the default Loader:

• ‘1’ will return 1 as an integer

• ‘1.0’ will return 1 as a float

• ‘true’ will return True

• The empty string ‘’ will return None

confuse.yaml_util.restore_yaml_comments(data, default_data)

Scan default_data for comments (we include empty lines in our definition of comments) and place them before the same keys in data. Only works with comments that are on one or more own lines, i.e. not next to a yaml mapping.