Merge branch 'gh-4618'

* gh-4618:
  DEP: Deprecate numpy.rank

4 files changed, 39 insertions, 1 deletions

diff --git a/doc/release/1.9.0-notes.rst b/doc/release/1.9.0-notes.rst
index dab772db4..4b1e094ad 100644
--- a/doc/release/1.9.0-notes.rst
+++ b/doc/release/1.9.0-notes.rst
@@ -347,6 +347,11 @@ The integer and empty input to ``select`` is deprecated. In the future only
 boolean arrays will be valid conditions and an empty ``condlist`` will be
 considered an input error instead of returning the default.
 
+``rank`` function
+~~~~~~~~~~~~~~~~~
+The ``rank`` function has been deprecated to avoid confusion with
+``numpy.linalg.matrix_rank``.
+
 C-API
 ~~~~~
 
diff --git a/numpy/__init__.py b/numpy/__init__.py
index 1029652c8..6a6caf654 100644
--- a/numpy/__init__.py
+++ b/numpy/__init__.py
@@ -121,6 +121,17 @@ class ModuleDeprecationWarning(DeprecationWarning):
     pass
 
 
+class VisibleDeprecationWarning(UserWarning):
+    """Visible deprecation warning.
+
+    By default, python will not show deprecation warnings, so this class
+    can be used when a very visible warning is helpful, for example because
+    the usage is most likely a user bug.
+
+    """
+    pass
+
+
 # oldnumeric and numarray were removed in 1.9. In case some packages import
 # but do not use them, we define them here for backward compatibility.
 oldnumeric = 'removed'
@@ -157,7 +168,9 @@ else:
         return loader(*packages, **options)
 
     from . import add_newdocs
-    __all__ = ['add_newdocs', 'ModuleDeprecationWarning']
+    __all__ = ['add_newdocs',
+               'ModuleDeprecationWarning',
+               'VisibleDeprecationWarning']
 
     pkgload.__doc__ = PackageLoader.__call__.__doc__
 
diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index 575df9628..a2d2f3100 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -4,7 +4,9 @@
 from __future__ import division, absolute_import, print_function
 
 import types
+import warnings
 
+from .. import VisibleDeprecationWarning
 from . import multiarray as mu
 from . import umath as um
 from . import numerictypes as nt
@@ -2453,6 +2455,11 @@ def rank(a):
     If `a` is not already an array, a conversion is attempted.
     Scalars are zero dimensional.
 
+    .. note::
+        This function is deprecated in NumPy 1.9 to avoid confusion with
+        `numpy.linalg.matrix_rank`. The ``ndim`` attribute or function
+        should be used instead.
+
     Parameters
     ----------
     a : array_like
@@ -2486,6 +2493,10 @@ def rank(a):
     0
 
     """
+    warnings.warn(
+        "`rank` is deprecated; use the `ndim` attribute or function instead. "
+        "To find the rank of a matrix see `numpy.linalg.matrix_rank`.",
+        VisibleDeprecationWarning)
     try:
         return a.ndim
     except AttributeError:
diff --git a/numpy/core/tests/test_deprecations.py b/numpy/core/tests/test_deprecations.py
index f7fbb94e5..6e559ab26 100644
--- a/numpy/core/tests/test_deprecations.py
+++ b/numpy/core/tests/test_deprecations.py
@@ -366,5 +366,14 @@ class TestBooleanSubtractDeprecations(_DeprecationTestCase):
         self.assert_deprecated(operator.neg, args=(generic,))
 
 
+class TestRankDeprecation(_DeprecationTestCase):
+    """Test that np.rank is deprecated. The function should simply be
+    removed. The VisibleDeprecationWarning may become unnecessary.
+    """
+    def test(self):
+        a = np.arange(10)
+        assert_warns(np.VisibleDeprecationWarning, np.rank, a)
+
+
 if __name__ == "__main__":
     run_module_suite()