avocado.core.future package

Submodules

avocado.core.future.settings module

This module is a new and experimental configuration handler.

This will handle both, command line args and configuration files. Settings() = configparser + argparser

Settings() is an attempt to implement part of BP001 and concentrate all default values in one place. This module will read the Avocado configuration options from many sources, in the following order:

  1. Default values: This is a “source code” defined. When plugins or core needs a settings, basically needs to call settings.register_option() with default value as argument. Developers only need to register the default value once, here when calling this methods.
  2. User/System configuration files (/etc/avocado or ~/.avocado/): This is configured by the user, on a more “permanent way”.
  3. Command-line options parsed in runtime. This is configured by the user, on a more “temporary way”;

ATTENTION: This is a future module, and will be moved out from this package soon.

exception avocado.core.future.settings.ConfigFileNotFound(path_list)

Bases: avocado.core.future.settings.SettingsError

Error thrown when the main settings file could not be found.

class avocado.core.future.settings.ConfigOption(namespace, help_msg, key_type=<class 'str'>, default=None, parser=None, short_arg=None, long_arg=None, positional_arg=False, choices=None, nargs=None, metavar=None, required=None, action=None)

Bases: object

action
add_argparser(parser, long_arg, short_arg=None, positional_arg=False, choices=None, nargs=None, metavar=None, required=None, action=None)

Add an command-line argparser to this option.

arg_parse_args
argparse_type
key
metavar
name_or_tags
section
set_value(value, convert=False)
value
exception avocado.core.future.settings.DuplicatedNamespace

Bases: avocado.core.future.settings.SettingsError

Raised when a namespace is already registered.

exception avocado.core.future.settings.NamespaceNotRegistered

Bases: avocado.core.future.settings.SettingsError

Raised when a namespace is not registered.

class avocado.core.future.settings.Settings

Bases: object

Settings, an experimental Avocado configuration handler.

It is a simple wrapper around configparser and argparse.

Also, one object of this class could be passed as config to plugins and modules.

Basically, if you are going to have options (configuration options), either via config file or via command line, you should use this class. You don’t need to instantiate a new settings, just import and use register_option().

from avocado.core.future.settings import settings settings.register_option(…)

And when you needs get the current value, check on your configuration for the namespace (section.key) that you registered. i.e:

value = config.get(‘a.section.with.subsections.key’)

Note

Please, do not use a default value when using get() here. If you are using an existing namespace, get will always return a value, either the default value, or the value set by the user.

Please, note that most of methods and attributes here are private. Only public methods and attributes should be used outside this module.

Constructor. Tries to find the main settings files and load them.

add_argparser_to_option(namespace, parser, long_arg, short_arg=None, positional_arg=False, choices=None, nargs=None, metavar=None, required=None, action=None, allow_multiple=False)

Add a command-line argument parser to an existing option.

This method is useful to add a parser when the option is registered without any command-line argument options. You should call the “register_option()” method for the namespace before calling this method.

Arguments

namespace : str
What is the namespace of the option (section.key)
parser : argparser parser
Since that you would like to have a command-line option, you should specify what is the parser or parser group that we should add this option.
long_arg: : str
A long option for the command-line. i.e: –debug for debug.
short_arg : str
A short option for the command-line. i.e: -d for debug.
positional_arg : bool
If this option is an positional argument or not. Default is False.
choices : tuple
If you would like to limit the option to a few choices. i.e: (‘foo’, ‘bar’)
nargs : int or str
The number of command-line arguments that should be consumed. Could be a int, ‘?’, ‘*’ or ‘+’. For more information visit the argparser documentation.
metavar : str
String presenting available sub-commands in help, if None we will use the section+key as metavar.
required : bool
If this is a required option or not when on command-line. Default is False.
action :
The basic type of action to be taken when this argument is encountered at the command line. For more information visit the argparser documentation.
allow_multiple :
Whether the same option may be available on different parsers. This is useful when the same option is available on different commands, such as “avocado run” or “avocado list”.
as_dict()

Return an dictionary with the current active settings.

