Sources¶
The built-in sources are:
argparse
¶
-
class
multiconfparse.
ArgparseSource
(config_specs, priority=20) Obtains config values from an
argparse.ArgumentParser
.Do not create
ArgparseSource
objects directly, add them to aConfigParser
object usingConfigParser.add_source()
. For example:parser = multiconfparse.ConfigParser() parser.add_config("config_item1") parser.add_config("config_item2", nargs=2, type=int) parser.add_config("config_item3", action="store_true") argparse_source = parser.add_source("argparse") argparse_parser = argparse.ArgumentParser() argparse_parser.add_argument("arg1") argparse_parser.add_argument("--opt1", type=int, action="append") argparse_source.add_configs_to_argparse_parser(argparse_parser) args = argparse_parser.parse_args(( "arg1_value --config-item1 v1 --config-item2 1 2 --opt1 opt1_v1 " "--config-item-3 --opt1 opt1_v2" ).split()) argparse_source.notify_parsed_args(args) config_parser.parse_config() # -> multiconfparse.Namespace { # "config_item1": "v1", # "config_item2": [1, 2], # "config_item3": True, # }
The
argparse
source does not create anargparse.ArgumentParser
for you. This is to allow extra command line arguments to be added to anargparse.ArgumentParser
that are not config items. InsteadArgparseSource
, which implements theargparse
source provides two methods to provide communication with theargparse.ArgumentParser
:-
add_configs_to_argparse_parser
(argparse_parser) Add arguments to an
argparse.ArgumentParser
for config items.
-
notify_parsed_args
(argparse_namespace) Notify the
argparse
source of theargparse.Namespace
object returned byargparse.ArgumentParser.parse_args()
.
If you don’t need to add command line arguments other than for config items, see
SimpleArgparseSource
which implements thesimple_argparse
source.The arguments of
ConfigParser.add_source()
for theargparse
source are:source
(required, positional):"argparse"
priority
(optional, keyword): The priority for the source. The default priority for anargparse
source is20
.
Note that:
- The name of the command line argument for a config item is the config
item’s name with underscores (
_
) converted to hyphens (-
) and prefixed with--
.
-
simple_argparse
¶
-
class
multiconfparse.
SimpleArgparseSource
(config_specs, argument_parser_class=<class 'argparse.ArgumentParser'>, priority=20, **kwargs) Obtains config values from the command line.
The
simple_argparse
source is simpler to use than theargparse
source but it doesn’t allow adding arguments that are not config items.Do not create objects of this class directly - create them via
ConfigParser.add_source()
instead. For example:parser = multiconfparse.ConfigParser() parser.add_config("config_item1") parser.add_config("config_item2", nargs=2, type=int) parser.add_config("config_item3", action="store_true") parser.add_source("simple_argparse") config_parser.parse_config() # If the command line looks something like: # PROG_NAME --config-item1 v1 --config-item2 1 2 --config-item-3 # The result would be: # multiconfparse.Namespace { # "config_item1": "v1", # "config_item2": [1, 2], # "config_item3": True, # }
The arguments of
ConfigParser.add_source()
for thesimple_argparse
source are:source
(required, positional):"simple_argparse"
argument_parser_class
(optional, keyword): a class derived fromargparse.ArgumentParser
to use instead ofArgumentParser
itself. This can be useful if you want to overrideargparse.ArgumentParser.exit()
orargparse.ArgumentParser.error()
.priority
(optional, keyword): The priority for the source. The default priority for asimple_argparse
source is20
.- Extra keyword arguments to pass to
argparse.ArgumentParser
. E.g.prog
,allow_help
. Don’t use theargument_default
option though - thesimple_argparse
sources sets this internally. See theconfig_default
option forConfigParser
instead.
Note that:
- The name of the command line argument for a config item is the config
item’s name with underscores (
_
) converted to hyphens (-
) and prefixed with--
.
environment
¶
-
class
multiconfparse.
EnvironmentSource
(config_specs, none_values=None, priority=10, env_var_prefix='') Obtains config values from the environment.
Do not create
EnvironmentSource
objects directly, add them to aConfigParser
object usingConfigParser.add_source()
. For example:# For demonstration purposes, set some config values in environment # variables os.environ["MY_APP_CONFIG_ITEM1"] = "v1" os.environ["MY_APP_CONFIG_ITEM2"] = "1 2" os.environ["MY_APP_CONFIG_ITEM3"] = "" parser = multiconfparse.ConfigParser() parser.add_config("config_item1") parser.add_config("config_item2", nargs=2, type=int) parser.add_config("config_item3", action="store_true") parser.add_source("environment", env_var_prefix="MY_APP_") parser.parse_config() # -> multiconfparse.Namespace { # "config_item1": "v1", # "config_item2": [1, 2], # "config_item3": True, # }
The arguments of
ConfigParser.add_source()
for theenvironment
source are:source
(required, positional):"environment"
none_values
(optional, keyword): a list of values that, when seen in environment variables, should be treated as if they were not present (i.e. values for config items withnargs == 0
ornargs == "?"
(where theconst
value should be used rather than the value from the dict).The default
none_values
is[""]
. using a different value fornone_values
is useful you want the empty string to be treated as a valid config value.priority
(optional, keyword): The priority for the source. The default priority for anenvironment
source is10
.env_var_prefix
(optional, keyword): a string prefixed to the environment variable names that the source will look for. The default value is""
.
Note that:
- The name of the environment variable for a config item is the config
item’s name, converted to upper case, then prefixed with
env_var_prefix
. - Values in environment variables for config items with
nargs == 0
ornargs == "?"
(where theconst
value should be used rather than the value from the environment variable) should be values from thenone_values
list described above. - Values in environment variables for config items with
nargs >= 2
,nargs == "+"
ornargs == "*"
are split into arguments byshlex.split()
(i.e. like arguments given on a command line via a shell). See theshlex
documentation for full details.
json
¶
-
class
multiconfparse.
JsonSource
(config_specs, path=None, fileobj=None, none_values=None, json_none_values=None, priority=0) Obtains config values from a JSON file.
Do not create objects of this class directly - create them via
ConfigParser.add_source()
. For example:parser = multiconfparse.ConfigParser() parser.add_config("config_item1") parser.add_config("config_item2", nargs=2, type=int) parser.add_config("config_item3", action="store_true") fileobj = io.StringIO(''' { "config_item1": "v1", "config_item2": [1, 2], "config_item3": null } ''') parser.add_source("json", fileobj=fileobj) config_parser.parse_config() # -> multiconfparse.Namespace { # "config_item1": "v1", # "config_item2": [1, 2], # "config_item3": True, # }
The arguments of
ConfigParser.add_source()
forjson
sources are:source
(required, positional):"json"
.priority
(optional, keyword): The priority for the source. The default priority for ajson
source is0
.path
(optional, keyword): path to the JSON file to parse. Exactly one of thepath
andfileobj
options must be given.fileobj
(optional keyword): a file object representing a stream of JSON data. Exactly one of thepath
andfileobj
options must be given.none_values
(optional, keyword): a list of python values that, when seen as config item values after JSON decoding, should be treated as if they were not present (i.e. values for config items withnargs == 0
ornargs == "?"
(where theconst
value should be used rather than the value from the dict). The defaultnone_values
is[]
.json_none_values
(optional, keyword): a list of JSON values (as strings) that are decoded into Python values and added tonone_values
. The defaultjson_none_values
is["null"]
.
Notes:
The data in the JSON file should be a JSON object. Each config item value should be assigned to a field of the object that has the same name as the config item.
Fields in the JSON object for config items with
nargs == 0
ornargs == "?"
(where theconst
value should be used rather than the value from the dict) should either have values from thejson_none_values
list or should decode to values in thenone_values
list.Fields in the JSON object for config items with
nargs >= 2
,nargs == "+"
ornargs == "*"
should be JSON arrays with an element for each argument of the config item.In the special case where
nargs == "+"
ornargs == "*"
and there is a single argument for the config item, the value may be given without the enclosing JSON array, unless the argument is itself an array.
dict
¶
-
class
multiconfparse.
DictSource
(config_specs, values_dict, none_values=None, priority=0) Obtains config values from a Python
dict
object.Do not create
DictSource
objects directly, add them to aConfigParser
object usingConfigParser.add_source()
. For example:parser = multiconfparse.ConfigParser() parser.add_config("config_item1") parser.add_config("config_item2", nargs=2, type=int) parser.add_config("config_item3", action="store_true") values_dict = { "config_item1": "v1", "config_item2": [1, 2], "config_item3": None, } parser.add_source("dict", values_dict) parser.parse_config() # -> multiconfparse.Namespace { # "config_item1": "v1", # "config_item2": [1, 2], # "config_item3": True, # }
The arguments of
ConfigParser.add_source()
for thedict
source are:source
(required, positional):"dict"
.values_dict
(required, positional): thedict
containing the config values.Note that:
Values in
values_dict
for config items withnargs == 0
ornargs == "?"
(where theconst
value should be used rather than the value from the dict) should be values from thenone_values
list described below.Values in
values_dict
for config items withnargs >= 2
,nargs == "+"
ornargs == "*"
should belist
objects with an element for each argument of the config item.In the special case where
nargs == "+"
ornargs == "*"
and there is a single argument for the config item, the value may be given without the enclosinglist
, unless the argument is itself alist
.
none_values
(optional, keyword): a list of values that, when seen invalues_dict
, should be treated as if they were not present (i.e. values for config items withnargs == 0
ornargs == "?"
(where theconst
value should be used rather than the value from the dict).The default
none_values
is[None, multiconfparse.MENTIONED_WITHOUT_VALUE]
. usingnone_values=[multiconfparse.MENTIONED_WITHOUT_VALUE]
is useful if you wantNone
to be treated as a valid config value.priority
(optional, keyword): The priority for the source. The default priority for adict
source is0
.
Creating your own source classes¶
To create your own source class, create a subclass of Source
:
-
class
multiconfparse.
Source
(priority=0) Abstract base for classes that parse config sources.
All config source classes should inherit from
Source
, have aname
class attribute containing the name of the source, and provide an implementation for theparse_config()
method.-
parse_config
() Read the values of config items for this source.
This is an abstract method that subclasses must implement to return a
Namespace
object where:The returned
Namespace
has an attribute for each config item found. The name of the attribute for a config item must be the config item’sname
as specified by thename
attribute of itsAction
.The value for each attribute is a list, where each element of the list is a value given for the config item in the source. The elements should be ordered so that values appearing earlier in the source are earlier in the list. In the common case where only a single value for the config item is given in the source, the attribute’s value should be a list with a single element.
For example, if
config_item1
is mentioned in the source once with value"v1"
andconfig_item2
is mentioned in the source twice with values"v2"
and then"v3"
, the returnedNamespace
object would have an attributeconfig_item1
with value["v1"]
and an attributeconfig_item2
with value["v2", "v3"]
.If a config item with
nargs == 0
ornargs == "?"
is mentioned in the source without a value (or possibly with a source-specific value that meansNone
/null
for sources where a value must always be given for a config item), the value for that mention of the config item should be given in the list of values asMENTIONED_WITHOUT_VALUE
.If a config item with
nargs == None
,nargs == 1
ornargs == "?"
is mentioned in the source with a value, the value for that mention of the config item should be given in the list of values as the value itself.If a config item with
nargs >= 2
,nargs == "*"
ornargs == "+"
is mentioned in the source, the value for that mention of the config item should be given in the list of values as a list of the values/arguments given in that mention.For example, if a config item
config_item1
withnargs == 2
appears in the source first with values/arguments of"v1a"
and"v1b"
and then again with values/arguments of"v2a"
and"v2b"
, theconfig_item1
attribute in theNamespace
should have a value of[["v1a", "v1b"], ["v2a", "v2b"]]
.None of the values returned should yet have been coerced into the types specified by the user in
ConfigParser.add_config()
.
-