Let user select a config file

Fix #13:

> Pulp Smash's configuration file does not live with the source code itself. […]
> There's one down-side to the current approach, though: it's hard to work with
> multiple configuration files. Imagine that a user creates two virtualenvs,
> installs Pulp Smash into each, and then wants to run Pulp Smash from both
> locations. How can the user make the two Pulp Smash installations use a
> different configuration file?

Do this by making `ServerConfig` objects respect a new environment variable:
`PULP_SMASH_CONFIG_FILE`. By default, `ServerConfig` objects look for a
configuration file named "settings.json", but if the environment variable is
set, a configuration file by that name is looked for instead.

Add unit tests and documentation for the new functionality.

Manual test results:

    $ mv ~/.config/pulp_smash/settings{,2}.json
    $ ls -A1 ~/.config/pulp_smash/
    settings2.json
    $ python -m unittest2 discover pulp_smash.tests
    … (numerous ConfigFileNotFoundError exceptions)
    $ PULP_SMASH_CONFIG_FILE=settings2.json \
    > python -m unittest2 discover pulp_smash.tests
    ....F...
    …
    ----------------------------------------------------------------------
    Ran 8 tests in 3.968s

    FAILED (failures=1)

The one test failure is expected.

pulp_smash/__main__.py

@@ -32,6 +32,12 @@
     configuration file found is used. Settings are not cascaded.
     ''',
     '''\
+    A non-default configuration file can be selected with an environment
+    variable like so: `PULP_SMASH_CONFIG_FILE=alternate-{} python -m unittest2
+    discover pulp_smash.tests`. This variable should be a file name, not a
+    path.
+    ''',
+    '''\
     The provided command will run all tests, but any subset of tests may also
     be selected. For example, you may also run `python -m unittest2
     pulp_smash.tests.test_login`. Consult the unittest2 documentation for test
@@ -43,10 +49,11 @@
 
 def main():
     """Provide usage instructions to the user."""
+    cfg = ServerConfig()
     cfg_path = join(
         # pylint:disable=protected-access
-        BaseDirectory.save_config_path(ServerConfig()._xdg_config_dir),
-        ServerConfig()._xdg_config_file
+        BaseDirectory.save_config_path(cfg._xdg_config_dir),
+        cfg._xdg_config_file
     )
     wrapper = textwrap.TextWrapper()
     message = ''
@@ -57,7 +64,11 @@ def main():
     wrapper.initial_indent = '* '
     wrapper.subsequent_indent = '  '
     message += '\n\n' + wrapper.fill(textwrap.dedent(MESSAGE[4]))
-    message += '\n\n' + wrapper.fill(textwrap.dedent(MESSAGE[5]))
+    message += '\n\n' + wrapper.fill(
+        # pylint:disable=protected-access
+        textwrap.dedent(MESSAGE[5].format(cfg._xdg_config_file))
+    )
+    message += '\n\n' + wrapper.fill(textwrap.dedent(MESSAGE[6]))
     print(message)
 
 

pulp_smash/config.py

@@ -11,7 +11,7 @@
 from __future__ import unicode_literals
 
 import json
-from os.path import isfile, join
+import os
 from threading import Lock
 from xdg import BaseDirectory
 
@@ -92,6 +92,12 @@ class ServerConfig(object):
     <http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_.
     Please read the specification for insight into the logic of those methods.
 
+    In addition, the file-facing methods respect the ``PULP_SMASH_CONFIG_FILE``
+    environment variable. By default, the methods work with a file named
+    ``settings.json``, but the environment variable overrides that default. If
+    set, the environment variable should be a file name like ``settings2.json``
+    (or a relative path), *not* an absolute path.
+
     :param base_url: A string. A protocol, hostname and optionally a port. For
         example, ``'http://example.com:250'``. Do not append a trailing slash.
     :param auth: A two-tuple. Credentials to use when communicating with the
@@ -110,7 +116,10 @@ def __init__(self, base_url=None, auth=None, verify=None):
         self.verify = verify
 
         self._section = 'default'
-        self._xdg_config_file = 'settings.json'
+        self._xdg_config_file = os.environ.get(
+            'PULP_SMASH_CONFIG_FILE',
+            'settings.json'
+        )
         self._xdg_config_dir = 'pulp_smash'
 
     def __repr__(self):
@@ -147,7 +156,7 @@ def save(self, section=None, xdg_config_file=None, xdg_config_dir=None):
             xdg_config_file = self._xdg_config_file
         if xdg_config_dir is None:
             xdg_config_dir = self._xdg_config_dir
-        path = join(
+        path = os.path.join(
             BaseDirectory.save_config_path(xdg_config_dir),
             xdg_config_file
         )
@@ -297,8 +306,8 @@ def _get_config_file_path(xdg_config_dir, xdg_config_file):
 
     """
     for config_dir in BaseDirectory.load_config_paths(xdg_config_dir):
-        path = join(config_dir, xdg_config_file)
-        if isfile(path):
+        path = os.path.join(config_dir, xdg_config_file)
+        if os.path.isfile(path):
             return path
     raise ConfigFileNotFoundError(
         'No configuration files could be located after searching for a file '

tests/test_config.py

@@ -3,6 +3,7 @@
 from __future__ import unicode_literals
 
 import json
+import os
 from itertools import permutations
 from mock import mock_open, patch
 from pulp_smash import config
@@ -54,6 +55,27 @@ def test_private_attrs(self):
                 self.assertIsNotNone(getattr(self.cfg, attr))
 
 
+class PulpSmashConfigFileTestCase(TestCase):
+    """Verify the ``PULP_SMASH_CONFIG_FILE`` environment var is respected."""
+
+    def test_var_set(self):
+        """Set the environment variable."""
+        os_environ = {'PULP_SMASH_CONFIG_FILE': type('')(randint(1, 1000))}
+        with patch.dict(os.environ, os_environ, clear=True):
+            cfg = ServerConfig()
+        self.assertEqual(
+            cfg._xdg_config_file,  # pylint:disable=protected-access
+            os_environ['PULP_SMASH_CONFIG_FILE']
+        )
+
+    def test_var_unset(self):
+        """Do not set the environment variable."""
+        with patch.dict(os.environ, {}, clear=True):
+            cfg = ServerConfig()
+        # pylint:disable=protected-access
+        self.assertEqual(cfg._xdg_config_file, 'settings.json')
+
+
 class ReadTestCase(TestCase):
     """Test :meth:`pulp_smash.config.ServerConfig.read`."""