API

This is the API of functions and classes in Everett.

Configuration things:

Utility functions:

Testing utility functions:

Configuration environments:

Errors:

Parsers:

everett

Everett is a Python library for configuration.

everett.NO_VALUE = NO_VALUE

Singleton indicating a non-value.

exception everett.ConfigurationError

Configuration error base class.

exception everett.DetailedConfigurationError(msg: str, namespace: Optional[List[str]], key: str, parser: Callable)

Base class for configuration errors that have a msg, namespace, key, and parser.

exception everett.InvalidKeyError

Error that indicates the key is not valid for this component.

exception everett.ConfigurationMissingError(msg: str, namespace: Optional[List[str]], key: str, parser: Callable)

Error that indicates that required configuration is missing.

everett.manager

Contains configuration infrastructure.

This module contains the configuration classes and functions for deriving configuration values from specified sources in the order specified.

class everett.manager.ConfigDictEnv(cfg: Dict[KT, VT])

Source for pulling configuration out of a dict.

This is handy for testing. You might also use it if you wanted to move all your defaults values into one centralized place.

Keys are prefixed by namespaces and the whole thing is uppercased.

For example, namespace “bar” for key “foo” becomes BAR_FOO in the dict.

For example:

from everett.manager import ConfigDictEnv, ConfigManager

config = ConfigManager([
    ConfigDictEnv({
        "FOO_BAR": "someval",
        "BAT": "1",
    })
])

Keys are not case sensitive. This also works:

from everett.manager import ConfigDictEnv, ConfigManager

config = ConfigManager([
    ConfigDictEnv({
        "foo_bar": "someval",
        "bat": "1",
    })
])

print config("foo_bar")
print config("FOO_BAR")
print config.with_namespace("foo")("bar")

Also, ConfigManager has a convenience classmethod for creating a ConfigManager with just a dict environment:

from everett.manager import ConfigManager

config = ConfigManager.from_dict({
    "FOO_BAR": "bat"
})

Changed in version 0.3: Keys are no longer case-sensitive.

get(key: str, namespace: Optional[List[str]] = None) → Union[str, everett.NoValue]

Retrieve value for key.

class everett.manager.ConfigEnvFileEnv(possible_paths: Union[str, List[str]])

Source for pulling configuration out of .env files.

This source lets you specify configuration in an .env file. This is useful for local development when in production you use values in environment variables.

Keys are prefixed by namespaces and the whole thing is uppercased.

For example, key “foo” will be FOO in the file.

For example, namespace “bar” for key “foo” becomes BAR_FOO in the file.

Key and namespace can consist of alphanumeric characters and _.

To use, instantiate and toss in the source list:

from everett.manager import ConfigEnvFileEnv, ConfigManager

config = ConfigManager([
    ConfigEnvFileEnv('.env')
])

For multiple paths:

from everett.manager import ConfigEnvFileEnv, ConfigManager

config = ConfigManager([
    ConfigEnvFileEnv([
        '.env',
        'config/prod.env'
    ])
])

Here’s an example .env file:

DEBUG=true

# secrets
SECRET_KEY=ou812

# database setup
DB_HOST=localhost
DB_PORT=5432
get(key: str, namespace: Optional[List[str]] = None) → Union[str, everett.NoValue]

Retrieve value for key.

class everett.manager.ConfigManager(environments: List[Any], doc: str = '', msg_builder: Callable = <function build_msg>, with_override: bool = True)

Manage multiple configuration environment layers.

Instantiate a ConfigManager.

Parameters:
  • environments – list of configuration sources to look through in the order they should be looked through
  • doc

    help text printed to users when they encounter configuration errors

    New in version 0.6.

  • msg_builder

    function that takes arguments and builds an exception message intended to be printed or conveyed to the user

    For example:

    def build_msg(namespace, key, parser, msg="", option_doc="", config_doc=""):
        full_key = namespace or []
        full_key = "_".join(full_key + [key]).upper()
    
        return (
            f"{full_key} requires a value parseable by {qualname(parser)}\n"
            + option_doc + "\n"
            + config_doc + "\n"
        )
    
  • with_override – whether or not to insert the special override environment used for testing as the first environment in the list of sources
classmethod basic_config(env_file: str = '.env', doc: str = '') → everett.manager.ConfigManager

Return a basic ConfigManager.

This sets up a ConfigManager that will look for configuration in this order:

  1. environment
  2. specified env_file defaulting to .env

This is for a fast one-line opinionated setup.

