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

:mod:`icat.config` --- Manage configuration

.. py:module:: icat.config

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 :class:`icat.config.Config`.

.. data:: icat.config.cfgdirs

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


.. autodata:: icat.config.cfgfile


.. autodata:: icat.config.defaultsection


.. autofunction:: icat.config.boolean


.. data:: icat.config.flag

    Variant of :func:`icat.config.boolean` that defines two command
    line arguments to switch the value on and off respectively.  May
    be passed as type to :meth:`icat.config.BaseConfig.add_variable`.


.. autofunction:: icat.config.cfgpath


.. autoclass:: icat.config.ConfigVariable
    :members:
    :show-inheritance:


.. autoclass:: icat.config.ConfigSubCmds
    :members:
    :show-inheritance:


.. autoclass:: icat.config.Configuration
    :members:
    :show-inheritance:


.. autoclass:: icat.config.BaseConfig
    :show-inheritance:

    Class attributes (read only):

    .. attribute:: ReservedVariables = ['configDir', 'credentials']

        Reserved names of configuration variables.

    Instance methods:

    .. automethod:: icat.config.BaseConfig.add_variable

    .. automethod:: icat.config.BaseConfig.add_subcommands


.. autoclass:: icat.config.Config
    :show-inheritance:

    Instance attributes (read only):

    .. attribute:: client

        The :class:`icat.client.Client` object initialized according to
        the configuration.  This is also the first element in the
        return value if :meth:`getconfig`.

    .. attribute:: client_kwargs

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

    Instance methods:

    .. automethod:: icat.config.Config.getconfig


.. autoclass:: icat.config.SubConfig
    :members:
    :show-inheritance:

Predefined configuration variables

The constructor of :class:`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 :meth:`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 :meth:`icat.client.Client.login`.
.. deprecated:: 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 :const:`None` depends (3)
checkCert --check-certificate, --no-check-certificate   :const:`True` no  
http_proxy --http-proxy http_proxy :const:`None` no  
https_proxy --https-proxy https_proxy :const:`None` no  
no_proxy --no-proxy no_proxy :const:`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 :meth:`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 :data:`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 :class:`icat.config.Config` is set to :const:`False`, to "mandatory", or to "optional" respectively.
  4. If the argument needlogin to the constructor of :class:`icat.config.Config` is set to :const:`False`, the configuration variables auth, username, password, promptPass, and credentials will be left out.
  5. If the ICAT server supports the :meth:`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 :const:`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 :class:`icat.config.Config` is set to :const:`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.