Add documentation and rename import variable

.travis.yml

@@ -23,6 +23,8 @@ before_install:
     - sh -e /etc/init.d/xvfb start
     - sudo apt-get update
 
+    # Python 3.2 is not supported by Miniconda, so we use the package manager for that run.
+    # NumPy has a bug in python 3 that is only fixed in the latest version, hence the download of _import _tools.
     - if [[ $ENV == python=3.2 ]]; then
         sudo apt-get install python3-numpy;
         wget https://raw.githubusercontent.com/numpy/numpy/master/numpy/_import_tools.py -O /home/travis/virtualenv/python3.2_with_system_site_packages/lib/python3.2/site-packages/numpy/_import_tools.py;

skimage/_shared/tests/test_version_requirements.py

@@ -4,30 +4,33 @@
 import numpy as np
 from numpy.testing import assert_raises, assert_equal
 import nose
-from skimage._shared import version_requirements as vr
+from skimage._shared import version_requirements as version_req
 
 
 def test_get_module_version():
-    assert vr.get_module_version('numpy')
-    assert vr.get_module_version('scipy')
-    assert_raises(ImportError, lambda: vr.get_module_version('fakenumpy'))
+    assert version_req.get_module_version('numpy')
+    assert version_req.get_module_version('scipy')
+    assert_raises(ImportError,
+                  lambda: version_req.get_module_version('fakenumpy'))
 
 
 def test_is_installed():
-    assert vr.is_installed('python', '>=2.6')
-    assert not vr.is_installed('numpy', '<1.0')
+    assert version_req.is_installed('python', '>=2.6')
+    assert not version_req.is_installed('numpy', '<1.0')
 
 
 def test_require():
 
-    @vr.require('python', '>2.6')
-    @vr.require('numpy', '>1.5')
+    # A function that only runs on Python >2.6 and numpy > 1.5 (should pass)
+    @version_req.require('python', '>2.6')
+    @version_req.require('numpy', '>1.5')
     def foo():
         return 1
 
     assert_equal(foo(), 1)
 
-    @vr.require('scipy', '<0.1')
+    # function that requires scipy < 0.1 (should fail)
+    @version_req.require('scipy', '<0.1')
     def bar():
         return 0
 
@@ -35,6 +38,5 @@ def test_require():
 
 
 def test_get_module():
-    assert_equal(vr.get_module('numpy'), np)
-    assert_equal(vr.get_module('nose'), nose)
-
+    assert_equal(version_req.get_module('numpy'), np)
+    assert_equal(version_req.get_module('nose'), nose)

skimage/_shared/version_requirements.py

@@ -95,6 +95,10 @@ def require(name, version=None):
         If version is not None, checking version
         (must have an attribute named '__version__' or 'VERSION')
         Version may start with =, >=, > or < to specify the exact requirement
+
+    Returns
+    -------
+    A decorator function.
     """
     def decorator(obj):
         @functools.wraps(obj)
@@ -112,6 +116,22 @@ def require(name, version=None):
 
 
 def get_module(module_name, version=None):
+    """Return a module object of name *module_name* if installed.
+
+    Parameters
+    ----------
+    module_name : str
+        Name of module.
+    version : str, optional
+        Version string to test against.
+        If version is not None, checking version
+        (must have an attribute named '__version__' or 'VERSION')
+        Version may start with =, >=, > or < to specify the exact requirement
+
+    Returns
+    -------
+    Module if *module_name* is installed matching the optional version or None.
+    """
     if not is_installed(module_name, version):
         return None
     return __import__(module_name,