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[source]

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]).

classmethod _build_namespace_dict(obj, dots=False)[source]

Recursively replaces all argparse.Namespace and optparse.Values with dicts and drops any keys with None values.

Additionally, if dots is True, will expand any dot delimited keys.

Parameters:
  • obj (argparse.Namespace or optparse.Values or dict or *) – Namespace, Values, or dict to iterate over. Other values will simply be returned.
  • dots – If True, any properties on obj that contain dots (.) will be broken down into child dictionaries.
Returns:

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

Return type:

dict or *

add(value)[source]

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

all_contents()[source]

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)[source]

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

as_filename()[source]

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

as_number()[source]

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

as_pairs(default_value=None)[source]

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

as_path()[source]

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

as_str()[source]

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

as_str_expanded()[source]

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

as_str_seq(split=True)[source]

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

exists()[source]

Determine whether the view has a setting in any source.

first()[source]

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)[source]

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>)[source]

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()[source]

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

items()[source]

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()[source]

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]).

redact

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

resolve()[source]

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()[source]

The RootView object from which this view is descended.

set(value)[source]

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

set_args(namespace, dots=False)[source]

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)[source]

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

values()[source]

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'>)[source]

Bases: confuse.core.RootView

_add_default_source()[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()[source]

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

config_dir()[source]

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)[source]

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)[source]

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.

set_file(filename)[source]

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

user_config_path()[source]

Points to the location of the user configuration.

The file may not exist.

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

Bases: confuse.core.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)[source]

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

clear()[source]

Remove all sources from this configuration.

read(user=True, defaults=True)[source]

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()[source]

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)[source]

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

class confuse.core.RootView(sources)[source]

Bases: confuse.core.ConfigView

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

add(obj)[source]

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

clear()[source]

Remove all sources (and redactions) from this configuration.

get_redactions()[source]

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

resolve()[source]

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()[source]

The RootView object from which this view is descended.

set(value)[source]

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

set_redaction(path, flag)[source]

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

class confuse.core.Subview(parent, key)[source]

Bases: confuse.core.ConfigView

A subview accessed via a subscript of a parent view.

add(value)[source]

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

get_redactions()[source]

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

resolve()[source]

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()[source]

The RootView object from which this view is descended.

set(value)[source]

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

set_redaction(path, flag)[source]

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

Exceptions

exception confuse.exceptions.ConfigError[source]

Bases: exceptions.Exception

Base class for exceptions raised when querying a configuration.

exception confuse.exceptions.NotFoundError[source]

Bases: confuse.exceptions.ConfigError

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

exception confuse.exceptions.ConfigValueError[source]

Bases: confuse.exceptions.ConfigError

The value in the configuration is illegal.

exception confuse.exceptions.ConfigTypeError[source]

Bases: confuse.exceptions.ConfigValueError

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

exception confuse.exceptions.ConfigTemplateError[source]

Bases: confuse.exceptions.ConfigError

Base class for exceptions raised because of an invalid template.

exception confuse.exceptions.ConfigReadError(filename, reason=None)[source]

Bases: confuse.exceptions.ConfigError

A configuration file could not be read.

Sources

class confuse.sources.ConfigSource(value, filename=None, default=False)[source]

Bases: dict

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

classmethod of(value)[source]

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.YamlSource(filename=None, default=False, optional=False, loader=<class 'confuse.yaml_util.Loader'>)[source]

Bases: confuse.sources.ConfigSource

A configuration data source that reads from a YAML file.

load()[source]

Load YAML data from the source’s filename.

Templates

class confuse.templates.AttrDict[source]

Bases: dict

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

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

Bases: confuse.templates.Template

A template that permits values from a sequence of choices.

convert(value, view)[source]

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)[source]

Bases: confuse.templates.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, then the configuration directory (see the config_dir method) if they come from a file. Otherwise, they are relative to the current working directory. This helps attain the expected behavior when using command-line options.

value(view, template=None)[source]

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>)[source]

Bases: confuse.templates.Template

An integer configuration value template.

convert(value, view)[source]

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

class confuse.templates.MappingTemplate(mapping)[source]

Bases: confuse.templates.Template

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

value(view, template=None)[source]

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

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

Bases: confuse.templates.Template

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

convert(value, view)[source]

Check that the value is an int or a float.

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

Bases: confuse.templates.Template

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

convert(value, view)[source]

Ensure that the value follows at least one template.

value(view, template)[source]

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)[source]

Bases: confuse.templates.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.

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

Bases: confuse.templates.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.

For Python 2 it returns the original path as returned by the Filename template.

value(view, template=None)[source]

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)[source]

Bases: confuse.templates.Template

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

value(view, template=None)[source]

Get a list of items validated against the template.

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

Bases: confuse.templates.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.

convert(value, view)[source]

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)[source]

Bases: confuse.templates.Template

A string configuration value template.

convert(value, view)[source]

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

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

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.

convert(value, view)[source]

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)[source]

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.

value(view, template=None)[source]

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>)[source]

Bases: confuse.templates.Template

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

convert(value, view)[source]

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)[source]

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

Utility

confuse.util.config_dirs()[source]

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)[source]

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)[source]

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

confuse.util.namespace_to_dict(obj)[source]
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()[source]

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)[source]

Bases: yaml.dumper.SafeDumper

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

represent_bool(data)[source]

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

represent_list(data)[source]

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

represent_none(data)[source]

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

class confuse.yaml_util.Loader(stream)[source]

Bases: yaml.loader.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)[source]

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'>)[source]

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.restore_yaml_comments(data, default_data)[source]

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.