Example:

from everett.manager import ConfigManager

config = ConfigManager.basic_config()

This is shorthand for:

config = ConfigManager(
    environments=[
        ConfigOSEnv(),
        ConfigEnvFileEnv(['.env'])
    ]
)
Parameters:
  • env_file – the name of the env file to use
  • doc – help text printed to users when they encounter configuration errors
Returns:

a everett.manager.ConfigManager

classmethod from_dict(dict_config: Dict[KT, VT]) → everett.manager.ConfigManager

Create a ConfigManager with specified configuration as a Python dict.

This is shorthand for:

config = ConfigManager([ConfigDictEnv(dict_config)])

This is handy for writing tests for the app you’re using Everett in.

Parameters:dict_config – Python dict holding the configuration for this manager
Returns:ConfigManager with specified configuration

New in version 0.3.

get_bound_component() → Any

Retrieve the bound component for this config object.

Returns:component or None
get_namespace() → List[str]

Retrieve the complete namespace for this config object.

Returns:namespace as a list of strings
with_namespace(namespace: Union[List[str], str]) → everett.manager.ConfigManager

Apply a namespace to this configuration.

Namespaces accumulate as you add them.

Parameters:namepace – namespace as a string or list of strings
Returns:a clone of the ConfigManager instance with the namespace applied
with_options(component: Any) → everett.manager.ConfigManager

Apply options component options to this configuration.

Parameters:component – the instance or class with a Config to bind this ConfigManager to
Returns:a clone of the ConfigManager instance bound to specified component
class everett.manager.ConfigOSEnv

Source for pulling configuration out of the environment.

This source lets you specify configuration in the environment. This is useful for infrastructure related configuration like usernames and ports and secret configuration like passwords.

Keys are prefixed by namespaces and the whole thing is uppercased.

For example, key “foo” will be FOO in the environment.

For example, namespace “bar” for key “foo” becomes BAR_FOO in the environment.

Key and namespace can consist of alphanumeric characters and _.

Note

Unlike other config environments, this one is case sensitive in that keys defined in the environment must be all uppercase.

For example, these are good:

FOO=bar
FOO_BAR=bar
FOO_BAR1=bar

This is bad:

foo=bar

To use, instantiate and toss in the source list:

from everett.manager import ConfigOSEnv, ConfigManager

config = ConfigManager([
    ConfigOSEnv()
])
get(key: str, namespace: Optional[List[str]] = None) → Union[str, everett.NoValue]

Retrieve value for key.

class everett.manager.ConfigObjEnv(obj: Any, force_lower: bool = True)

Source for pulling configuration values out of a Python object.

This is handy for a few weird situations. For example, you can use this to “bridge” Everett configuration with command line arguments. The argparse Namespace works fine here.

Namespace (the Everett one–not the argparse one) is prefixed. So key “foo” in namespace “bar” is “foo_bar”.

For example:

import argparse

from everett.manager import ConfigObjEnv, ConfigManager

parser = argparse.ArgumentParser()
parser.add_argument(
    "--debug", help="to debug or not to debug"
)
parsed_vals = parser.parse_known_args()[0]

config = ConfigManager([
    ConfigObjEnv(parsed_vals)
])

print config("debug", parser=bool)

Keys are not case-sensitive–everything is converted to lowercase before pulling it from the object.

Note

ConfigObjEnv has nothing to do with the library configobj.

New in version 0.6.

get(key: str, namespace: Optional[List[str]] = None) → Union[str, everett.NoValue]

Retrieve value for key.

class everett.manager.ListOf(parser: Callable, delimiter: str = ', ')

Parse a comma-separated list of things.

>>> from everett.manager import ListOf
>>> ListOf(str)('')
[]
>>> ListOf(str)('a,b,c,d')
['a', 'b', 'c', 'd']
>>> ListOf(int)('1,2,3,4')
[1, 2, 3, 4]

Note: This doesn’t handle quotes or backslashes or any complicated string parsing.

For example:

>>> ListOf(str)('"a,b",c,d')
['"a', 'b"', 'c', 'd']
class everett.manager.Option(default: Union[str, everett.NoValue] = NO_VALUE, alternate_keys: Optional[List[str]] = None, doc: str = '', parser: Callable = <class 'str'>, meta: Any = None)

Settings for a single configuration option.

Use this when creating Everett configuration components.

Example:

from everett.manager import Option

class MyService:
    # Note: The Config class has to be called "Config".
    class Config:
        host = Option(default="localhost")
        port = Option(default="8000", parser=int)
