Etcaetera helps you loading your application configuration from multiple sources in a simple way. It exposes a single Config object which you add prioritized sources adapters to (env, files, cmdline, modules...).
Once you call load method over it: your settings are loaded from your adapters in order, all your configuration is stored in the Config object.
You’re done.
Managing a large application configuration sources can be a pain in the neck. Command line, files, system environment, modules, a lot of mixed sources can provide you with the settings you seek.
They are all accessed in different ways, and establishing a merging strategy of these differents sources can sometimes look like impossible. Etcaetera provides you a simple and unified way to handle all the complexity in a single place.
$ pip install etcaetera
$ git clone git@github.com:oleiade/etcaetera
$ cd etcaetera
$ python setup.py install
A real world example is worth a thousand words
>>> from etcaetera.config import Config
>>> from etcaetera.adapters import Defaults, Module, Overrides, Env, File
# Let's create a new configuration object
>>> config = Config()
# And create a bunch of adapters
>>> env_adapter = Env("MY_FIRST_SETTING", "MY_SECOND_SETTING")
>>> python_file_adapter = File('/etc/my/python/settings.py')
>>> json_file_adapter = File('/etc/my_json_settings.json')
>>> module_adapter = Module(os)
>>> overrides = Overrides({"MY_FIRST_SETTING": "my forced value"})
# Let's register them
>>> config.register(env_adapter, python_file_adapter, json_file_adapter, module_adapter, overrides)
# Load configuration
>>> config.load()
# And that's it
>>> print config
{
"MY_FIRST_SETTING": "my forced value",
"MY_SECOND_SETTING": "my second value",
"FIRST_YAML_SETTING": "first yaml setting value found in yaml settings",
"FIRST_JSON_SETTING": "first json setting value found in json settings",
...
}
The config object is the central place for your whole application settings. It loads your adapters in the order you’ve registered them, and updates itself using it’s data. Furthermore you can attach sub config objects to it, in order to keep a clean configuration hierarchy.
Please note that Defaults adapter will always be loaded first, and Overrides will always be loaded last.
>>> from etcaetera.config import Config
>>> from etcaetera.adapters import Defaults, Module, Overrides, Env, File
# Let's create a new configuration object
>>> config = Config()
# And create a bunch of adapters
>>> env_adapter = Env("MY_FIRST_SETTING", "MY_SECOND_SETTING")
>>> python_file_adapter = File('/etc/my/python/settings.py')
>>> json_file_adapter = File('/etc/my_json_settings.json')
>>> module_adapter = Module(os)
>>> overrides = Overrides({"MY_FIRST_SETTING": "my forced value"})
# Let's register them
>>> config.register(env_adapter, python_file_adapter, json_file_adapter, module_adapter, overrides)
# Load configuration
>>> config.load()
# And that's it
>>> print config
{
"MY_FIRST_SETTING": "my forced value",
"MY_SECOND_SETTING": "my second value",
"FIRST_YAML_SETTING": "first yaml setting value found in yaml settings",
"FIRST_JSON_SETTING": "first json setting value found in json settings",
...
}
# If you need a certain hierarchy for your configuration
# Config objects supports sub configs. Here's an example of
# how to add an "aws" subconfig
>>> aws_config = Config() # Create a config obj
>>> aws_env = Env("AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY")
>>> aws_config.register(aws_env) # Register an env adapter on to it
>>> config.add_subconfig('aws', aws_config)
>>> config.aws
{
"AWS_ACCESS_KEY_ID": "128u09ijod019jhd182o1290d81",
"AWS_SECRET_ACCESS_KEY": "qoiejdn0182hern1d098uj12podij1029udaiwjJBIU09u0oimJHKI"
}
Adapters are the interfaces with configuration sources. They load settings from their custom source type, and they expose them as a normalized dict to Config objects.
Defaults adapter provides your configuration object with default values. It will always be evaluated first when Config.load method is called. You can whether provide defaults values to Config as a Defaults object or as a dictionary.
>>> from etcaetera.adapter import Defaults
# Defaults adapter provides default configuration settings
>>> defaults = Defaults({"ABC": "123"})
>>> config = Config(defaults)
>>> print config
{
"ABC": "123"
}
The Overrides adapter overrides Config object values with it’s own values. It will always be evaluated last when the Config.load method is called.
>>> from etcaetera.adapter import Overrides
# The Overrides adapter helps you set overriding configuration settings.
# When registered over a Config objects, it will always be evaluated last.
# Use it if you wish to force some config values.
>>> overrides_adapter = Overrides({"USER": "overrided value"})
>>> config = Config({
"USER": "default_value",
"FIRST_SETTING": "first setting value"
})
>>> config.register(overrides_default)
>>> config.load()
>>> print config
{
"USER": "overrided user",
"FIRST_SETTING": "first setting value"
}
Env adapter loads configuration variables values from system environment. You can whether provide it a keys to be fetched from environment list as *args. Or you can pass it with a **kwargs dict of environment variables to be fetched as keys to adapter destination name values.
>>> from etcaetera.adapter import Env
# You can provide keys to be fetched by the adapter at construction
# as keys
>>> env = Env("USER", "PATH")
>>> env.load()
>>> print env.data
{
"USER": "user extracted from environment",
"PATH": "path extracted from environment",
"PWD": "pwd extracted from environment"
}
# alternatively pass it as env var names to adapter var
# names dict
>>> os.environ["SOURCE"], os.environ["OTHER_SOURCE"]
("my first value", "my second value")
>>> env = Env({"SOURCE": "DEST", "OTHER_SOURCE": "TEST"})
>>> env.load()
>>> print env.data
{
"DEST": "my first value",
"TEST": "my second value"
}
The File adapter will load the configuration settings from a file. Supported formats are json, yaml and python module files. Every key-value pairs stored in the pointed file will be loaded in the Config object it is registered to.
The Python module files should be in the same format as the Django settings files. Only uppercased variables will be loaded. Any python data structures can be used.
Here’s an example
Given the following settings.py file
$ cat /my/settings.py
FIRST_SETTING = 123
SECOND_SETTING = "this is the second value"
THIRD_SETTING = {"easy as": "do re mi"}
ignored_value = "this will be ignore"
File adapter output will look like this:
>>> from etcaetera.adapter import File
>>> file = File('/my/settings.py')
>>> file.load()
>>> print file.data
{
"FIRST_SETTING": 123,
"SECOND_SETTING": "this is the second value",
"THIRD_SETTING": {"easy as": "do re mi"}
}
Given the following json file content:
$ cat /my/json/file.json
{
"FIRST_SETTING": "first json file extracted setting",
"SECOND_SETTING": "second json file extracted setting"
}
The File adapter output will look like this:
>>> from etcaetera.adapter import File
# The File adapter awaits on a file path at construction.
# All you have to do then, is to let the magic happen
>>> file = File('/my/json/file.json')
>>> file.load()
>>> print file.data
{
"FIRST_SETTING": "first json file extracted setting",
"SECOND_SETTING": "second json file extracted setting"
}
The Module adapter will load settings from a python module. It emulates the django settings module loading behavior, so that every uppercased locals of the module is matched.
Given a mymodule.settings module looking this:
MY_FIRST_SETTING = 123
MY_SECOND_SETTING = "abc"
Loaded module data will look like this:
>>> from etcaetera.adapter import Module
# It will extract all of the module's uppercased local variables
>>> module = Module(mymodule.settings)
>>> module.load()
>>> print module.data
{
MY_FIRST_SETTING = 123
MY_SECOND_SETTING = "abc"
}
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
Report bugs at https://github.com/oleiade/etcaetera/issues.
If you are reporting a bug, please include:
Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.
Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implement it.
Etcaetera could always use more documentation, whether as part of the official Etcaetera docs, in docstrings, or even on the web in blog posts, articles, and such.
The best way to send feedback is to file an issue at https://github.com/oleiade/etcaetera/issues.
If you are proposing a feature:
Ready to contribute? Here’s how to set up etcaetera for local development.
Fork the etcaetera repo on GitHub.
Clone your fork locally:
$ git clone git@github.com:your_name_here/etcaetera.git
Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:
$ mkvirtualenv etcaetera
$ cd etcaetera/
$ python setup.py develop
Create a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:
$ flake8 etcaetera tests
$ python setup.py test
$ tox
To get flake8 and tox, just pip install them into your virtualenv.
Commit your changes and push your branch to GitHub:
$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature
Submit a pull request to the develop branch through the GitHub website.
Before you submit a pull request, check that it meets these guidelines: