icat.config — Manage configuration

This module reads configuration variables from different sources, such as command line arguments, environment variables, and configuration files. A set of configuration variables that any ICAT client program typically needs is predefined. Custom configuration variables may be added. The main class that client programs interact with is icat.config.Config.

icat.config.cfgdirs

Search path for the configuration file. The value depends on the operating system.

icat.config.cfgfile = 'icat.cfg'

Configuration file name

icat.config.defaultsection = None

Default value for configSection

icat.config.boolean(value)

Test truth value.

Convert the string representation of a truth value, such as 0, 1, yes, no, true, or false to bool. This function is suitable to be passed as type to icat.config.Config.add_variable().

icat.config.flag

Variant of icat.config.boolean() that defines two command line arguments to switch the value on and off respectively. May be passed as type to icat.config.Config.add_variable().

class icat.config.Configuration(config)

Bases: object

Provide a name space to store the configuration.

icat.config.Config.getconfig() returns a Configuration object having the configuration values stored in the respective attributes.

as_dict()

Return the configuration as a dict.

class icat.config.Config(needlogin=True, ids=False)

Bases: object

Set configuration variables.

Allow configuration variables to be set via command line arguments, environment variables, configuration files, and default values, in this order. The first value found will be taken. Command line arguments and configuration files are read using the standard Python library modules argparse and ConfigParser respectively, see the documentation of these modules for details on how to setup custom arguments or for the format of the configuration files.

ReservedVariables = ['configDir', 'client_kwargs', 'credentials']

Reserved names of configuration variables.

add_variable(name, arg_opts=(), arg_kws={}, envvar=None, optional=False, default=None, type=None, subst=False)

Defines a new configuration variable.

Call argparse.ArgumentParser.add_argument() to add a new command line argument if arg_opts is set.

Parameters:

• name (str) – the name of the variable. This will be used as the name of the attribute of icat.config.Configuration returned by icat.config.Config.getconfig() and as the name of the option to be looked for in the configuration file. The name must be unique and not in icat.config.Config.ReservedVariables. If arg_opts corresponds to a positional argument, the name must be equal to this argument name.
• arg_opts (tuple of str) – command line flags associated with this variable. This will be passed as name or flags to argparse.ArgumentParser.add_argument().
• arg_kws (dict) – keyword arguments to be passed to argparse.ArgumentParser.add_argument().
• envvar (str) – name of the environment variable or None. If set, the value for the variable may be set from the respective environment variable.
• optional (bool) – flag wether the configuration variable is optional. If set to False and default is None the variable is mandatory.
• default – default value.
• type (callable) – type to which the value should be converted. This must be a callable that accepts one string argument and returns the desired value. The builtins int() and float() are fine. If set to None, the string value is taken as is. If applicable, the default value will also be passed through this conversion. The special value of icat.config.flag may also be used to indicate a variant of icat.config.boolean().
• subst (bool) – flag wether substitution of other configuration variables using the % interpolation operator shall be performed. If set to True, the value may contain conversion specifications such as %(othervar)s. This will then be substituted by the value of othervar. The referenced variable must have been defined earlier.

Raises ValueError:  

if the name is not valid.

See :

the documentation of the argparse standard library module for details on arg_opts and arg_kws.

getconfig(args=None)

Get the configuration.

Parse the command line arguments, evaluate environment variables, read the configuration file, and apply default values (in this order) to get the value for each defined configuration variable. The first defined value found will be taken.

Parameters:args (list of str) – list of command line arguments or None. If not set, the command line arguments will be taken from sys.argv. Returns:an object having the configuration values set as attributes. Return type:icat.config.Configuration Raises ConfigError:  if configFile is defined but the file by this name can not be read, if configSection is defined but no section by this name could be found in the configuration file, if an invalid value is given to a variable, or if a mandatory variable is not defined.

Predefined configuration variables

The constructor of icat.config.Config sets up the following set of configuration variables that an ICAT client typically needs:

configFile

Name of the configuration file to read.

configSection

Name of the section in the configuration file to apply. If not set, no values will be read from the configuration file.

url

URL to the web service description of the ICAT server.

idsurl

URL to the ICAT Data Service.

checkCert

Verify the server certificate for HTTPS connections. Note that this requires either Python 2.7.9 or 3.2 or newer. With older Python version, this option has no effect.

http_proxy

Proxy to use for HTTP requests.

https_proxy

Proxy to use for HTTPS requests.

no_proxy

Comma separated list of domain extensions proxy should not be used for.

auth

Name of the authentication plugin to use for login.

username

The ICAT user name.

password

The user’s password. Will prompt for the password if not set.

promptPass

Prompt for the password.

A few derived variables are also set in icat.config.Config.getconfig():

configDir

the directory where (the last) configFile has been found.

client_kwargs

contains the proxy settings and other configuration that should be passed as the keyword arguments to the constructor of icat.client.Client.

credentials

contains username and password suitable to be passed to icat.client.Client.login().

The command line arguments, environment variables, and default values for the configuration variables are as follows:

name	command line	environment	default	mandatory
configFile	-c, --configfile	ICAT_CFG	depends	no
configSection	-s, --configsection	ICAT_CFG_SECTION	None	no
url	-w, --url	ICAT_SERVICE		yes
idsurl	--idsurl	ICAT_DATA_SERVICE	None	depends
checkCert	--check-certificate, --no-check-certificate		True	no
http_proxy	--http-proxy	http_proxy	None	no
https_proxy	--https-proxy	https_proxy	None	no
no_proxy	--no-proxy	no_proxy	None	no
auth	-a, --auth	ICAT_AUTH		yes
username	-u, --user	ICAT_USER		yes
password	-p, --pass		None	no
promptPass	-P, --prompt-pass		False	no

Mandatory means that an error will be raised in icat.config.Config.getconfig() if no value is found for the configuration variable in question.

The default value for configFile depends on the operating system. The default value for configSection may be changed in icat.config.defaultsection.

If the argument needlogin to the constructor of icat.config.Config is set to False, the configuration variables auth, username, password, promptPass, and credentials will be left out. The configuration variable idsurl will not be set up at all, or be set up as a mandatory, or as an optional variable, if the ids argument is set to False, to “mandatory”, or to “optional” respectively.

The method icat.config.Config.getconfig() will prompt the user for a password if promptPass is True, if password is None, or if the username, but not the password has been provided by command line arguments.