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

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.

class avocado.core.future.settings.Settings(config_path=None)

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.

Parameters:config_path – Path to a config file. Useful for unittesting.

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_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.

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)

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 sould pass the other 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 : typle

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.

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 convertion 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.

namespace : str

Your section plus your key, separeted 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