layeredconfig

.. image:: https://badge.fury.io/py/layeredconfig.png :target: http://badge.fury.io/py/layeredconfig

.. image:: https://travis-ci.org/staffanm/layeredconfig.png?branch=master :target: https://travis-ci.org/staffanm/layeredconfig

.. image:: https://ci.appveyor.com/api/projects/status/nnfqv9jhxh3afgn0/branch/master :target: https://ci.appveyor.com/project/staffanm/layeredconfig/branch/master

.. image:: https://coveralls.io/repos/staffanm/layeredconfig/badge.png?branch=master :target: https://coveralls.io/r/staffanm/layeredconfig

.. image:: https://landscape.io/github/staffanm/layeredconfig/master/landscape.png :target: https://landscape.io/github/staffanm/layeredconfig/master :alt: Code Health

.. image:: https://pypip.in/d/layeredconfig/badge.png :target: https://pypi.python.org/pypi/layeredconfig

Full documentation: https://layeredconfig.readthedocs.org/

LayeredConfig compiles configuration from files, environment variables, command line arguments, hard-coded default values, or other backends, and makes it available to your code in a simple way::

from layeredconfig import (LayeredConfig, Defaults, INIFile,
                           Environment, Commandline)

# This represents four different way of specifying the value of the
# configuration option "hello":

# 1. hard-coded defaults
defaults = {"hello": "is it me you're looking for?"}

# 2. INI configuration file
with open("myapp.ini", "w") as fp:
    fp.write("""
[__root__]
hello = kitty
""")

# 3. enironment variables
import os
os.environ['MYAPP_HELLO'] = 'goodbye'

# 4.command-line arguments
import sys
sys.argv = ['./myapp.py', '--hello=world']

# Create a config object that gets settings from these four
# sources.
config = LayeredConfig(Defaults(defaults),
                       INIFile("myapp.ini"),
                       Environment(prefix="MYAPP_"),
                       Commandline())

# Prints "Hello world!", i.e the value provided by command-line
# arguments. Latter sources take precedence over earlier sources.
print("Hello %s!" % config.hello)

• A flexible system makes it possible to specify the sources of configuration information, including which source takes precedence. Implementations of many common sources are included and there is a API for writing new ones.
• Included configuration sources for INI files, YAML files, JSON file, PList files, etcd stores (read-write), Python source files, hard-coded defaults, command line options, environment variables (read-only).
• Configuration can include subsections (ie. config.downloading.refresh) and if a subsection does not contain a requested setting, it can optionally be fetched from the main configuration (if config.module.retry is missing, config.retry can be used instead).
• Configuration settings can be changed by your code (i.e. to update a "lastmodified" setting or similar), and changes can be persisted (saved) to the backend of your choice.
• Configuration settings are typed (ie. if a setting should contain a date, it's made available to your code as a datetime.date object, not a str). If settings are fetched from backends that do not themselves provide typed data (ie. environment variables, which by themselves are strings only), a system for type coercion makes it possible to specify how data should be converted.

History

0.3.3 (2019-11-11)

• INIFile has been extended to support nested subsections.
• Fixed a problem with DictSource (and by extension the Defaults source) where nested sections could be erroneously handled.
• The sectionsep parameter to the Environment constructor has been documented. Thanks to @brentmclark for the patch!
• Using "_" in the name of a configuration setting was not supported, regardless of what sectionsep had been set to. Thanks to @dginzbourg for reporting this!
• Support for python 3.3 and 2.6 was dropped.

0.3.2 (2016-09-26)

• Fixed bug #9 (Custom section separators caused values to be retrieved as lists, not single values). Thanks to @numbnut for reporting this!

0.3.1 (2016-08-31)

• Fixed bug #8 (layering a Commandline source over a YAMLFile with defined subsection resulted in crash in initialization. Thanks to @AnsonT for reporting this!
• The default URI used for EtcdStore was changed to reflect that port 2379 should be used instead of 4001 (which was the default for etcd 1.*).
• Support for Python 3.2 was dropped.

0.3.0 (2016-08-06)

• New staticmethod dump, which returns the content of the passed config object as a dict. This is also used as a printable representation of a config object (through __repr__).
• The intrinsic type of any typed setting may not be None any longer.
• If you subclass LayeredConfig, any created subsection will be instances of your subclass, not the base LayeredConfig class
• Layering multiple configuration files now works even when earlier files might lack subsections present in latter.

All of the above was done by @jedipi. Many thanks!

A number of unreported bugs, mostly concerning unicode handling and type conversion in various sources, was also fixed.

0.2.2 (2016-01-24)

• Fixed a bug when using a class in a Default configuration for automatic coercion, where the type of the class isn't type (as is the case with the "newint" and other classes from the future module).

• Fixed a bug where loading configuration from multiple config files would crash if latter configs lacked subsections present in earlier. Thanks to @badkapitan!

0.2.1 (2014-11-26)

• Made the Commandline source interact better with "partially configured" ArgumentParser objects (parsers that has been configured with some, but not all, possible arguments).

0.2.0 (2014-11-22)

• Integration with argparse: The Commandline source now accepts an optional parse parameter, which should be a configured argparse.ArgumentParser object. Most features of argparse, such as specifying the type of arguments, and automatic help text
• A new source, PyFile, for reading configuration from python source files.
• Another new source, EtcdStore, for reading configuration from etcd stores.

0.1.0 (2014-11-03)

• First release on PyPI.