DEV Rely on SERPENT_TOOLS_DATA environment variable

The serpentTools.data.getFile and readDataFile functions now
rely on the evnironment variable SERPENT_TOOLS_DATA. This will allow
the files to be stored in any location, including outside the
repository, but more importantly, outside the python package.

Since this change is done inside the getFile function, none of the
tests have to be modified at all. The travis build commands will
have to be slightly modified to use this directory, and those
changes will come shortly.

Notes have been added to the developer guide to indicate the use
of this variable, and how to set it.

Related: GH Issue CORE-GATECH-GROUP#336

docs/develop/checklist.rst

@@ -15,7 +15,7 @@ reviewing pull requests (PR):
 #. PR does not cause unit tests and builds to fail
 #. Changes are reflected in documentation - :ref:`documentation`
 
-.. _dev-ci
+.. _dev-ci:
 
 CI Testing
 ==========
@@ -27,20 +27,36 @@ notebooks. The former are used to perform more granular testing
 over the project, while the latter ensure our example notebooks
 are runnable.
 
-.. _dev-unittests
+.. _dev-unittests:
 
 Unit Tests
 ----------
 
 Unit tests should cover all public methods and a sufficient
-set of use cases to reduce the amount of bugs that make it
-into releases.
+set of use cases to reduce the amount of bugs that make it into releases.
 Unit tests are run using :term:`pytest` from the project directory::
 
     $ ls
     examples/ LICENSE serpentTools/ tests/ ...
     $ pytest
 
+Unit tests rely on data files that are shipped with the repository. These
+files are found using the environment variable ``SERPENT_TOOLS_DATA``, which
+should point to a directory containing the data files. For a temporary fix,
+this variable can be included in the command line, with::
+
+    $ SERPENT_TOOLS_DATA=/path/to/data/files pytest
+
+Alternatively, one can make the fix permanent by including the line
+``export SERPENT_TOOLS_DATA=/path/to/data/files`` into a shell startup
+file, e.g. ``~/.bashrc``.
+
+.. note::
+
+    The notebook test script uses a temporary directory, which may not
+    find files if ``SERPENT_TOOLS_DATA`` is a relative path. Using the
+    absolute path is recommended.
+
 If the ``pytest-cov`` package is installed, you can view the coverage, or
 how much of the project is touched by tests, with::
 
@@ -51,7 +67,7 @@ deviations are acceptable. The coverage is not a factor in passing or failing
 CI, but substantial changes to the test suite should serve a valid purpose if
 the coverage does decrease.
 
-.. _dev-notebooks
+.. _dev-notebooks:
 
 Notebook Tests
 --------------
@@ -65,7 +81,7 @@ converts these to python scripts and runs them using
 It is beneficial to run this script during major changes to the API, as well as correcting any
 errors or deprecated/removed features.
 
-.. _dev-lint
+.. _dev-lint:
 
 Lint
 ====

serpentTools/data/__init__.py

@@ -2,12 +2,12 @@
 Module for loading reference and example data files
 """
 
-from os.path import join, exists
+import os
+from os.path import exists
+import pathlib
 from warnings import warn
 
-from serpentTools import __path__, read
-
-_DATA_ROOT = join(__path__[0], 'data')
+from serpentTools import read
 
 __all__ = ['readDataFile', ]
 
@@ -16,27 +16,36 @@ def getFile(path):
     """
     Retrieve the path to one of the reference or example files
 
+    Relies on the environment variable ``SERPENT_TOOLS_DATA``
+    to find the data files.
+
     Parameters
     ----------
-    path: str
+    path : str
         The name of the file without any additional directory
         information
 
     Returns
     -------
-    str:
+    str
         Path to a data file that can be read with one of
         the readers or with :func:`serpentTools.read`
 
     Raises
     ------
-    IOError:
+    IOError
         If no match for ``path`` exists
     """
-    fullPath = join(_DATA_ROOT, path)
-    if not exists(fullPath):
-        raise IOError("File matching {} does not exist".format(path))
-    return fullPath
+    datadir = os.environ.get("SERPENT_TOOLS_DATA")
+    if datadir is None:
+        raise EnvironmentError("""serpentTools.data functions rely on the
+environment variable SERPENT_TOOLS_DATA to find data files. To use these
+functions for testing and examples, set this environment variable""")
+    fullPath = pathlib.Path(datadir) / path
+    if not fullPath.is_file():
+        raise FileNotFoundError(
+            "Data file {} could not be found in {}".format(path, datadir))
+    return str(fullPath)
 
 
 def readDataFile(path, **kwargs):
@@ -81,15 +90,8 @@ def readDataFile(path, **kwargs):
         # assume this is a example/test file contained in this project
         filePath = getFile(path)
     else:
-        _warnDataFilePurpose()
+        warn("Please use serpentTools.read as the primary read function. "
+             "readDataFile is intended for testing and example and may "
+             "be changed or removed in the future.")
         filePath = path
     return read(filePath, **kwargs)
-
-
-def _warnDataFilePurpose():
-    """
-    Issue a warning indicating that readDataFile is not primary read function.
-    """
-    warn("Please use serpentTools.read as the primary read function. "
-         "readDataFile is intended for testing and example and may "
-         "be changed or removed in the future.", UserWarning)