Parameters:
  • default – the default value (if any); this must be a string that is parseable by the specified parser; if no default is provided, this will raise an error or return everett.NO_VALUE depending on the value of raise_error
  • alternate_keys

    the list of alternate keys to look up; supports a root: key prefix which will cause this to look at the configuration root rather than the current namespace

    New in version 0.3.

  • doc

    documentation for this config option

    New in version 0.6.

  • parser – the parser for converting this value to a Python object
  • meta – any meta information that’s tied to this option; useful for noting which options are related in some way or which are secrets that shouldn’t be logged
everett.manager.config_override(**cfg) → everett.manager.ConfigOverride

Allow you to override config for writing tests.

This can be used as a class decorator:

@config_override(FOO="bar", BAZ="bat")
class FooTestClass(object):
    ...

This can be used as a function decorator:

@config_override(FOO="bar")
def test_foo():
    ...

This can also be used as a context manager:

def test_foo():
    with config_override(FOO="bar"):
        ...
everett.manager.get_config_for_class(cls: Type[CT_co]) → Dict[str, Tuple[everett.manager.Option, Type[CT_co]]]

Roll up configuration options for this class and parent classes.

This handles subclasses overriding configuration options in parent classes.

Parameters:cls – the component class to return configuration options for
Returns:final dict of configuration options for this class in key -> (option, cls) form
everett.manager.get_runtime_config(config: everett.manager.ConfigManager, component: Any, traverse: Callable = <function traverse_tree>) → List[Tuple[List[str], str, Any, everett.manager.Option]]

Returns configuration specification and values for a component tree

For example, if you had a tree of components instantiated, you could traverse the tree and log the configuration:

from everett.manager import (
    ConfigManager,
    generate_uppercase_key,
    get_runtime_config,
    Option,
    parse_class,
)

class App:
    class Config:
        debug = Option(default="False", parser=bool)
        reader = Option(parser=parse_class)
        writer = Option(parser=parse_class)

    def __init__(self, config):
        self.config = config.with_options(self)

        # App has a reader and a writer each of which has configuration
        # options
        self.reader = self.config("reader")(config.with_namespace("reader"))
        self.writer = self.config("writer")(config.with_namespace("writer"))

class Reader:
    class Config:
        input_file = Option()

    def __init__(self, config):
        self.config = config.with_options(self)

class Writer:
    class Config:
        output_file = Option()

    def __init__(self, config):
        self.config = config.with_options(self)

cm = ConfigManager.from_dict(
    {
        # This specifies which reader component to use. Because we
        # specified this one, we need to define a READER_INPUT_FILE
        # value.
        "READER": "__main__.Reader",
        "READER_INPUT_FILE": "input.txt",

        # Same thing for the writer component.
        "WRITER": "__main__.Writer",
        "WRITER_OUTPUT_FILE": "output.txt",
    }
)

my_app = App(cm)

# This traverses the component tree starting with my_app and then
# traversing .reader and .writer attributes.
for namespace, key, value, option in get_runtime_config(cm, my_app):
    full_key = generate_uppercase_key(key, namespace)
    print(f"{full_key.upper()}={value or ''}")

# This should print out:
# DEBUG=False
# READER=__main__.Reader
# READER_INPUT_FILE=input.txt
# WRITER=__main__.Writer
# WRITER_OUTPUT_FILE=output.txt
Parameters:
  • config – a configuration manager instance
  • component – a component or tree of components
  • traverse – the function for traversing the component tree; see everett.manager.traverse_tree() for signature
Returns:

a list of (namespace, key, value, option) tuples

everett.manager.parse_bool(val: str) → bool

Parse a bool value.

Handles a series of values, but you should probably standardize on “true” and “false”.

>>> from everett.manager import parse_bool
>>> parse_bool("y")
True
>>> parse_bool("FALSE")
False
everett.manager.parse_class(val: str) → Any

Parse a string, imports the module and returns the class.

>>> from everett.manager import parse_class
>>> parse_class("everett.manager.Option")
<class 'everett.manager.Option'>
everett.manager.parse_env_file(envfile: Iterable[str]) → Dict[KT, VT]

Parse the content of an iterable of lines as .env.

Return a dict of config variables.

>>> from everett.manager import parse_env_file
>>> parse_env_file(["DUDE=Abides"])
{'DUDE': 'Abides'}

everett.ext.inifile

everett.ext.yamlfile