Better handling of configuration files

Author: albireox

CHANGELOG.rst

@@ -18,6 +18,14 @@ master
 1.0.5 (unreleased)
 ------------------
 
+Backward incompatible changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* The default path for the user configuration file is now ``~/.config/<name>/<name>.yml``.
+
+Added
+^^^^^
+* Better handling of configuration files. An environment variable ``$<NAME>_CONFIG_PATH`` (e.g., ``$MYPYTHON_CONFIG_PATH``) can be defined to point to the user configuration file. If defined, this path overrides the default location.
+
 Changed
 ^^^^^^^
 * Modified logger to deal with warnings. Added critical level printing. Fixes :issue:`12,13`.

docs/sphinx/index.rst

@@ -196,7 +196,7 @@ Your new product contains a `YAML <http://yaml.org/>`_ configuration file in the
     print(mypython.config['option1']['suboption2'])
     >>> 'some text'
 
-If the user creates a custom configuration file in ``~/.mypython/mypython.yml``, the contents of that file will be used to update the default options. For instance, if you create a file with the contents
+If the user creates a custom configuration file in ``~/.config/mypython/mypython.yml``, the contents of that file will be used to update the default options. For instance, if you create a file with the contents
 
 .. code-block:: yaml
 
@@ -210,6 +210,8 @@ the code above would return ::
     print(mypython.config['option1']['suboption2'])
     >>> 'a different text'
 
+Another possibility is to define an environment variable ``$MYPYTHON_CONFIG_PATH`` pointing to the user configuration file to use. If the environment variable is set, it overrides the default location for the user configuration file.
+
 The package also includes a logging object built around Python's `logging <https://docs.python.org/3/library/logging.html>`__ module. Our custom logger allows to file and screen at the same time and provides more colourful tracebacks and warnings. From anywhere in your code you can do ::
 
     from mypython import log

{{cookiecutter.repo_name}}/python/{{cookiecutter.package_name|lower}}/__init__.py

@@ -2,48 +2,18 @@
 
 from __future__ import absolute_import, division, print_function, unicode_literals
 
-from pkg_resources import parse_version
-import os
-
-import yaml
-
-# Inits the logging system. Only shell logging, and exception and warning catching.
-# File logging can be started by calling log.start_file_logger(path).
-from .utils import get_logger
-
-
-def merge(user, default):
-    """Merges a user configuration with the default one."""
-
-    if isinstance(user, dict) and isinstance(default, dict):
-        for kk, vv in default.items():
-            if kk not in user:
-                user[kk] = vv
-            else:
-                user[kk] = merge(user[kk], vv)
-
-    return user
+from .utils import get_config, get_logger
 
 
 NAME = '{{cookiecutter.package_name}}'
 
 
 # Loads config
-yaml_kwds = dict()
-if parse_version(yaml.__version__) >= parse_version('5.1'):
-    yaml_kwds.update(Loader=yaml.FullLoader)
-
-config_path = os.path.join(os.path.dirname(__file__), 'etc/{0}.yml'.format(NAME))
-with open(config_path, 'r') as fp:
-    config = yaml.load(fp, **yaml_kwds)
-
-# If there is a custom configuration file, updates the defaults using it.
-custom_config_path = os.path.expanduser('~/.{0}/{0}.yml'.format(NAME))
-if os.path.exists(custom_config_path):
-    with open(custom_config_path, "r") as fp:
-        config = merge(yaml.load(fp, **yaml_kwds), config)
+config = get_config(NAME)
 
 
+# Inits the logging system. Only shell logging, and exception and warning catching.
+# File logging can be started by calling log.start_file_logger(path).
 log = get_logger(NAME)
 
 

{{cookiecutter.repo_name}}/python/{{cookiecutter.package_name|lower}}/utils/__init__.py

@@ -1,2 +1,3 @@
 
+from .configuration import *
 from .logger import *

{{cookiecutter.repo_name}}/python/{{cookiecutter.package_name|lower}}/utils/configuration.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# @Author: José Sánchez-Gallego (gallegoj@uw.edu)
+# @Date: 2019-05-08
+# @Filename: configuration.py
+# @License: BSD 3-clause (http://www.opensource.org/licenses/BSD-3-Clause)
+#
+# @Last modified by: José Sánchez-Gallego (gallegoj@uw.edu)
+# @Last modified time: 2019-05-09 10:44:49
+
+import os
+
+import yaml
+from pkg_resources import parse_version
+
+
+__all__ = ['get_config']
+
+
+def merge_config(user, default):
+    """Merges a user configuration with the default one."""
+
+    if isinstance(user, dict) and isinstance(default, dict):
+        for kk, vv in default.items():
+            if kk not in user:
+                user[kk] = vv
+            else:
+                user[kk] = merge_config(user[kk], vv)
+
+    return user
+
+
+def get_config(name, allow_user=True, user_path=None, config_envvar=None,
+               merge_mode='update'):
+    """Returns a configuration dictionary.
+
+    The configuration dictionary is created by merging the default
+    configuration file that is part of the library (in ``etc/<name>.yml``)
+    with a user configuration file. The path to the user configuration file
+    can be defined as an environment variable to be passed to this function
+    in ``config_envvar`` or as a path in ``user_path``. The environment
+    variable, if exists, always takes precedence.
+
+    Parameters
+    ----------
+    name : str
+        The name of the package.
+    allow_user : bool
+        If `True`, looks for an user configuration file and merges is to the
+        default configuration. Otherwise it returns just the default
+        configuration.
+    user_path : str
+        The path to the user configuration file. Defaults to
+        ``~/.config/<name>/<name>.yml``. Ignored if the file does not exist.
+    config_envvar : str
+        The environment variable that contains the path to the user
+        configuration file. Defaults to ``<name>_CONFIG_PATH``. If the
+        environment variable exists, the ``user_path`` is ignored.
+    merge_mode : str
+        Defines how the default and user dictionaries will be merged. If
+        ``update``, the user dictionary will be used to update the default
+        configuration. If ``replace``, only the user configuration will be
+        returned.
+
+    Returns
+    -------
+    config : dict
+        A dictionary containing the configuration.
+
+    """
+
+    assert merge_mode in ['update', 'replace'], 'invalid merge mode.'
+
+    yaml_kwds = dict()
+    if parse_version(yaml.__version__) >= parse_version('5.1'):
+        yaml_kwds.update(Loader=yaml.FullLoader)
+
+    # Loads config
+    config_path = os.path.join(os.path.dirname(__file__), '../etc/{0}.yml'.format(name))
+    with open(config_path, 'r') as fp:
+        config = yaml.load(fp, **yaml_kwds)
+
+    if allow_user is False:
+        return config
+
+    config_envvar = config_envvar or '{}_CONFIG_PATH'.format(name.upper())
+
+    if user_path is not None:
+        user_path = os.path.expanduser(os.path.expandvars(user_path))
+    else:
+        user_path = os.path.expanduser('~/.config/{0}/{0}.yml'.format(name))
+
+    if config_envvar in os.environ:
+        custom_config_fn = os.environ[config_envvar]
+    elif os.path.exists(user_path):
+        custom_config_fn = user_path
+    else:
+        return config
+
+    with open(custom_config_fn, 'r') as fp:
+        user_config = yaml.load(fp, **yaml_kwds)
+
+    if merge_mode == 'update':
+        return merge_config(user_config, config)
+    else:
+        return user_config