Actions

The built-in actions are:

store

class multiconfparse.StoreAction(const=None, **kwargs)

The store action simply stores the value from the highest priority mention of a config item. Its behaviour is based on the store argparse action and is the default action.

Arguments to ConfigParser.add_config() have standard behaviour, but note:

  • nargs == 0 is not allowed. The default nargs value is None.
  • The const argument is only accepted when nargs == "?".

Examples:

parser = multiconfparse.ConfigParser()
parser.add_config("config_item1")
parser.add_source("dict", {"config_item1": "v1"}, priority=2)
parser.add_source("dict", {"config_item1": "v2"}, priority=1)
parser.parse_config()
# -> multiconfparse.Namespace {
#   "config_item1": "v1",
# }

parser = multiconfparse.ConfigParser()
parser.add_config("config_item1", nargs=2, type=int, default=[1, 2])
parser.add_source("simple_argparse")
parser.parse_config()
#
# If the command line looks something like:
#   prog some-arg --config-item1 3 4
# parse_config() will return something like:
#   multiconfparse.Namespace {
#       "config_item1": [3, 4],
#   }
#
# If the command line looks something like:
#   prog some-arg
# parse_config() will return something like:
#   multiconfparse.Namespace {
#       "config_item1": [1, 2],
#   }

store_const

class multiconfparse.StoreConstAction(const, **kwargs)

The store_const action stores the value from the const argument whenever a config item is mentioned in a source. Its behaviour is based on the store_const argparse action.

Notes about the arguments to ConfigParser.add_config():

  • The const argument is mandatory.
  • nargs is not accepted as an argument. nargs is always 0 for store_const actions.
  • required is not accepted as an argument. required is always False for store_const actions.
  • type is not accepted as an argument - it doesn’t make sense for store_const.
  • choices is not accepted as an argument - it doesn’t make sense for store_const.

Example:

parser = multiconfparse.ConfigParser()
parser.add_config(
    "config_item1",
    action="store_const",
    const="yes",
    default="no"
)
parser.add_source("dict", {"config_item1": None})
parser.parse_config()
# -> multiconfparse.Namespace {
#   "config_item1": "yes",
# }

store_true

class multiconfparse.StoreTrueAction(default=False, **kwargs)

The store_true action simply stores the value True whenever a config item is mentioned in a source. Its behaviour is based on the store_true argparse action.

Notes about the arguments to ConfigParser.add_config():

  • const is not accepted as an argument - const is always True for store_true actions.
  • nargs is not accepted as an argument. nargs is always 0 for store_true actions.
  • required is not accepted as an argument. required is always False for store_true actions.
  • type is not accepted as an argument - it doesn’t make sense for store_true.
  • choices is not accepted as an argument - it doesn’t make sense for store_true.
  • The default value for the default argument is False.

Examples:

parser = multiconfparse.ConfigParser()
parser.add_config("config_item1", action="store_true")
parser.add_source("dict", {"config_item1": None})
parser.parse_config()
# -> multiconfparse.Namespace {
#   "config_item1": True,
# }

parser = multiconfparse.ConfigParser()
parser.add_config("config_item1", action="store_true")
parser.parse_config()
# -> multiconfparse.Namespace {
#   "config_item1": False,
# }

store_false

class multiconfparse.StoreFalseAction(default=True, **kwargs)

The store_false action simply stores the value False whenever a config item is mentioned in a source. Its behaviour is based on the store_false argparse action.

Notes about the arguments to ConfigParser.add_config():

  • const is not accepted as an argument - const is always False for store_false actions.
  • nargs is not accepted as an argument. nargs is always 0 for store_false actions.
  • required is not accepted as an argument. required is always False for store_false actions.
  • type is not accepted as an argument - it doesn’t make sense for store_false.
  • choices is not accepted as an argument - it doesn’t make sense for store_false.
  • The default value for the default argument is True.

Examples:

parser = multiconfparse.ConfigParser()
parser.add_config("config_item1", action="store_false")
parser.add_source("dict", {"config_item1": None})
parser.parse_config()
# -> multiconfparse.Namespace {
#   "config_item1": False,
# }

