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 thestore
argparse
action and is the default action.Arguments to
ConfigParser.add_config()
have standard behaviour, but note:nargs == 0
is not allowed. The defaultnargs
value isNone
.- The
const
argument is only accepted whennargs == "?"
.
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 theconst
argument whenever a config item is mentioned in a source. Its behaviour is based on thestore_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 always0
forstore_const
actions.required
is not accepted as an argument.required
is alwaysFalse
forstore_const
actions.type
is not accepted as an argument - it doesn’t make sense forstore_const
.choices
is not accepted as an argument - it doesn’t make sense forstore_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", # }
- The
store_true
¶
-
class
multiconfparse.
StoreTrueAction
(default=False, **kwargs) The
store_true
action simply stores the valueTrue
whenever a config item is mentioned in a source. Its behaviour is based on thestore_true
argparse
action.Notes about the arguments to
ConfigParser.add_config()
:const
is not accepted as an argument -const
is alwaysTrue
forstore_true
actions.nargs
is not accepted as an argument.nargs
is always0
forstore_true
actions.required
is not accepted as an argument.required
is alwaysFalse
forstore_true
actions.type
is not accepted as an argument - it doesn’t make sense forstore_true
.choices
is not accepted as an argument - it doesn’t make sense forstore_true
.- The default value for the
default
argument isFalse
.
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 valueFalse
whenever a config item is mentioned in a source. Its behaviour is based on thestore_false
argparse
action.Notes about the arguments to
ConfigParser.add_config()
:const
is not accepted as an argument -const
is alwaysFalse
forstore_false
actions.nargs
is not accepted as an argument.nargs
is always0
forstore_false
actions.required
is not accepted as an argument.required
is alwaysFalse
forstore_false
actions.type
is not accepted as an argument - it doesn’t make sense forstore_false
.choices
is not accepted as an argument - it doesn’t make sense forstore_false
.- The default value for the
default
argument isTrue
.
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 alist
. Thelist
is sorted according to the priorities of the mentions of the config item, lower priorities first. The Behaviour is based on theappend
argparse
action.Notes about the arguments to
ConfigParser.add_config()
:nargs == 0
is not allowed. The defaultnargs
value isNone
.When
nargs >= 1
,nargs == "+"
ornargs == "*"
, each value in thelist
for the config item is itself alist
containing the arguments for a mention of the config item.The
const
argument is only accepted whennargs == "?"
.The
default
argument (if it is given and is notSUPPRESS
) is used as the initiallist
of values. This means that thedefault
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 thecount
argparse
action.Notes about the arguments to
ConfigParser.add_config()
:nargs
is not accepted as an argument.nargs
is always0
forcount
actions.const
is not accepted as an argument - it doesn’t make sense forcount
.required
is not accepted as an argument.required
is alwaysFalse
forcount
actions.type
is not accepted as an argument - it doesn’t make sense forcount
.choices
is not accepted as an argument - it doesn’t make sense forcount
.If the
default
argument is given and is notSUPPRESS
, 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 ofdefault
.Note that if the config item is not found in any sources and
default
is not given, it is not assumed to be0
. The final value for the config item would beNone
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 alist
. Thelist
is sorted according to the priorities of the mentions of the config item, lower priorities first. The Behaviour is based on theextend
argparse
action, although the behaviour whennargs == None
ornargs == "?"
is different.Notes about the arguments to
ConfigParser.add_config()
:nargs == 0
is not allowed. The defaultnargs
value is “+”.Unlike the
append
action, whennargs >= 1
,nargs == "+"
ornargs == "*"
, each value in thelist
for the config item is not itself alist
containing the arguments for a mention of the config item. Each argument of each mention is added separately to thelist
that makes the final value for the config item.Unlike the
argparse
extend
action, whennargs == None
ornargs == "?"
, themulticonfparse
extend
action behaves exactly like theappend
action.The
const
argument is only accepted whennargs == "?"
.The
default
argument (if it is given and is notSUPPRESS
) is used as the initiallist
of values. This means that thedefault
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 toConfigParser.add_config()
calls by the user (except theaction
argument) and which callsAction.__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 toAction.__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, thestore_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
, orchoices
arguments when adding astore_const
action because if the user specifies those arguments they will be given twice in the call toAction.__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 sameNamespace
object for all calls to this function during aConfigParser.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 thenew
argument, and write the combined value into back intonamespace
.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; otherwisenamespace
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’sdest
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’stype
. - The values in
new
have already been checked forchoices
validity. - The number of values in
new
has already been checked fornargs
validity. - If no arguments for the config item were given,
new
will just be an emptylist
.
For example, the
__call__()
method for theappend
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 name of the attribute in
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)