`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

Deprecated since version 1.0.0: Use the preset keyword argument to icat.config.Config instead.

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.BaseConfig.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.BaseConfig.add_variable().

icat.config.cfgpath(p)

Search for a file in some default directories.

The argument p should be a file path name. It will be converted to a Path object. If p is absolute, it will be returned unchanged. Otherwise, p will be resolved against the directories in icat.config.cfgdirs in reversed order. If a file with the resulting path is found to exist, this path will be returned, first match wins. If no file exists in any of the directories, p will be returned unchanged.

In any case, the return value is a Path object.

This function is suitable to be passed as type argument to icat.config.BaseConfig.add_variable().

Changed in version 1.0.0: return a Path object.

class icat.config.ConfigVariable(name, envvar, optional, default, convert, subst)

Bases: object

Describe a configuration variable. Configuration variables are created in icat.config.BaseConfig.add_variable() and control the behavior of icat.config.Config.getconfig().

class icat.config.ConfigSubCmds(name, optional, config, subparsers)

Bases: ConfigVariable

A special configuration variable that selects a subcommand. These subcommand configuration variables are created in icat.config.BaseConfig.add_subcommand(). Possible values for the subcommand are then registered calling the add_subconfig() method.

add_subconfig(name, arg_kws=None, func=None)

Add a comand to a set of subcommands defined with icat.config.BaseConfig.add_subcommands().

Parameters:

name (str) – the name of the command.
arg_kws (dict) – constructor arguments to be passed to argparse.ArgumentParser() to create the subparser. Mostly useful to set help.
func – any custom value. The configuration value representing the subcommands in the icat.config.Configuration object returned by icat.config.Config.getconfig() will have an attribute func with this value if this command has been selected. Most useful to set this to a callable that implements the command.

Returns:

a subconfig object that allows to set specific configuration variables for the command.

Return type:

icat.config.SubConfig

Raises:

ValueError – if the name is already defined.

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.BaseConfig(argparser)

Bases: object

Abstract base class for icat.config.Config and icat.config.SubConfig. This class defines the common API. It is not intended to be instantiated directly.

Class attributes (read only):

ReservedVariables = ['credentials']: Reserved names of configuration variables.

Instance methods:

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

Defines a new configuration variable.

Note that the value of some configuration variable may influence the evaluation of other variables. For instance, if configFile and configSection are set, the values for other configuration variables are searched in this configuration file. Thus, the evaluation order of the configuration variables is important. The variables are evaluated in the order that this method is called to define the respective 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. Python builtins int and float or some standard library classes such as Path 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 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.

Returns:

the new configuration variable object.

Return type:

icat.config.ConfigVariable

Raises:

RuntimeError – if this objects already has subcommands defined with icat.config.BaseConfig.add_subcommands().
ValueError – if the name is not valid.

See:

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

add_subcommands(name='subcmd', arg_kws=None, optional=False)

Defines a new configuration variable to select subcommands.

Note

adding a subcommand variable must be the last action of this kind on a icat.config.BaseConfig object. Adding any more configuration variables or subcommand variables subsequently is not allowed. As a consequence, a icat.config.BaseConfig object may not have more then one subcommand variable.

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.
arg_kws (dict) – keyword arguments to be passed to argparse.ArgumentParser.add_subparsers(). Mostly useful to set title or help. Note that dest will be overridden and set to the value of name.
optional (bool) – flag wether providing a subcommand is optional.

Returns:

the new subcommand object.

Return type:

icat.config.ConfigSubCmd

Raises:

RuntimeError – if this objects already has subcommands.
ValueError – if the name is not valid.

See:

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

class icat.config.Config(defaultvars=True, needlogin=True, ids='optional', preset=None, args=None)

Bases: BaseConfig

Set configuration variables.

Allow configuration variables to be set via command line arguments, environment variables, configuration files, and default values, in this order. In the case of a hidden credential such as a password, the user may also be prompted for a value. 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.

The constructor sets up some predefined configuration variables.

Parameters:

defaultvars (bool) – if set to False, no default configuration variables other then configFile and configSection will be defined. The arguments needlogin and ids will be ignored in this case.
needlogin (bool) – if set to False, the configuration variables auth, username, password, promptPass, and credentials will be left out.
ids (bool or str) – the configuration variable idsurl will not be set up at all, or be set up as a mandatory, or as an optional variable, if this is set to False, to ‘mandatory’, or to ‘optional’ respectively.
preset (dict) – mapping of configuration variable names to preset values. These preset values override the default value for the corresponding variable. Note that command line arguments, environment variables, and settings in the configuration files still take precedence over the preset values.
args (list of str) – list of command line arguments or None. If not set, the command line arguments will be taken from sys.argv.

Changed in version 1.0.0: add the preset argument.

Instance attributes (read only):

client: The icat.client.Client object initialized according to the configuration. This is also the first element in the return value from getconfig().

client_kwargs: The keyword arguments that have been passed to the constructor of client.

Instance methods:

getconfig()

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.

Returns:: a tuple with two items, a client initialized to connect to an ICAT server according to the configuration and an object having the configuration values set as attributes. The client will be None if the defaultvars constructor argument was False.
Return type:: tuple of icat.client.Client and 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.

class icat.config.SubConfig(argparser, parent, name=None, func=None)

Bases: BaseConfig

Set configuration variables for a subcommand.

These subconfig objects are created in icat.config.ConfigSubCmds.add_subconfig(). Specific configuration variables for the respective subcommand may be added calling the add_variable() method inherited from icat.config.BaseConfig.

Predefined configuration variables

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

configFile
Paths of the configuration files to read. The default is a list of standard paths that depends on the operating system. If a value is provided, it must be a single path. The value that is set in this variable after configuration is a list of Path objects of the files that have successfully been 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 of the web service description of the ICAT server.

idsurl
URL of the ICAT Data Service.

checkCert
Verify the server certificate for HTTPS connections.

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():

credentials
contains the credentials needed for the indicated authenticator (username and password if authenticator information is not available) suitable to be passed to icat.client.Client.login().

Table 1 Command line arguments, environment variables, and default values for the configuration variables.
Name	Command line	Environment	Default	Mandatory	Notes
configFile	`-c`, `--configfile`	`ICAT_CFG`	depends	no	(1)
configSection	`-s`, `--configsection`	`ICAT_CFG_SECTION`	`None`	no
url	`-w`, `--url`	`ICAT_SERVICE`		yes
idsurl	`--idsurl`	`ICAT_DATA_SERVICE`	`None`	depends	(2)
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	(3)
username	`-u`, `--user`	`ICAT_USER`		yes	(3),(4)
password	`-p`, `--pass`		interactive	yes	(3),(4),(5)
promptPass	`-P`, `--prompt-pass`		`False`	no	(3),(4),(5)

See Table 1 for an overview of predefined configuration variables. Mandatory means that an error will be raised in icat.config.Config.getconfig() if no value is found for the configuration variable in question.

Notes:

The default value for configFile depends on the operating system.
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 to the constructor of icat.config.Config is set to False, to “mandatory”, or to “optional” respectively.
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.
If the ICAT server supports the icat.client.Client.getAuthenticatorInfo() API call (icat.server 4.9.0 and newer), the server will be queried about the credentials required for the authenticator indicated by the value of auth. The corresponding variables will be setup in the place of username and password. The variable promptPass will be setup only if any of the credentials is marked as hidden in the authenticator information.
The user will be prompted for the password if promptPass is True, if no password is provided in the command line or the configuration file, or if the username, but not the password has been provided by command line arguments. This applies accordingly to credentials marked as hidden if authenticator information is available from the server.

If the argument defaultvars to the constructor of icat.config.Config is set to False, no default configuration variables other then configFile and configSection will be defined. The configuration mechanism is still intact. In particular, custom configuration variables may be defined and reading the configuration file still works.

icat.config — Manage configuration

Predefined configuration variables

`icat.config` — Manage configuration