This will return a dict with all parsed options (either via config file or via command-line).

as_full_dict()
as_json()

Return a JSON with the current active settings.

This will return a JSON with all parsed options (either via config file or via command-line).

merge_with_arguments(arg_parse_config)

Merge the current settings with the command-line args.

After parsing argument options this method should be executed to have an unified settings.

Parameters:arg_parse_config – argparse.config dictionary with all command-line parsed arguments.
merge_with_configs()

Merge the current settings with the config file options.

After parsing config file options this method should be executed to have an unified settings.

process_config_path(path)

Update list of config paths and process the given path.

register_option(section, key, default, help_msg, key_type=<class 'str'>, parser=None, positional_arg=False, short_arg=None, long_arg=None, choices=None, nargs=None, metavar=None, required=False, action=None, allow_multiple=False)

Method used to register a configuration option inside Avocado.

This should be used to register a settings option (either config file option or command-line option). This is the central point that plugins and core should use to register a new configuration option.

This method will take care of the ‘under the hood dirt’, registering the configparse option and, if desired, the argparse too. Instead of using argparse and/or configparser, Avocado’s contributors should use this method.

Using this method, you need to specify a “section”, “key”, “default” value and a “help_msg” always. This will create a relative configuration file option for you.

For instance:

settings.reigster_option(section=’foo’, key=’bar’, default=’hello’,
help_msg=’this is just a test’)

This will register a ‘foo.bar’ namespace inside Avocado internals settings. And this could be now, be changed by the users or system configuration option:

[foo] bar = a different message replacing ‘hello’

If you would like to provide also the flexibility to the user change the values via command-line, you should pass the other arguments.

Arguments

section : str
The configuration file section that your option should be present. You can specify subsections with dots. i.e: run.output.json
key : str
What is the key name of your option inside that section.
default : typeof(key_type)
What is the default value of your option if the key is not present inside the section on all configuration files.
help_msg : str
The help message that will be displayed at command-line (-h) and configuration file template.
key_type : any method
What is the type of your option? Currently supported: int, list, str or a custom method. Default is str.
parser : argparser parser
Since that you would like to have a command-line option, you should specify what is the parser or parser group that we should add this option.
positional_arg : bool
If this option is an positional argument or not. Default is False.
short_arg : str
A short option for the command-line. i.e: -d for debug.
long_arg: : str
A long option for the command-line. i.e: –debug for debug.
choices : tuple
If you would like to limit the option to a few choices. i.e: (‘foo’, ‘bar’)
nargs : int or str
The number of command-line arguments that should be consumed. Could be a int, ‘?’, ‘*’ or ‘+’. For more information visit the argparser documentation.
metavar : str
String presenting available sub-commands in help, if None we will use the section+key as metavar.
required : bool
If this is a required option or not when on command-line. Default is False.
action :
The basic type of action to be taken when this argument is encountered at the command line. For more information visit the argparser documentation.
allow_multiple :
Whether the same option may be available on different parsers. This is useful when the same option is available on different commands, such as “avocado run” or “avocado list”.

Note

Most of the arguments here (like parser, positional_arg, short_arg, long_arg, choices, nargs, metavar, required and action) are only necessary if you would like to add a command-line option.

update_option(namespace, value, convert=False)

Convenient method to change the option’s value.

This will update the value on Avocado internals and if necessary the type conversion will be realized.

For instance, if an option was registered as bool and you call:

settings.register_option(namespace=’foo.bar’, value=’true’,
convert=True)

This will be stored as True, because Avocado will get the ‘key_type’ registered and apply here for the conversion.

This method is useful when getting values from config files where everything is stored as string and a conversion is needed.

Arguments

namespace : str
Your section plus your key, separated by dots. The last part of the namespace is your key. i.e: run.outputs.json.enabled (section is run.outputs.json and key is enabled)
value : any type
This is the new value to update.
convert : bool
If Avocado should try to convert the value and store it as the ‘key_type’ specified during the register. Default is False.
exception avocado.core.future.settings.SettingsError

Bases: Exception

Base settings error.

Module contents