Add pysb.pathfinder to documentation (#548)

Also add a new function pysb.pathfinder.list_programs() to discover
available external programs and their environment variables at
runtime, and some tests.

doc/modules/index.rst

@@ -7,6 +7,7 @@ PySB Modules Reference
    core.rst
    integrate.rst
    simulator.rst
+   pathfinder.rst
    modeltests.rst
    bng.rst
    kappa.rst

doc/modules/pathfinder.rst

@@ -0,0 +1,5 @@
+Set/get paths for external tools (:py:mod:`pysb.pathfinder`)
+============================================================
+
+.. automodule:: pysb.pathfinder
+    :members:

pysb/pathfinder.py

@@ -101,6 +101,23 @@
 _path_cache = {}
 
 
+def list_programs():
+    """
+    Return the list of available external programs as a dictionary
+
+    Returns
+    -------
+    A dictionary containing the internal program name (key) and the
+    human-readable name and environment variable (value) to adjust the path
+    for that program.
+
+    """
+    keep_keys = ('name', 'env_var')
+    return {prog_name: {
+        k: v for k, v in prog_data.items() if k in keep_keys
+    } for prog_name, prog_data in _path_config.items()}
+
+
 def get_path(prog_name):
     """
     Gets the currently active path to an external executable
@@ -111,8 +128,8 @@ def get_path(prog_name):
     Parameters
     ----------
     prog_name: str
-        The PySB internal program name for an executable. One of 'bng'
-        (BioNetGen), 'kasa' (Kappa's KaSa) or 'kasim' (Kappa's KaSim).
+        The PySB internal program name for an executable (run
+        :func:`list_programs` for a list).
 
     Returns
     -------
@@ -216,13 +233,16 @@ def get_path(prog_name):
 
 def set_path(prog_name, full_path):
     """
-    Sets the full path to an external executable
+    Sets the full path to an external executable at runtime
+
+    External program paths can also be adjusted by environment variable prior
+    to first use; run :func:`list_programs` for a list of programs.
 
     Parameters
     ----------
     prog_name: str
-        The internal program name for an executable. See :func:`get_path` for
-        valid values.
+        The internal program name for an executable. (see
+        :func:`list_programs`)
     full_path: str
         The full path to the external executable or its enclosing directory.
         If the path is a directory, it will be searched for the executable.

pysb/tests/test_pathfinder.py

@@ -0,0 +1,12 @@
+from pysb.pathfinder import get_path, set_path, list_programs, _path_config
+import os
+
+
+def test_get_set_path():
+    bng_path = get_path('bng')
+    assert os.path.exists(bng_path)
+    set_path('bng', bng_path)
+
+
+def test_list_programs():
+    assert list_programs().keys() == _path_config.keys()