Adding config items

Once you have created your ConfigParser object, you can add specifications of your config items using the ConfigParser.add_config():

ConfigParser.add_config(name, **kwargs)

Add a config item to the ConfigParser.

The arguments that apply to all config items are:

• name (required, positional): the name of the config item.

  In the Namespace object returned by parse_config(), the name of the attribute used for this config item will be name and must be a valid Python identifier.

  name is also used by source Source classes to generate the strings that will be used to find the config in config sources. The Source classes may, use a modified version of name, however. For example, the argparse and simple_argparse sources will convert underscores (_) to hyphens (-) and add a -- prefix, so if a config item had the name "config_item1", the argparse and simple_argparse sources would use the option string "--config-item1".

• action (optional, keyword): the name of the action that should be performed when a config item is found in a config source. The default action is "store", and the built-in actions are described briefly below. See Actions for more detailed information about the built-in actions and creating your own actions. The built-in actions are all based on argparse actions so the argparse documentation may also provide useful information.

  • store: this action just stores the highest priority value for config item.
  • store_const: this stores the value specified in the const argument.
  • store_true: this stores the value True and sets the default argument to False. It is a special case of store_const.
  • store_false: this stores the value False and sets the default argument to True. It is a special case of store_const.
  • append: this creates a list containing every value seen (with lower priority values first). When nargs >= 1, nargs == "+" or nargs == "*", each value in the list s iteself a list containing the arguments for a mention of the config item.
  • count: this stores the number of mentions of the config item.
  • extend: this creates a list containing every value seen (with lower priority values first). Unlike append, when nargs >= 1, nargs == "+" or nargs == "*", arguments for mentions of the config item are not placed in separate sublists for each mention.

• default: the default value for this config item. Note that some actions will incorporate the default value into the final value for the config item even if the config item is mentioned in one of the sources (e.g. append, count and extend).

  Note that the default value for all config items can also be set by passing a value for the config_default argument of ConfigParser. If both the config_default argument to ConfigParser and the default argument to add_config() are used then only the default argument to add_config() is used.

  If a default value is not provided for the config item by the default argument, the config_default argument or by the action class (like e.g. store_true does), then the final value for the config will be None if the config item is not mentioned in any source.

  The special value SUPPRESS can be passed as the default argument. In this case, if the config item is not mentioned in any source, it will not be given an attribute in the Namespace object returned by parse_config().

• dest (optional, keyword): the name of the attribute for the config item in the Namespace object returned by parse_config(). By default, dest is set to the name of the config item (name).

• exclude_sources (optional, keyword): a collection of source names or Source classes that should ignore this config item. This argument is mutually exclusive with include_sources. If neither exclude_sources nor include_sources is given, the config item will be looked for by all sources added to the ConfigParser.

• include_sources (optional, keyword): a collection of source names or Source classes that should look for this config item. This argument is mutually exclusive with exclude_sources. If neither exclude_sources nor include_sources is given, the config item will be looked for by all sources added to the ConfigParser.

• help: the help text/description for the config item. Set this to SUPPRESS to prevent this config item from being mentioned in generated documentation.

The other arguments are all keyword arguments and are passed on to the class that implements the config items action and may have different default values or may not even be valid for all actions. See Actions for action specific documentation.

• nargs: specifies the number of arguments that the config item accepts. The values that nargs can take are:

  • None: the config item will take a single argument.
  • 0: the config item will take no arguments. This value is usually not given to add_config() but may be implicit for an action (e.g. store_const or count).
  • An int N >= 1: the config item will take N arguments and the value for a mention of the config item will be a list containing each argument. In particular, when nargs == 1 the value for each mention of a config item will be a list containing a single element.
  • "?": The config item will take a single optional argument. When the config item is mentioned without an accompanying value, the value for the mention is the value of the config item’s const argument.
  • "*": The config item will take zero or more arguments and the value for a mention of the config item will be a list containing each argument.
  • "+" The config item will take one or more arguments and the value for a mention of the config item will be a list containing each argument.

• const: The value to use for a mention of the config item where there is no accompanying argument. This is only ever used when nargs == 0 or nargs == "+".

• type: The type to which each argument of the config item should be converted. This can be any callable object that takes a single argument (an object with a __call__(self, arg) method), including classes like int and functions that take a single argument. Note that some sources that read typed data may produce config item argument values that aren’t always str objects.

  The default type is str unless that doesn’t make sense (e.g. when nargs == 0.

• required: specifies whether an exception should be raised if a value for this config item cannot be found in any source.

  The default required is False.

• choices: specifies a collection of valid values for the arguments of the config item. If choices is specified, an exception is raised if the config item is mentioned in a source with an argument that is not in choices.