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:
- 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.
- User/System configuration files (/etc/avocado or ~/.avocado/): This is configured by the user, on a more “permanent way”.
- 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.
Error thrown when the main settings file could not be found.
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)¶
Raised when a namespace is already registered.
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’)
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.
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).
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 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 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.
- 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.
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’,
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.