Source code for vdat.config.core

# Virus Data Analysis Tool: a data reduction GUI for HETDEX/VIRUS data
# Copyright (C) 2015, 2016, 2017  "The HETDEX collaboration"
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
"""Manage configuration

    Mostly copied from vhc/libvhc/config.py

"""
from __future__ import (absolute_import, division, print_function,
                        unicode_literals)

from configparser import ExtendedInterpolation
import configparser as cp
import os
import warnings

import yaml
from pyhetdex.tools import configuration as confp
from pyhetdex.tools import six_ext

_config_dic = {}


# exceptions

class ConfigurationError(Exception):
    """Generic error raised by the configuration sub-package"""
    pass


class MissingConfigurationError(ConfigurationError, KeyError):
    """Raised when a configuration item does not exist"""
    pass


class MissingConfigurationSectionError(ConfigurationError, KeyError):
    """Raised when a configuration section does not exist"""
    pass


# functions


def load_all_configs(args):
    """Convenience function to load the vdat configuration files.

    It loads:

    * ``"main"``: the standard configuration file ``vdat_conf_fname``; given
      from the command line
    * ``"command"``: the YAML file(s) defining the commands
    * ``"tasks"``: the YAML file(s) that instruct the GUI how to display the
      files; the names are in the ``tasks_config`` of the ``general`` section
      of the "default" configuration

    Parameters
    ----------
    args : Namespace
        Command line arguments
    """
    # load the main configuration files
    setting_files = args.setting
    if not load_std_conf('main', args, setting_files):
        msg = "The file '{}' does not exist".format(setting_files)
        raise ConfigurationError(msg)

    # get the ``general`` section of the configuration file
    conf = get_config('main')
    # load the tab and command interpreter yaml files
    for opt_name, name in zip(['command_config', 'tasks_config'],
                              ['commands', 'tasks']):
        fnames = conf.get_list('general', opt_name)
        if not load_yaml(name, *fnames):
            msg = "The file(s) '{}' do not exist"
            msg = msg.format(', '.join(fnames))
            raise ConfigurationError(msg)


def load_std_conf(name, args, *fnames):
    """Load standard configuration files

    Parameters
    ----------
    name : string
        name to associate to the configurations
    args : Namespace
        Command line arguments
    fnames : list of strings
        the filename(s) of the configuration files

    Returns
    -------
    flist : list
        files successfully loaded
    """
    conf = confp.ConfigParser(interpolation=ExtendedInterpolation(),
                              defaults=default_dict())

    flist = conf.read(fnames)

    try:
        conf.add_section('redux_dirs')
    except cp.DuplicateSectionError:
        pass

    conf = confp.override_conf(conf, args)

    _config_dic[name] = conf
    return flist


def load_yaml(name, *fnames):
    """Load YAML configuration files. Skip non existing files.

    Parameters
    ----------
    name : string
        name to associate to the configurations
    fnames : list of strings
        the filename(s) of the configuration files

    Returns
    -------
    flist : list
        files successfully loaded
    """
    yconf = {}
    flist = []
    for fn in fnames:
        try:
            with open(fn) as f:
                yconf.update(yaml.safe_load(f))
            flist.append(fn)
        except six_ext.FileOpenError:
            pass
    _config_dic[name] = yconf
    return flist


def default_dict():
    """Default values of the configuration object

    Returns
    -------
    defaults : dict
        options-values pairs
    """
    defaults = {}

    # Do the same to get the source dir
    defaults['vdat_source_dir'] = os.path.join(os.sep,
                                *os.path.abspath(__file__).split(os.sep)[:-2])

    # get the curebin directory from the environment as save in into
    # ``curebin_env``
    try:
        defaults['curebin_env'] = os.environ['CUREBIN']
    except KeyError:
        warnings.warn("'CUREBIN' environment variable is not set. If the"
                      " 'curebin' option in the configuration file is set"
                      " to interpolate from 'curebin_env', all the vdat"
                      " commands requiring cure binaries will fail.")

    return defaults


def get_config(name, section=None):
    """Returns the configuration file with the specified name.

    Parameters
    ----------
    name : string, optional
        name associated with the configuration object; by default returns the
        main configuration
    section : string, optional
        optionally returns only one section

    Returns
    -------
    configuration object
        can be either a :class:`~pyhetdex.tools.configuration.ConfigParser` or
        a dictionary(-like) object
    """
    try:
        conf = _config_dic[name]
    except KeyError:
        raise MissingConfigurationError("The configuration object '{}' does"
                                        " not exist".format(name))
    if section:
        try:
            conf = conf[section]
        except KeyError:
            msg = ("The configuration object '{}' does not have the required"
                   " section '{}".format(name, section))
            raise MissingConfigurationSectionError(msg)

    return conf