Class @decorator for defining exquisite settings configurations
Project description
User configuration framework developed for dob.
Overview
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.
Example
Here’s a simple example:
#!/usr/bin/env python3
from config_decorator import section
def generate_config():
@section(None)
class ConfigRoot(object):
'''Decorate an empty class to create the root settings section.'''
pass
@ConfigRoot.section('mood')
class ConfigSection(object):
'''Use the root settings section decorator to define setting groups.'''
@property
@ConfigRoot.setting(
"The color",
choices=['red', 'yellow', 'blue'],
)
def color(self):
return 'red'
@property
@ConfigRoot.setting(
"The volume",
validate=lambda val: 0 <= val and val <= 11,
)
def volume(self):
return 11
@ConfigRoot.section('vibe')
class ConfigSection(object):
'''Another settings section.'''
@property
@ConfigRoot.setting(
"Is it funky yet?",
value_type=bool,
)
def funky(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",
)
def cleopatra(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'
)
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'
cfgroot.forget_config_values()
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')
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)
Features
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).
Explore
For complete usage examples, see this project’s tests/.
For a real-world usage example, see nark’s ConfigRoot and related.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for config_decorator-2.0.18-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8057e83ab87c11c9af9a2a89b887e01fd8523954ff39857691aa44ee44f8e421 |
|
MD5 | 35f1f2118bbac6b3f5415f71011f99ae |
|
BLAKE2b-256 | 04d46f3b05102344a035d9dcea0454651612a0aa3a81fe212ab245008597a291 |