common.config.config module
This sub-module holds the classes for the configuration management.
The Config
class plays the central role. It uses az array of ConfigEntry
instances to
define the list of config parameters, incl. their names and default values.
Each ConfigEntry
has its own CliEntry
property, which describes the command-line related
counterparts of the config parameters.
This module is responsible for giving default values to the config parameters, evaulate the environment variables and command-line parameters, and applies them to the config variables.
The precedence is the following, in ascending order (command-line is the strongest): - default value, - environment variable, - command-line parameter.
- class common.config.config.CliEntry(short_flag=None, name=None, entry_type=<class 'str'>, action='store', choices=None)
Bases:
object
It is the command-line entry descriptor data-class.
It holds the details of a ConfigEntry about how to setup the command-line arg parser.
NOTE: The properties hold by this class are strongly related to the argparse package.
Example:
cli_entry = CliEntry( short_flag="-d", name="--dump-config", entry_type=bool, action="store_true")
- __init__(short_flag=None, name=None, entry_type=<class 'str'>, action='store', choices=None)
- short_flag: str
Defines the short name of an optional CLI argument, for example:
-f
- name: str
Defines the name of an optional command-line argument, for example:
--file-name
- entry_type: type
The type of the argument, e.g.
int
,float
. See also: the argparse docs / type
- action: str
It specifies how the command-line argument should be handled. See also: the argparse docs / action
- choices: list
The list of possible choices, in case the value can be chosen from a predefined set.
- class common.config.config.ConfigEntry(name=None, help_text='', default=None, cli=None)
Bases:
object
Config parameter descriptor data-class
Example:
ConfigEntry( name="LOG_LEVEL", help_text=f"Log level {get_level_choices()}", default="info", cli=CliEntry(short_flag="-l", name="--log-level", choices=get_level_choices()), )
- __init__(name=None, help_text='', default=None, cli=None)
- name: str
The name of the config parameter.
Usually this is the name of the environment variable may be used accompanied with the command-line parameter. It should be ALL-CAPS.
- help_text: str
The short description of the config parameter, that will be displayed to the console when the
--help
switch is used for the application.
- default: str
The default value of the config parameter.
The config parameter always has default value, that can be overwritten either by the value of the environment variable with the same name, if exists and/or the command-line parameter.
- cli: common.config.config.CliEntry
The definition of the command-line argument entry, if there is any.
If given, it defines the hints of the command-line optional argument counterpart of the config parameter. Before parsing of the command line parameters, each parameter will be initialized with the actual value of the corresponding config parameter, using the built-in default value, then applying the environment variable.
- class common.config.config.Config(app_name, app_description, config_entries)
Bases:
object
Configuration class that represent the actual config parameter set of the application. The class provides method for resolving the config parameters from env variables as well as from CLI parameters.
- __init__(app_name, app_description, config_entries)
Constructor for the application config.
- Parameters
app_name (str) – The name of the application.
app_description (str) – The short description of the application.
config_entries (Array[ConfigEntry]) – The array of the definitions of config entries.
It fills the object with the properties given by the config_entries argument. It also sets the initial value of each parameter from the environment, if it is found or set to its default value if the corresponding environment var is missing.
- apply_parameters(parameters)
Overwrites the actual values of the configuration properties with the values given by the parameters dictionary. Typical usage is, when the CLI argument parser wants to overwrite the default, or environment values.
- Parameters
parameters (dict) – The dictionary of parameters, that have to be applied to the actual set of configuration parameters. The keys in the
parameters
must fit to the names in the configuration object.
- apply_cli_args(argv)
Take the actual CLI parameters according to the definitions in self.config_entries parse them, and apply them to the actual properties of the config object.
- Parameters
argv (Array[str]) – The command line parameters.
- get(name)
Get the value of a config parameter by its name.
- Parameters
name (str) – The name of the config parameter
- Returns
The value of the config parameter found, or
None
, if not found.
- get_the_cli_args(argv)
Parse the CLI parameters, and returns with them as a dictionary
- Parameters
argv (Array[str]) – The command-line parameters
- dump()
Prints the actual values of the config parameters to the console