API Docs¶
Functions¶
Errors¶
configaro.ConfigError
configaro.ConfigModuleNotFoundError
configaro.ConfigModuleNotValidError
configaro.ConfigObjectNotInitializedError
configaro.ConfigPropertyNotFoundError
configaro.ConfigPropertyNotScalarError
configaro.ConfigUpdateNotValidError
Configaro Python configuration library.
-
exception
configaro.
ConfigModuleNotValidError
(path)[source]¶ Config module does not contain a ‘config’ attribute of ‘dict’ type error.
-
exception
configaro.
ConfigPropertyNotFoundError
(data: munch.Munch, prop_name: str)[source]¶ Config property not found error.
-
exception
configaro.
ConfigPropertyNotScalarError
(data: munch.Munch, prop_name: str)[source]¶ Config property not scalar error.
-
configaro.
get
(*prop_names, **kwargs) → Tuple[Union[munch.Munch, Any]][source]¶ Query config values in config object.
The config object must be initialized with
configaro.init()
before use.If no prop_names are provided, returns the config root config object:
config = get()
If one property name is provided, returns that sub config object:
prop = get('prop')
If multiple property names are provided, returns a tuple of sub config objects:
prop1, prop2 = get('prop1', 'prop2')
Multiple property names can also be provided in a single string argument as well:
prop1, prop2 = get('prop1 prop2')
If a property name is not found, configaro.ConfigPropertyNotFoundError is raised, unless a default keyword argument is provided:
prop = get('prop', default=None)
Parameters: - prop_names – config property names
- kwargs – config property names and values keyword args
Returns: property values
Raises: configaro.ConfigObjectNotInitializedError
– if config object has not been initializedconfigaro.ConfigPropertyNotFoundError
– if a config property in prop_names is not found
-
configaro.
init
(config_package: str, locals_path: str = None, locals_env_var: str = None)[source]¶ Initialize the config object.
The config object must be initialized before use and is built from one or two config modules. A config module is simply any Python module with a module attribute named config. The config object loaded from the defaults config module, as well as any locals config module found.
The defaults config module is always loaded. The required config_package argument is used to define the package in which the defaults config module, named
defaults.py
, is loaded from:init('my_project.config')
The locals config module is loaded, next if it exists, from the following locations, in precedence order from highest to lowest:
- one found at path specified by locals path
- one found at path specified by locals env var
- one found in config package
If no other options are provided, the locals config module will be loaded, if it exists, from the config_package.
If the optional locals_path argument is provided it will be used, if it exists, instead of any
locals.py
config module in the config package:init('my_project.config', locals_path='/path/to/my/alternatively_named_locals.py')
If the optional locals_env_var argument is provided it will be used as a an environment variable configuring the path of the locals config module to load, if the module exists:
init('my_project.config', locals_env_var='MY_PROJECT_CONFIG_LOCALS')
Repeated initialization has no effect. You can not re-initialize with different values.
Parameters: - config_package – package to search for config modules
- locals_path – path to locals config module
- locals_env_var – name of environment variable providing path to locals config module
-
configaro.
put
(*args, **kwargs)[source]¶ Modify config values in config object.
The config object must be initialized with
configaro.init()
before use.This function supports many expressive styles of usage.
The entire config object can be updated with a single dict data argument:
put({'prop_a': True, 'prop_b': 23})
Similarly, any sub config object can be updated with a string property and dict data argument:
put(prop={'prop_a': True, 'prop_b': 23}) put('nested.prop', {'prop_a': True, 'prop_b': 23})
Updates can also be specified by
name=value
update strings. If one or more string arguments are passed, the updates described by those update strings will be applied to the config object:put('prop_a=True') put('prop_b=23')
Update strings allow hierarchical configs to be updated:
put('prop.nested=awesome')
You can also batch up multiple updates in a single update string:
put('prop_a=True prop.nested=awesome')
If you are updating root config properties you can simply use keyword arguments:
put(prop_a=True, prop_d={'greeting': 'Hello', 'subject': 'world'})
Parameters: - args – config dict object or one or more ‘some.knob=value’ update strings
- kwargs – config property names and values keyword args
Raises: configaro.ConfigObjectNotInitializedError
– if config object has not been initializedconfigaro.ConfigPropertyNotScalarError
– if config property is not a scalarconfigaro.ConfigUpdateNotValidError
– if config update string is not valid