Package: config-decorator
User configuration framework developed fordob.Overviewconfig-decoratormakes it easy to define a hierarchical
collection of user-configurable key-value settings using
Pythonic@decoratorsyntax. It can be used with a modern
file round tripper, such asConfigObj, to add a capable,
robust user configuration subsystem to any application.ExampleHere’s a simple example:#!/usr/bin/env python3fromconfig_decoratorimportsectiondefgenerate_config():@section(None)classConfigRoot(object):'''Decorate an empty class to create the root settings section.'''pass@ConfigRoot.section('mood')classConfigSection(object):'''Use the root settings section decorator to define setting groups.'''@property@ConfigRoot.setting("The color",choices=['red','yellow','blue'],)defcolor(self):return'red'@property@ConfigRoot.setting("The volume",validate=lambdaval:0<=valandval<=11,)defvolume(self):return11@ConfigRoot.section('vibe')classConfigSection(object):'''Another settings section.'''@property@ConfigRoot.setting("Is it funky yet?",value_type=bool,)deffunky(self):# Because value_type=bool, str will be converted to bool.# - Useful for config files where all values are strings!return'False'@property@ConfigRoot.setting("A list of numbers I heard in a song",)defcleopatra(self):return[5,10,15,20,25,30,35,40]@property@ConfigRoot.setting("Example showing how to use dashes in a settings name",name='kick-out-the-jams')defkick_out_the_jams(self):return"I done kicked em out!"returnConfigRootcfgroot=generate_config()# The config object is subscriptable.assertcfgroot['mood']['color']=='red'# You can override defaults with user values.cfgroot['mood']['color']='blue'assertcfgroot['mood']['color']=='blue'# And you can always reset your values back to default.assertcfgroot.mood.color.default=='red'cfgroot.forget_config_values()assertcfgroot['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.assertcfgroot.vibe.cleopatra.value==[100]# The config object is environ-aware, and prefers values it reads# from the environment over those from a config file.importosfromconfig_decorator.key_chained_valimportKeyChainedValueKeyChainedValue._envvar_prefix='TEST_'os.environ['TEST_MOOD_VOLUME']='8'assertcfgroot.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.fromconfigobjimportConfigObjsaved_cfg=ConfigObj('path/to/persisted/settings')cfgroot.apply_items(saved_cfg)saved_cfg.write()# 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')cfgroot.update_known(saved_cfg)FeaturesA 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 byConfigObj).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-suppliedchoiceslist;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).ExploreFor complete usage examples, see this project’stests/.For a real-world usage example, seenark’sConfigRootand related.