Skip to content

Latest commit

 

History

History
221 lines (161 loc) · 9.09 KB

config.rst

File metadata and controls

221 lines (161 loc) · 9.09 KB
Raw

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.config.defaultsection

icat.config.boolean

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

icat.config.ConfigVariable

icat.config.ConfigSubCmds

icat.config.Configuration

icat.config.BaseConfig

Class attributes (read only):

ReservedVariables = ['configDir', 'credentials']

Reserved names of configuration variables.

Instance methods:

icat.config.BaseConfig.add_variable

icat.config.BaseConfig.add_subcommands

icat.config.Config

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 if getconfig.

client_kwargs

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

Instance methods:

icat.config.Config.getconfig

icat.config.SubConfig

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.

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 :const: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 :const: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:

  1. The default value for configFile depends on the operating system.
  2. The default value for configSection may be changed in icat.config.defaultsection.
  3. 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.
  4. 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.
  5. 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.
  6. 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.