Library¶
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.
BoundConfig
(config, component_name, options)¶ Wrap a config and binds it to a set of options.
This restricts the config to only return keys from the option set. Further, it uses the option set to determine the default and the parser for that option.
This is useful for binding configuration to a component’s specified options.
-
get_namespace
()¶ Retrieve the complete namespace for this config object.
Returns: namespace as a list of strings
-
-
class
everett.manager.
ConfigDictEnv
(cfg)¶ 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 aConfigManager
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, namespace=None)¶ Retrieve value for key.
-
-
class
everett.manager.
ConfigEnvFileEnv
(possible_paths)¶ 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, namespace=None)¶ Retrieve value for key.
-
-
class
everett.manager.
ConfigManager
(environments, doc='', with_override=True)¶ Manage multiple configuration environment layers.
-
classmethod
basic_config
(env_file='.env')¶ Return a basic ConfigManager.
This sets up a ConfigManager that will look for configuration in this order:
- environment
- 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 Returns: a everett.manager.ConfigManager
-
classmethod
from_dict
(dict_config)¶ 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.
-
classmethod
-
class
everett.manager.
ConfigManagerBase
¶ Base configuration manager class.
-
get_namespace
()¶ Retrieve the complete namespace for this config object.
Returns: namespace as a list of strings
-
with_namespace
(namespace)¶ Apply namespace to this configuration.
-
with_options
(component)¶ Apply options component options to this configuration.
-
-
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, namespace=None)¶ Retrieve value for key.
-
-
class
everett.manager.
ConfigObjEnv
(obj, force_lower=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, namespace=None)¶ Retrieve value for key.
-
-
class
everett.manager.
ConfigOverride
(**cfg)¶ Handle contexts and decoration for overriding config in testing.
-
decorate
(fun)¶ Decorate a function for overriding configuration.
-
pop_config
()¶ Pop a config layer off.
Raises: IndexError – If there are no layers to pop off
-
push_config
()¶ Push
self._cfg
as a config layer onto the stack.
-
-
class
everett.manager.
ConfigOverrideEnv
¶ Override configuration layer for testing.
-
get
(key, namespace=None)¶ Retrieve value for key.
-
-
class
everett.manager.
ListOf
(parser, delimiter=', ')¶ Parse a comma-separated list of things.
>>> 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.
NamespacedConfig
(config, namespace)¶ Apply a namespace to a config.
This restricts keys in a config to those belonging to the specified namespace.
-
get_namespace
()¶ Retrieve the complete namespace for this config object.
Returns: namespace as a list of strings
-
-
everett.manager.
config_override
(**cfg)¶ 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.
generate_uppercase_key
(key, namespace=None)¶ Given a key and a namespace, generates a final uppercase key.
-
everett.manager.
get_key_from_envs
(envs, key)¶ Return the value of a key from the given dict respecting namespaces.
Data can also be a list of data dicts.
-
everett.manager.
get_parser
(parser)¶ Return a parsing function for a given parser.
-
everett.manager.
listify
(thing)¶ Convert thing to a list.
If thing is a string, then returns a list of thing. Otherwise returns thing.
Parameters: thing – string or list of things Returns: list
-
everett.manager.
parse_bool
(val)¶ Parse a bool value.
Handles a series of values, but you should probably standardize on “true” and “false”.
>>> parse_bool('y') True >>> parse_bool('FALSE') False
-
everett.manager.
parse_class
(val)¶ Parse a string, imports the module and returns the class.
>>> parse_class('hashlib.md5') <built-in function openssl_md5>
-
everett.manager.
parse_env_file
(envfile)¶ Parse the content of an iterable of lines as
.env
.Return a dict of config variables.
>>> parse_env_file(['DUDE=Abides']) {'DUDE': 'Abides'}
-
everett.manager.
qualname
(thing)¶ Return the dot name for a given thing.
>>> import everett.manager >>> qualname(str) 'str' >>> qualname(everett.manager.parse_class) 'everett.manager.parse_class' >>> qualname(everett.manager) 'everett.manager'
everett.component¶
Module holding infrastructure for building components.
-
class
everett.component.
ConfigOptions
¶ A collection of config options.
-
add_option
(key, default=NO_VALUE, alternate_keys=NO_VALUE, doc='', parser=<class 'str'>, **meta)¶ Add an option to the group.
Parameters: - key – the key to look up
- default – the default value (if any); must be a string that is parseable by the specified parser
- 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 - doc – documentation for this config option
- parser – the parser for converting this value to a Python object
- meta – catch-all for other key/value pairs you want to association with this option
-
update
(new_options)¶ Update this ConfigOptions using data from another.
-
-
class
everett.component.
Option
(key, default=NO_VALUE, alternate_keys=NO_VALUE, doc='', parser=<class 'str'>, meta=None)¶ A single option comprised of a key and settings.
-
class
everett.component.
RequiredConfigMixin
¶ Mixin for component classes that have required configuration.
As with all mixins, make sure this is earlier in the class list.
Example:
from everett.component import RequiredConfigMixin, ConfigOptions class SomeComponent(RequiredConfigMixin): required_config = ConfigOptions() required_config.add_option('foo') def __init__(self, config): self.config = config.with_options(self)
-
classmethod
get_required_config
()¶ Roll up configuration options for this class and parent classes.
This handles subclasses overriding options in parent classes.
Returns: final ConfigOptions
representing all configuration for this class
-
get_runtime_config
(namespace=None)¶ Roll up the runtime config for this class and all children.
Implement this to call
.get_runtime_config()
on child components or to adjust how it works.For example, if you created a component that has a child component, you could do something like this:
class MyComponent(RequiredConfigMixin): .... def __init__(self, config): self.config = config.with_options(self) self.child = OtherComponent(config.with_namespace('source')) def get_runtime_config(self, namespace=None): for item in super(MyComponent, self).get_runtime_config(namespace): yield item for item in self.child.get_runtime_config(['source']): yield item
Calling this function can give you the complete runtime configuration for a component tree. This is helpful for doing things like printing the configuration being used including default values.
Note
If this instance has a
.config
attribute and it is aeverett.component.BoundConfig
, then this will try to compute the runtime config.Otherwise, it’ll yield nothing.
Parameters: namespace (list) – list of namespace parts or None Returns: list of (namespace, key, option)
-
classmethod