parser = multiconfparse.ConfigParser()
parser.add_config("config_item1", action="store_false")
parser.parse_config()
# -> multiconfparse.Namespace {
#   "config_item1": True,
# }

append

class multiconfparse.AppendAction(const=None, default=NOT_GIVEN, **kwargs)

The append action stores the value for each mention of a config item in a list. The list is sorted according to the priorities of the mentions of the config item, lower priorities first. The Behaviour is based on the append argparse action.

Notes about the arguments to ConfigParser.add_config():

  • nargs == 0 is not allowed. The default nargs value is None.

    When nargs >= 1, nargs == "+" or nargs == "*", each value in the list for the config item is itself a list containing the arguments for a mention of the config item.

  • The const argument is only accepted when nargs == "?".

  • The default argument (if it is given and is not SUPPRESS) is used as the initial list of values. This means that the default value is incorporated into the final value for the config item, even if the config item is mentioned in a source.

Examples:

parser = multiconfparse.ConfigParser()
parser.add_config("config_item1", action="append", default=["v1"])
parser.add_source("dict", {"config_item1": "v2"}, priority=2)
parser.add_source("dict", {"config_item1": "v3"}, priority=1)
parser.parse_config()
# -> multiconfparse.Namespace {
#   "config_item1": ["v1", "v3", "v2"],
# }

parser = multiconfparse.ConfigParser()
parser.add_config(
    "config_item1",
    action="append",
    nargs="?",
    const="v0",
)
parser.parse_config()
parser.add_source("dict", {"config_item1": "v1"}, priority=2)
parser.add_source("dict", {"config_item1": None}, priority=1)
# -> multiconfparse.Namespace {
#   "config_item1": ["v0", "v1"],
# }

count

class multiconfparse.CountAction(**kwargs)

The count action stores the number of times a config item is mentioned in the config sources. Its behaviour is based on the count argparse action.

Notes about the arguments to ConfigParser.add_config():

  • nargs is not accepted as an argument. nargs is always 0 for count actions.

  • const is not accepted as an argument - it doesn’t make sense for count.

  • required is not accepted as an argument. required is always False for count actions.

  • type is not accepted as an argument - it doesn’t make sense for count.

  • choices is not accepted as an argument - it doesn’t make sense for count.

  • If the default argument is given and is not SUPPRESS, it acts as the initial value for the count. I.e. the final value for the config item will be the number of mentions of the config item in the sources, plus the value of default.

    Note that if the config item is not found in any sources and default is not given, it is not assumed to be 0. The final value for the config item would be None in this case.

Examples:

parser = multiconfparse.ConfigParser()
parser.add_config("config_item1", action="count")
parser.add_source("dict", {"config_item1": None})
parser.add_source("dict", {"config_item1": None})
parser.parse_config()
# -> multiconfparse.Namespace {
#   "config_item1": 2,
# }

parser = multiconfparse.ConfigParser()
parser.add_config("config_item1", action="count", default=10)
parser.add_source("dict", {"config_item1": None})
parser.add_source("dict", {"config_item1": None})
parser.parse_config()
# -> multiconfparse.Namespace {
#   "config_item1": 12,
# }

parser = multiconfparse.ConfigParser()
parser.add_config("config_item1", action="count")
parser.parse_config()
# -> multiconfparse.Namespace {
#   "config_item1": None,
# }

extend

class multiconfparse.ExtendAction(**kwargs)

The extend action stores the value for each argument of each mention of a config item in a list. The list is sorted according to the priorities of the mentions of the config item, lower priorities first. The Behaviour is based on the extend argparse action, although the behaviour when nargs == None or nargs == "?" is different.

Notes about the arguments to ConfigParser.add_config():

  • nargs == 0 is not allowed. The default nargs value is “+”.

    Unlike the append action, when nargs >= 1, nargs == "+" or nargs == "*", each value in the list for the config item is not itself a list containing the arguments for a mention of the config item. Each argument of each mention is added separately to the list that makes the final value for the config item.

    Unlike the argparse extend action, when nargs == None or nargs == "?", the multiconfparse extend action behaves exactly like the append action.

  • The const argument is only accepted when nargs == "?".

  • The default argument (if it is given and is not SUPPRESS) is used as the initial list of values. This means that the default value is incorporated into the final value for the config item, even if the config item is mentioned in a source.

