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 toicat.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 toicat.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. 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.This function is suitable to be passed as type argument to
icat.config.BaseConfig.add_variable()
.
-
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 oficat.config.Config.getconfig()
.
-
class
icat.config.
ConfigSubCmds
(name, optional, config, subparsers)¶ Bases:
icat.config.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 theadd_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 toargparse.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 byicat.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: Raises: ValueError – if the name is already defined.
- name (
-
-
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.
-
class
icat.config.
BaseConfig
(argparser)¶ Bases:
object
Abstract base class for
icat.config.Config
andicat.config.SubConfig
. This class defines the common API. It is not intended to be instantiated directly.Class attributes (read only):
-
ReservedVariables = ['configDir', '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 oficat.config.Configuration
returned byicat.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 inicat.config.Config.ReservedVariables
. If arg_opts corresponds to a positional argument, the name must be equal to this argument name. - arg_opts (
tuple
ofstr
) – command line flags associated with this variable. This will be passed as name or flags toargparse.ArgumentParser.add_argument()
. - arg_kws (
dict
) – keyword arguments to be passed toargparse.ArgumentParser.add_argument()
. - envvar (
str
) – name of the environment variable orNone
. 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 toFalse
and default isNone
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
andfloat
or some standard library classes such asPath
are fine. If set toNone
, the string value is taken as is. If applicable, the default value will also be passed through this conversion. The special valueicat.config.flag
may also be used to indicate a variant oficat.config.boolean()
. - subst (
bool
) – flag wether substitution of other configuration variables using the%
interpolation operator shall be performed. If set toTrue
, 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: 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.- name (
-
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, aicat.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 oficat.config.Configuration
returned byicat.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 inicat.config.Config.ReservedVariables
. - arg_kws (
dict
) – keyword arguments to be passed toargparse.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.- name (
-
-
class
icat.config.
Config
(defaultvars=True, needlogin=True, ids='optional', args=None)¶ Bases:
icat.config.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
andconfigparser
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 toFalse
, 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 toFalse
, the configuration variables auth, username, password, promptPass, and credentials will be left out. - ids (
bool
orstr
) – 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 toFalse
, to ‘mandatory’, or to ‘optional’ respectively. - args (
list
ofstr
) – list of command line arguments orNone
. If not set, the command line arguments will be taken fromsys.argv
.
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 ifgetconfig()
.
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 wasFalse
.Return type: tuple
oficat.client.Client
andicat.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.
- defaultvars (
-
class
icat.config.
SubConfig
(argparser, parent, name=None, func=None)¶ Bases:
icat.config.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 theadd_variable()
method inherited fromicat.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
- 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.
- 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()
.
Deprecated since version 0.13: The derived variable configDir is deprecated and will be removed in version 1.0.
The command line arguments, environment variables, and default values for the configuration variables are as follows:
Name | Command line | Environment | Default | Mandatory | Notes |
---|---|---|---|---|---|
configFile | -c , --configfile |
ICAT_CFG |
depends | no | (1) |
configSection | -s , --configsection |
ICAT_CFG_SECTION |
None |
no | (2) |
url | -w , --url |
ICAT_SERVICE |
yes | ||
idsurl | --idsurl |
ICAT_DATA_SERVICE |
None |
depends | (3) |
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 | (4) | |
username | -u , --user |
ICAT_USER |
yes | (4),(5) | |
password | -p , --pass |
interactive | yes | (4),(5),(6) | |
promptPass | -P , --prompt-pass |
False |
no | (4),(5),(6) |
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 default value for configSection may be changed in
icat.config.defaultsection
. - 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 toFalse
, to “mandatory”, or to “optional” respectively. - If the argument needlogin to the constructor of
icat.config.Config
is set toFalse
, 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.