Sources¶

The built-in sources are:

`argparse`¶

class multiconfparse.ArgparseSource(actions, priority=20)

Obtains config values from an argparse.ArgumentParser.

Do not create ArgparseSource objects directly, add them to a ConfigParser object using 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")
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 an argparse.ArgumentParser for you. This is to allow extra command line arguments to be added to an argparse.ArgumentParser that are not config items. Instead ArgparseSource, which implements the argparse source provides two methods to provide communication with the argparse.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 the argparse.Namespace object returned by argparse.ArgumentParser.parse_args().

If you don’t need to add command line arguments other than for config items, see SimpleArgparseSource which implements the simple_argparse source.

The arguments of ConfigParser.add_source() for the argparse source are:

source (required, positional): "argparse"
priority (optional, keyword): The priority for the source. The default priority for an argparse source is 20.

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(actions, 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 the argparse 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 the simple_argparse source are:

source (required, positional): "simple_argparse"
argument_parser_class (optional, keyword): a class derived from argparse.ArgumentParser to use instead of ArgumentParser itself. This can be useful if you want to override argparse.ArgumentParser.exit() or argparse.ArgumentParser.error().
priority (optional, keyword): The priority for the source. The default priority for a simple_argparse source is 20.
Extra keyword arguments to pass to argparse.ArgumentParser. E.g. prog, allow_help. Don’t use the argument_default option though - the simple_argparse sources sets this internally. See the config_default option for ConfigParser 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(actions, none_values=None, priority=10, env_var_prefix='', env_var_force_upper=True)

Obtains config values from the environment.

Do not create EnvironmentSource objects directly, add them to a ConfigParser object using ConfigParser.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 the environment 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 with nargs == 0 or nargs == "?" (where the const value should be used rather than the value from the dict).

The default none_values is [""]. using a different value for none_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 an environment source is 10.
env_var_prefix (optional, keyword): a string prefixed to the environment variable names that the source will look for. The default value is "".
env_var_force_upper (optional, keyword): force the environment variable name to be in upper case. Default is True.

Note that:

Values in environment variables for config items with nargs == 0 or nargs == "?" (where the const value should be used rather than the value from the environment variable) should be values from the none_values list described above.
Values in environment variables for config items with nargs >= 2, nargs == "+" or nargs == "*" are split into arguments by shlex.split() (i.e. like arguments given on a command line via a shell). See the shlex documentation for full details.

`json`¶

class multiconfparse.JsonSource(actions, 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() for json sources are:

source (required, positional): "json".
priority (optional, keyword): The priority for the source. The default priority for a json source is 0.
path (optional, keyword): path to the JSON file to parse. Exactly one of the path and fileobj options must be given.
fileobj (optional keyword): a file object representing a stream of JSON data. Exactly one of the path and fileobj 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 with nargs == 0 or nargs == "?" (where the const value should be used rather than the value from the dict). The default none_values is [].
json_none_values (optional, keyword): a list of JSON values (as strings) that are decoded into Python values and added to none_values. The default json_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 or nargs == "?" (where the const value should be used rather than the value from the dict) should either have values from the json_none_values list or should decode to values in the none_values list.
Fields in the JSON object for config items with nargs >= 2, nargs == "+" or nargs == "*" should be JSON arrays with an element for each argument of the config item.

In the special case where nargs == "+" or nargs == "*" 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(actions, values_dict, none_values=None, priority=0)

Obtains config values from a Python dict object.

Do not create DictSource objects directly, add them to a ConfigParser object using 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")

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 the dict source are:

source (required, positional): "dict".
values_dict (required, positional): the dict containing the config values.

Note that:
- Values in values_dict for config items with nargs == 0 or nargs == "?" (where the const value should be used rather than the value from the dict) should be values from the none_values list described below.
- Values in values_dict for config items with nargs >= 2, nargs == "+" or nargs == "*" should be list objects with an element for each argument of the config item.
  
  In the special case where nargs == "+" or nargs == "*" and there is a single argument for the config item, the value may be given without the enclosing list, unless the argument is itself a list.
none_values (optional, keyword): a list of values that, when seen in values_dict, should be treated as if they were not present (i.e. values for config items with nargs == 0 or nargs == "?" (where the const value should be used rather than the value from the dict).

The default none_values is [None]. Using a different none_values is useful if you want None to be treated as a valid config value.
priority (optional, keyword): The priority for the source. The default priority for a dict source is 0.

Creating your own source classes¶

To create your own source class, create a subclass of Source:

class multiconfparse.Source(actions, priority=0)

Abstract base for classes that parse config sources.

All config source classes should:

Inherit from Source.
Have a source_name class attribute containing the name of the source.
Provide an implementation for the parse_config() method.
Have an __init__() method that forwards its actions and priority arguments to Source.__init__(). Source.__init__() will create actions and priority attributes to make them available to subclass methods.

actions is a dict with config item names as the keys and Action objects as the values. The Action attributes that are most useful for source classes to use are:
- name: the name of the config item to which the Action applies. The source class should use this to determine which Action object corresponds with each config item mention in the source. The name atribute of an Action has the same value as the key in the actions dict.
- nargs: this specifies the number of arguments/values that a config item should have when mentioned in the source.

parse_config()

Read the values of config items for this source.

This is an abstract method that subclasses must implement to return a list containing a ConfigMention element for each config item mentioned in the source, in the order in which they appear (unless order makes no sense for the source).

The implementation of this method will need to make use of the actions and priority attributes created by the Action base class.

class ConfigMention(action, args, priority)

A ConfigMention object represents a single mention of a config item in a source.

The arguments are:

action: the Action object that corresponds with the config item being mentioned.
args: a list of arguments that accompany the config item mention.
priority: the priority of the mention. Generally, this is the same as the priority of the Source object that found the mention.

Sources¶

argparse¶

simple_argparse¶

environment¶

json¶

dict¶

Creating your own source classes¶

`argparse`¶

`simple_argparse`¶

`environment`¶

`json`¶

`dict`¶