Example:

parser = multiconfparse.ConfigParser()
parser.add_config(
    "config_item1",
    action="extend",
    default=[["v1", "v2"]]
)
parser.add_source("dict", {"config_item1": ["v3", "v4"]}, priority=2)
parser.add_source("dict", {"config_item1": ["v5"]}, priority=1)
parser.parse_config()
# -> multiconfparse.Namespace {
#   "config_item1": ["v1", "v2", "v5", "v3", "v4"],
# }

Creating your own action classes

To create your own action class, create a subclass of Action:

class multiconfparse.Action(name, dest=None, nargs=None, type=<class 'str'>, required=False, default=NOT_GIVEN, choices=None, help=None, include_sources=None, exclude_sources=None)

Abstract base class config actions.

Classes to support actions should:

  • Inherit from Action.

  • Implement the __call__() method documented below.

  • Have an action_name class attribute set to the name of the action that the class implements.

  • Have an __init__() method that accepts arguments passed to ConfigParser.add_config() calls by the user (except the action argument) and which calls Action.__init__() with any of those arguments which are not specific to the action handled by the class. I.e.:

    • name;
    • nargs;
    • type;
    • required;
    • default;
    • choices;
    • help;
    • dest;
    • include_sources;
    • exclude_sources.

    These arguments will be assigned to attributes of the Action object being created (perhaps after some processing or validation) that are available for access by subclasses. The names of the attributes are the same as the argument names.

    It is recommended that passing the arguments to Action.__init__() is done by the subclass __init__ method accepting a **kwargs argument to collect any arguments that are not used or modified by the action class, then passing that **kwargs argument to Action.__init__(). The action class may also want pass some arguments that aren’t specified by the user if the value of those arguments is implied by the action. For example, the store_const action class has the following __init__ method:

    def __init__(self, const, **kwargs):
    super().__init__(
        nargs=0,
        type=None,
        required=False,
        choices=None,
        **kwargs,
    )
    self.const = const

    This ensures that an exception is raised if the user specifies nargs, type, required, or choices arguments when adding a store_const action because if the user specifies those arguments they will be given twice in the call to Action.__init__().

__call__(namespace, args)

Combine the arguments from a mention of this config with any existing value.

This method is called once for each mention of the config item in the sources in order to combine the arguments from the mention with any existing value.

namespace will be the same Namespace object for all calls to this function during a ConfigParser.parse_config() call, and it is used to hold the so-far-accumulated value for the config item mentions.

This method’s purpose is to combine the current value for this config item in namespace with the values in the new argument, and write the combined value into back into namespace.

The first time this method is called, if the config item has a default value, namespace will have an attribute for the config item and it will contain the default value; otherwise namespace will not have an attribute for the config item.

After the first call to this method, namespace should have an attribute value for the config item set by the previous call.

Notes:

  • The name of the attribute in namespace for this config item is given by this object’s dest attribute.
  • The calls to this method are made in order of the priorities of the config item mentions in the sources, lowest priority first.
  • The values in new have already been coerced to the config item’s type.
  • The values in new have already been checked for choices validity.
  • The number of values in new has already been checked for nargs validity.
  • If no arguments for the config item were given, new will just be an empty list.

For example, the __call__() method for the append action is:

def __call__(self, namespace, args):
    current = getattr(namespace, self.dest, [])
    if self.nargs == "?" and not args:
        current.append(self.const)
    elif self.nargs is None or self.nargs == "?":
        assert len(args) == 1
        current.extend(args)
    else:
        current.append(args)
    setattr(namespace, self.dest, current)

The full example of the class for the store_const action is:

class StoreConstAction(Action):
    action_name = "store_const"

    def __init__(self, const, **kwargs):
        super().__init__(
            nargs=0,
            type=None,
            required=False,
            choices=None,
            **kwargs,
        )
        self.const = const

        def __call__(self, namespace, args):
            assert not args
            setattr(namespace, self.dest, self.const)