Hierarchical configuration manager for Python 2/3.
hconf allows configurations from multiple sources to be prioritized and amalgamated onto a single object. Configuration options and parsers must be registered with an hconf.ConfigManager which can then be used to produce the resulting configuration object.
hconf can be installed using pip:
pip install hconf
Alternatively, hconf can be installed manually by cloning this repo and running the following command in the main directory:
python setup.py install
Note: hconf requires setuptools and PyYAML (the latter of which will be installed automatically).
>>> import hconf
>>> configMgr = hconf.ConfigManager()
>>> # Add configuration options
>>> configMgr.addConfig('start-time', required=True, cast=int)
>>> configMgr.addConfig('end-time', cast=int)
>>> configMgr.addConfig('action', required=True, default='list')
>>> # Add parsers; configuration options will be acquired from them in order
>>> configMgr.registerParser(hconf.Subparsers.Cmdline("Program -h description")
>>> configMgr.registerParser(hconf.Subparsers.YAML(filename="program.cfg", filepath='/etc/program/conf')
>>> # Parse configuration options into an object
>>> config = configMgr.parse()
>>> print vars(config)
{
'start-time': 1234567890,
'end-time': None,
'action': 'list'
}
Object which controls the registering of configuration options and subparsers.
When hconf.ConfigManager objects are instantiated they can optionally be passed a series of dictionaries representing arguments to addConfig calls. The code below creates two equivalent ConfigManager objects
>>> c1 = hconf.ConfigManager()
>>> c1.addConfig('a', required=True, cast=int, default=0)
>>> c1.addConfig('b', required=False, default=1)
>>> c2 = hconf.ConfigManager(
... {'name': 'a', 'required': True, 'cast': int, 'default': 0},
... {'name': 'b', 'required': False, 'default': 1}
... )
Registers a configuration object with the manager. Only configuration options registered with the manager will be populated on the resulting configuration obejct returned from ConfigManager.parse. Any non-registered configuration options received from the registered subparsers will raise an UnknownConfigurationException. Accepts 5 arguments, with the first being required and the following 4 optional.
- name - The name of the configuration option to accept. Note that any -'s in the name will be converted to _'s on the resulting configuration object. It must also not start with a number and must contain only alphanumeric characters, dashes and underscores.
- required - A boolean indicating whether or not this configuration option is required or not. If not passed and not required, will be set to None on the resulting configuration object. If not passed and required, a MissingConfigurationException will be raised.
- cast - A type (or function accepting 1 argument and returning an object) to cast the input as. If any error occurs during casting an InvalidConfigurationException will be raised.
- default - The default value to assign to this configuration option if not passed. Note that default=None is not valid if required=True, as required=True will force a MissingConfigurationException to be raised if the final value of the configuration option is None.
- description - A human readable description of this configuration parameter. Will be displayed when the program is run with a -h flag and a Cmdline subparser is registered.
>>> c1 = hconf.ConfigManager()
>>> c1.addConfig('a', required=True, cast=int, default=0, description="A parameter")
>>> c1.addConfig('b', required=False, default=1)
Registers a subparser to parse configuration options from some source. A list of the pre-built subparsers can be found below. The parsers will be run in the order that they are registered with the manager. If an earlier parser parses out a configuration option and then a later parser parses out the same configuration option, the later parser will overwrite the earlier parsers configuration value. In this way you can specify a hierarchy of configuration sources. For example, cmdline >= Config File >= Defaults. If the parser passed to registerParser is not a subclass of hconf.Subparsers.Subparser a TypeError is raised.
>>> confMgr = hconf.ConfigManager()
>>> confMgr.addConfig('a')
>>> confMgr.registerParser(hconf.Subparsers.Dictionary({'a': 1}))
>>> confMgr.registerParser(hconf.Subparsers.Dictionary({'a': 2}))
>>> vars(confMgr.parse())
{'a': 2}
Parses registered configuration options using the registered subparsers into a configuration object. Accepts no parameters. Configuration options can be extracted from the returned configuration object either by attribute lookup or dictionary lookup.
>>> confMgr = hconf.ConfigManager()
>>> confMgr.addConfig('a')
>>> confMgr.registerParser(hconf.Subparsers.Dictionary({'a': 1}))
>>> config = confMgr.parse()
>>> config['a']
1
>>> config.a
1
The hconf.Exceptions module contains exceptions which may be thrown by ConfigManager objects.
Thrown by ConfigManager.addConfig when a configuration option with an invalid name is registered.
Thrown by ConfigManager.parse when a configuration option is registered with a cast, and the cast raises an exception.
Thrown by ConfigManager.parse when a configuration option registered with required=True would be returned with the resulting config object with a value of None.
Thrown by ConfigManager.parse when an unregistered configuration option is parsed by a subparser.
Thrown by various subparsers on initialization/parsing when an error occurs.
Module which contains subparsers which can be registered to a ConfigManager using ConfigManager.registerParser. You can define your own subparsers by overriding hconf.subparser.Subparser or hconf.subparser.ConfigFileSubparser.
Parses configuration options from the command line. Also creates help output when the program is run with a -h flag.
Command line parsers can accept an optional description argument, which will be used as the description for the program in the help output if it is run with a -h flag.
Command line parsers can optionally either be subclassed or have this function overridden to modify the argparse.ArgumentParser used to accept command-line arguments. This function should accept two parameters, the first being the ConfigManager object the subparser is registered to, and the second being the Config object which has been constructed thus far. It should return a single argument, being the argparse.ArgumentParser that the subparser should use to parse arguments from the command line.
Note that any arguments registered with underscores will have them converted to dashes when accepting commandline arguments.
For example, a configuration registered with the name start_time will be accepted from the command line as --start-time.
cmdlineSubparser = hconf.Subparsers.Cmdline("Program Description")
Subparser which accepts a python dictionary as an input and returns it. Can be used to accept configuration options from external sources, like another process or from a socket.
dictionarySubparser = hconf.Subparsers.Dictionary(someDictionary)
Subparser which parses configuration options from an .ini configuration file. Arguments:
- sections - (Optional) A list of names of sections to parse. Note that DEFAULT is not a valid section name as that section is always parsed. If not passed all sections will be parsed.
- hconf.Subparsers.ConfigFileSubparser keyword arguments. See below.
iniSubparser = hconf.Subparsers.INI(sections=['client'], filename='prog.cnf', filepath='/etc/prog/conf')
Subparser which accepts a JSON string (which when parsed must result in a dictionary) and returns the resulting dictionary. Can be used to accept configuration options from external sources, like another process or from a socket.
jsonSubparser = hconf.Subparsers.JSON(someJSONString)
Subparser which parses configuration options from a .yaml/.yml configuration file. Arguments:
- hconf.Subparsers.ConfigFileSubparser keyword arguments. See below.
yamlSubparser = hconf.Subparsers.YAML(filenameConfig='config-name', filepathConfig='config-path')
Base class for subparsers. Defines a single function, parse, which must be overridden.
Convenience base class for subparsers which require the input of a configuration file to parse. Requires one of two pairs of keyword arguments to be passed to __init__:
- filepath: Either a list/tuple of the path tokens or a complete string to the directory which the configuration file resides in.
- filename: A string containing the name and extension of the configuration file to parse.
or
- filepathConfig: The name of a configuration option, the value of which will be acquired from the Config object and used as the path to the directory containing the configuration file to parse.
- filenameConfig: The name of a configuration option, the value of which will be acquired from the Config object and used as the name of the configuration file to parse.
Notes:
- If both filepath/filename and filepathConfig/filenameConfig are passed, filepath/filename will be used UNLESS the configuration options filepathConfig/filenameConfig are not None on the Config object. In other words, filepath/filename acts as the default if filepathConfig/filenameConfig aren't passed.
- If filepathConfig/filenameConfig are used, the names they refer to must be registered as configuration objects in the ConfigManager as well. Example:
iniSubparser = hconf.Subparsers.INI(filepathConfig='ini_conf_path', filenameConfig='ini_conf_name')
confMgr.addConfig('ini_conf_path')
conf<gr.addConfig('ini_conf_name')