Available sources¶
Hardcoded defaults¶
Environment variables¶
-
class
layeredconfig.
Environment
(environ=None, prefix=None, lower=True, sectionsep='_', **kwargs)[source]¶ Loads settings from environment variables. If
prefix
is set toMYAPP_
, the value of the environment variableMYAPP_HOME
will be available as the configuration settinghome
.Parameters: - environ (dict) – Environment variables, in dict form like
os.environ
. If not provided, uses the realos.environ
. - prefix (str) – Since the entire environment is not suitable to use as a configuration, only variables starting with this prefix are used.
- lower (True) – If true, lowercase the name of environment variables (since these typically uses uppercase)
- sectionsep (str) – An alternate section separator instead of
-
.
-
has
(key)[source]¶ This method should return true if the parameter identified by
key
is present in this configuration source. It is up to each configuration source to define the semantics of what exactly “is present” means, but a guideline is that only real values should count as being present. If you only have some sort of placeholder or typing information forkey
this should probably not return True.Note that it is possible that a configuration source would return True for
typed(some_key)
and at the same time return False forhas(some_key)
, if the source only carries typing information, not real values.
-
get
(key)[source]¶ Should return the actual value of the parameter identified by
key
. Ifhas(some_key)
returns True,get(some_key)
should always succeed. If the configuration source does not include intrinsic typing information (ie. everything looks like a string) this method should return the string as-is, LayeredConfig is responsible for converting it to the correct type.
-
set
(key, val)[source]¶ Should set the parameter identified by
key
to the new valuevalue
.This method should be prepared for any type of value, ie ints, lists, dates, bools… If the backend cannot handle the given type, it should convert to a str itself.
Note that this does not mean that the changes should be persisted in the backend data, only in the existing objects view of the data (only when
save()
is called, the changes should be persisted).
-
typed
(key)[source]¶ Should return True if this source contains typing information for
key
, ie information about which data type this parameter should be.For sources where everything is stored as a string, this should generally return False (no way of distinguishing an actual string from a date formatted as a string).
-
subsections
()[source]¶ Should return a list (or other iterator) of subsection keys, ie names that represent subsections of this configuration source. Not all configuration sources need to support subsections. In that case, this should just return an empty list.
-
subsection
(key)[source]¶ Should return the subsection identified by
key
, in the form of a new object of the same class, but initialized differently. Exactly how will depend on the source, but as a general rule the same resource handle used asself.source
should be passed to the new object. Often, the subsection key will need to be provided to the new object as well, so thatget()
and other methods can use it to look in the correct place.As a general rule, the constructor should be called with a
parent
parameter set toself
.
- environ (dict) – Environment variables, in dict form like
Command-line parameters¶
-
class
layeredconfig.
Commandline
(commandline=None, parser=None, sectionsep='-', add_help=True, **kwargs)[source]¶ Load configuration from command line options. Any long-style parameters are turned into configuration values, and parameters containing the section separator (by default
"-"
) are turned into nested config objects (i.e.--module-parameter=foo
results inself.module.parameter == "foo"
.If an initialized ArgumentParser object is provided, the defined parameters in that object is used for supporting short form options (eg.
'-f'
instead of'--force'
), typing information and help text. The standards argparse feature of printing a helpful message when the ‘-h’ option is given is retained.Parameters: - commandline (list) – Command line arguments, in list form like
sys.argv
. If not provided, uses the realsys.argv
. - parser (argparse.ArgumentParser) – An initialized/configured argparse object
- sectionsep (str) – An alternate section separator instead of
-
. - add_help (bool) – Same as for ArgumentParser()
-
rest
= []¶ The remainder of the command line, containing all parameters that couldn’t be turned into configuration settings.
-
setup
(config)[source]¶ Perform some post-initialization setup. This method will be called by the LayeredConfig constructor after its internal initialization is finished, with itself as argument. Sources may access all properties of the config object in order to eg. find out which parameters have been defined.
The sources will be called in the same order as they were provided to the LayeredConfig constructior, ie. lowest precedence first.
Parameters: config (layeredconfig.LayeredConfig) – The initialized config object that this source is a part of
-
has
(key)[source]¶ This method should return true if the parameter identified by
key
is present in this configuration source. It is up to each configuration source to define the semantics of what exactly “is present” means, but a guideline is that only real values should count as being present. If you only have some sort of placeholder or typing information forkey
this should probably not return True.Note that it is possible that a configuration source would return True for
typed(some_key)
and at the same time return False forhas(some_key)
, if the source only carries typing information, not real values.
-
get
(key)[source]¶ Should return the actual value of the parameter identified by
key
. Ifhas(some_key)
returns True,get(some_key)
should always succeed. If the configuration source does not include intrinsic typing information (ie. everything looks like a string) this method should return the string as-is, LayeredConfig is responsible for converting it to the correct type.
-
subsections
()[source]¶ Should return a list (or other iterator) of subsection keys, ie names that represent subsections of this configuration source. Not all configuration sources need to support subsections. In that case, this should just return an empty list.
-
subsection
(key)[source]¶ Should return the subsection identified by
key
, in the form of a new object of the same class, but initialized differently. Exactly how will depend on the source, but as a general rule the same resource handle used asself.source
should be passed to the new object. Often, the subsection key will need to be provided to the new object as well, so thatget()
and other methods can use it to look in the correct place.As a general rule, the constructor should be called with a
parent
parameter set toself
.
-
set
(key, value)[source]¶ Should set the parameter identified by
key
to the new valuevalue
.This method should be prepared for any type of value, ie ints, lists, dates, bools… If the backend cannot handle the given type, it should convert to a str itself.
Note that this does not mean that the changes should be persisted in the backend data, only in the existing objects view of the data (only when
save()
is called, the changes should be persisted).
-
typed
(key)[source]¶ Should return True if this source contains typing information for
key
, ie information about which data type this parameter should be.For sources where everything is stored as a string, this should generally return False (no way of distinguishing an actual string from a date formatted as a string).
- commandline (list) – Command line arguments, in list form like
INI files¶
-
class
layeredconfig.
INIFile
(inifilename=None, rootsection='__root__', sectionsep='.', writable=True, **kwargs)[source]¶ Loads and optionally saves configuration files in INI format, as handled by
configparser
.Parameters: - inifile (str) – The name of a ini-style configuration
file. The file should have a top-level
section, by default named
__root__
, whose keys are turned into top-level configuration parameters. Any other sections in this file are turned into nested config objects. - rootsection (str) – An alternative name for the top-level section. See note below.
- sectionsep (str) – separator to use in section names to separate nested subsections. See note below.
- writable (bool) – Whether changes to the LayeredConfig object that has this INIFile object amongst its sources should be saved in the INI file.
Note
Nested subsections is possible, but since the INI format does not natively support nesting, this is accomplished through specially-formatted section names, eg the config value mymodule.mysection.example would be expressed in the ini file as:
[mymodule.mysection] example = value
Since this source uses
configparser
, and since that module handles sections named[DEFAULT]
differently, this module will have a sort-of automatic cascading feature for subsections ifDEFAULT
is used asrootsection
-
typed
(key)[source]¶ Should return True if this source contains typing information for
key
, ie information about which data type this parameter should be.For sources where everything is stored as a string, this should generally return False (no way of distinguishing an actual string from a date formatted as a string).
-
subsections
()[source]¶ Should return a list (or other iterator) of subsection keys, ie names that represent subsections of this configuration source. Not all configuration sources need to support subsections. In that case, this should just return an empty list.
-
subsection
(key)[source]¶ Should return the subsection identified by
key
, in the form of a new object of the same class, but initialized differently. Exactly how will depend on the source, but as a general rule the same resource handle used asself.source
should be passed to the new object. Often, the subsection key will need to be provided to the new object as well, so thatget()
and other methods can use it to look in the correct place.As a general rule, the constructor should be called with a
parent
parameter set toself
.
-
has
(key)[source]¶ This method should return true if the parameter identified by
key
is present in this configuration source. It is up to each configuration source to define the semantics of what exactly “is present” means, but a guideline is that only real values should count as being present. If you only have some sort of placeholder or typing information forkey
this should probably not return True.Note that it is possible that a configuration source would return True for
typed(some_key)
and at the same time return False forhas(some_key)
, if the source only carries typing information, not real values.
-
get
(key)[source]¶ Should return the actual value of the parameter identified by
key
. Ifhas(some_key)
returns True,get(some_key)
should always succeed. If the configuration source does not include intrinsic typing information (ie. everything looks like a string) this method should return the string as-is, LayeredConfig is responsible for converting it to the correct type.
-
set
(key, value)[source]¶ Should set the parameter identified by
key
to the new valuevalue
.This method should be prepared for any type of value, ie ints, lists, dates, bools… If the backend cannot handle the given type, it should convert to a str itself.
Note that this does not mean that the changes should be persisted in the backend data, only in the existing objects view of the data (only when
save()
is called, the changes should be persisted).
-
save
()[source]¶ Persist changed data to the backend. This generally means to update a loaded configuration file with all changed data, or similar.
This method will only ever be called if
writable
is True, and only ifdirty
has been set to True.If your source is read-only, you don’t have to implement this method.
- inifile (str) – The name of a ini-style configuration
file. The file should have a top-level
section, by default named
JSON files¶
-
class
layeredconfig.
JSONFile
(jsonfilename=None, writable=True, **kwargs)[source]¶ Loads and optionally saves configuration files in JSON format. Since JSON has some support for typed values (supports numbers, lists, bools, but not dates or datetimes), data from this source are sometimes typed, sometimes only available as strings.
Parameters: -
typed
(key)[source]¶ Should return True if this source contains typing information for
key
, ie information about which data type this parameter should be.For sources where everything is stored as a string, this should generally return False (no way of distinguishing an actual string from a date formatted as a string).
-
set
(key, value)[source]¶ Should set the parameter identified by
key
to the new valuevalue
.This method should be prepared for any type of value, ie ints, lists, dates, bools… If the backend cannot handle the given type, it should convert to a str itself.
Note that this does not mean that the changes should be persisted in the backend data, only in the existing objects view of the data (only when
save()
is called, the changes should be persisted).
-
save
()[source]¶ Persist changed data to the backend. This generally means to update a loaded configuration file with all changed data, or similar.
This method will only ever be called if
writable
is True, and only ifdirty
has been set to True.If your source is read-only, you don’t have to implement this method.
-
YAML files¶
-
class
layeredconfig.
YAMLFile
(yamlfilename=None, writable=True, **kwargs)[source]¶ Loads and optionally saves configuration files in YAML format. Since YAML (and the library implementing the support, PyYAML) has automatic support for typed values, data from this source are typed.
Parameters: -
get
(key)[source]¶ Should return the actual value of the parameter identified by
key
. Ifhas(some_key)
returns True,get(some_key)
should always succeed. If the configuration source does not include intrinsic typing information (ie. everything looks like a string) this method should return the string as-is, LayeredConfig is responsible for converting it to the correct type.
-
save
()[source]¶ Persist changed data to the backend. This generally means to update a loaded configuration file with all changed data, or similar.
This method will only ever be called if
writable
is True, and only ifdirty
has been set to True.If your source is read-only, you don’t have to implement this method.
-
PList files¶
-
class
layeredconfig.
PListFile
(plistfilename=None, writable=True, **kwargs)[source]¶ Loads and optionally saves configuration files in PList format. Since PList has some support for typed values (supports numbers, lists, bools, datetimes but not dates), data from this source are sometimes typed, sometimes only available as strings.
Parameters: -
set
(key, value)[source]¶ Should set the parameter identified by
key
to the new valuevalue
.This method should be prepared for any type of value, ie ints, lists, dates, bools… If the backend cannot handle the given type, it should convert to a str itself.
Note that this does not mean that the changes should be persisted in the backend data, only in the existing objects view of the data (only when
save()
is called, the changes should be persisted).
-
get
(key)[source]¶ Should return the actual value of the parameter identified by
key
. Ifhas(some_key)
returns True,get(some_key)
should always succeed. If the configuration source does not include intrinsic typing information (ie. everything looks like a string) this method should return the string as-is, LayeredConfig is responsible for converting it to the correct type.
-
typed
(key)[source]¶ Should return True if this source contains typing information for
key
, ie information about which data type this parameter should be.For sources where everything is stored as a string, this should generally return False (no way of distinguishing an actual string from a date formatted as a string).
-
subsections
()[source]¶ Should return a list (or other iterator) of subsection keys, ie names that represent subsections of this configuration source. Not all configuration sources need to support subsections. In that case, this should just return an empty list.
-
save
()[source]¶ Persist changed data to the backend. This generally means to update a loaded configuration file with all changed data, or similar.
This method will only ever be called if
writable
is True, and only ifdirty
has been set to True.If your source is read-only, you don’t have to implement this method.
-
Python files¶
-
class
layeredconfig.
PyFile
(pyfilename=None, **kwargs)[source]¶ Loads configuration from a python source file. Any variables defined in that file will be interpreted as configuration keys. The class
Subsection
is automatically imported into the context when the file is executed, and represents a subsection of the configuration. Any attribute set on such an object is treated as a configuration parameter on that subsection.Note
The python source file is loaded and interpreted once, when creating the PyFile object. If a value is set by eg. calling a function, that function will only be called at load time, not when accessing the parameter.
Parameters: pyfile (str) – The name of a file containing valid python code. -
has
(key)[source]¶ This method should return true if the parameter identified by
key
is present in this configuration source. It is up to each configuration source to define the semantics of what exactly “is present” means, but a guideline is that only real values should count as being present. If you only have some sort of placeholder or typing information forkey
this should probably not return True.Note that it is possible that a configuration source would return True for
typed(some_key)
and at the same time return False forhas(some_key)
, if the source only carries typing information, not real values.
-
get
(key)[source]¶ Should return the actual value of the parameter identified by
key
. Ifhas(some_key)
returns True,get(some_key)
should always succeed. If the configuration source does not include intrinsic typing information (ie. everything looks like a string) this method should return the string as-is, LayeredConfig is responsible for converting it to the correct type.
-
subsections
()[source]¶ Should return a list (or other iterator) of subsection keys, ie names that represent subsections of this configuration source. Not all configuration sources need to support subsections. In that case, this should just return an empty list.
-
subsection
(key)[source]¶ Should return the subsection identified by
key
, in the form of a new object of the same class, but initialized differently. Exactly how will depend on the source, but as a general rule the same resource handle used asself.source
should be passed to the new object. Often, the subsection key will need to be provided to the new object as well, so thatget()
and other methods can use it to look in the correct place.As a general rule, the constructor should be called with a
parent
parameter set toself
.
-
set
(key, value)[source]¶ Should set the parameter identified by
key
to the new valuevalue
.This method should be prepared for any type of value, ie ints, lists, dates, bools… If the backend cannot handle the given type, it should convert to a str itself.
Note that this does not mean that the changes should be persisted in the backend data, only in the existing objects view of the data (only when
save()
is called, the changes should be persisted).
-
typed
(key)[source]¶ Should return True if this source contains typing information for
key
, ie information about which data type this parameter should be.For sources where everything is stored as a string, this should generally return False (no way of distinguishing an actual string from a date formatted as a string).
-
etcd
stores¶
-
class
layeredconfig.
EtcdStore
(baseurl='http://127.0.0.1:2379/v2/', **kwargs)[source]¶ Loads configuration from a etcd store.
Parameters: baseurl – The main endpoint of the etcd store etcd
has no concept of typed values, so all data from this source are returned as strings.-
has
(key)[source]¶ This method should return true if the parameter identified by
key
is present in this configuration source. It is up to each configuration source to define the semantics of what exactly “is present” means, but a guideline is that only real values should count as being present. If you only have some sort of placeholder or typing information forkey
this should probably not return True.Note that it is possible that a configuration source would return True for
typed(some_key)
and at the same time return False forhas(some_key)
, if the source only carries typing information, not real values.
-
get
(key)[source]¶ Should return the actual value of the parameter identified by
key
. Ifhas(some_key)
returns True,get(some_key)
should always succeed. If the configuration source does not include intrinsic typing information (ie. everything looks like a string) this method should return the string as-is, LayeredConfig is responsible for converting it to the correct type.
-
typed
(key)[source]¶ Should return True if this source contains typing information for
key
, ie information about which data type this parameter should be.For sources where everything is stored as a string, this should generally return False (no way of distinguishing an actual string from a date formatted as a string).
-
subsections
()[source]¶ Should return a list (or other iterator) of subsection keys, ie names that represent subsections of this configuration source. Not all configuration sources need to support subsections. In that case, this should just return an empty list.
-
subsection
(key)[source]¶ Should return the subsection identified by
key
, in the form of a new object of the same class, but initialized differently. Exactly how will depend on the source, but as a general rule the same resource handle used asself.source
should be passed to the new object. Often, the subsection key will need to be provided to the new object as well, so thatget()
and other methods can use it to look in the correct place.As a general rule, the constructor should be called with a
parent
parameter set toself
.
-
set
(key=None, value=None)[source]¶ Should set the parameter identified by
key
to the new valuevalue
.This method should be prepared for any type of value, ie ints, lists, dates, bools… If the backend cannot handle the given type, it should convert to a str itself.
Note that this does not mean that the changes should be persisted in the backend data, only in the existing objects view of the data (only when
save()
is called, the changes should be persisted).
-
save
()[source]¶ Persist changed data to the backend. This generally means to update a loaded configuration file with all changed data, or similar.
This method will only ever be called if
writable
is True, and only ifdirty
has been set to True.If your source is read-only, you don’t have to implement this method.
-