config-decorator User Options Framework

Build Status Coverage Status Documentation Status GitHub Release Status PyPI Release Status PyPI Supported Python Versions License Status

User configuration framework developed for dob.


config-decorator makes it easy to define a hierarchical collection of user-configurable key-value settings using Pythonic @decorator syntax. It can be used with a modern file round tripper, such as ConfigObj, to add a capable, robust user configuration subsystem to any application.


Here’s a simple example:

#!/usr/bin/env python3

from config_decorator import section

def generate_config():

    class ConfigRoot(object):
        '''Decorate an empty class to create the root settings section.'''

    class ConfigSection(object):
        '''Use the root settings section decorator to define setting groups.'''

            "The color",
            choices=['red', 'yellow', 'blue'],
        def color(self):
            return 'red'

            "The volume",
            validate=lambda val: 0 <= val and val <= 11,
        def volume(self):
            return 11

    class ConfigSection(object):
        '''Another settings section.'''

            "Is it funky yet?",
        def funky(self):
            # Because value_type=bool, str will be converted to bool.
            # - Useful for config files where all values are strings!
            return 'False'

            "A list of numbers I heard in a song",
        def cleopatra(self):
            return [5, 10, 15, 20, 25, 30, 35, 40]

            "Example showing how to use dashes in a settings name",
        def kick_out_the_jams(self):
            return "I done kicked em out!"

    return ConfigRoot

cfgroot = generate_config()

# The config object is subscriptable.
assert cfgroot['mood']['color'] == 'red'

# You can override defaults with user values.
cfgroot['mood']['color'] = 'blue'
assert cfgroot['mood']['color'] == 'blue'

# And you can always reset your values back to default.
assert cfgroot.mood.color.default == 'red'
assert cfgroot['mood']['color'] == 'red'

# The config object is attribute-aware (allows dot-notation).
cfgroot.vibe.cleopatra.value = 100
# And list-type values intelligently convert atoms to lists.
assert cfgroot.vibe.cleopatra.value == [100]

# The config object is environ-aware, and prefers values it reads
# from the environment over those from a config file.
import os
from config_decorator.key_chained_val import KeyChainedValue
KeyChainedValue._envvar_prefix = 'TEST_'
os.environ['TEST_MOOD_VOLUME'] = '8'
assert cfgroot.mood.volume.value == 8

# The config object can be flattened to a dict, which makes it easy
# to persist settings keys and values to disk using another package.
from configobj import ConfigObj
saved_cfg = ConfigObj('path/to/persisted/settings')

# Likewise, values can be read from a dictionary, which makes loading
# them from a file saved to disk easy to do as well.
saved_cfg = ConfigObj('path/to/persisted/settings')


  • A setting value may come from one or more sources, but the value of the most important source is the value used. A setting value may come from the following sources, ordered from most important to least:

    • A “forced” value set internally by the application.

    • A “cliarg” value read from command line arguments.

    • An “envvar” value read from an environment variable.

    • A “config” value read from a user-supplied dictionary (e.g., from an INI file loaded by ConfigObj).

    • A default value (determined by decorated method used to define the setting).

  • Each setting value is:

    • always type-checked, though the type check could be a no-op;

    • optionally validated, possibly against a user-supplied choices list;

    • always documented, either by the first decorator argument, or from the decorated method '''docstring''';

    • sometimes hidden (e.g., for developer-only or experimental settings, to keep the user from seeing the setting unless its value differs from the default value);

    • sometimes ephemeral, or not saved (e.g., for values based on other values that must be generated at runtime, after all value sources are loaded).


  • For complete usage examples, see this project’s tests/.

  • For a real-world usage example, see nark’s ConfigRoot and related.