Merge deprecate_with_doc into deprecate(message="...").

4 files changed, 33 insertions, 48 deletions

diff --git a/numpy/lib/arraysetops.py b/numpy/lib/arraysetops.py
index 6868dc1d4..042866f30 100644
--- a/numpy/lib/arraysetops.py
+++ b/numpy/lib/arraysetops.py
@@ -32,7 +32,7 @@ __all__ = ['ediff1d', 'unique1d', 'intersect1d', 'intersect1d_nu', 'setxor1d',
            'setmember1d', 'union1d', 'setdiff1d', 'unique', 'in1d']
 
 import numpy as np
-from numpy.lib.utils import deprecate_with_doc
+from numpy.lib.utils import deprecate
 
 def ediff1d(ary, to_end=None, to_begin=None):
     """
@@ -418,7 +418,7 @@ def setdiff1d(ar1, ar2, assume_unique=False):
     else:
         return np.asarray(ar1)[aux == 0]
 
-@deprecate_with_doc('')
+@deprecate
 def unique1d(ar1, return_index=False, return_inverse=False):
     """
     This function is deprecated. Use unique() instead.
@@ -458,7 +458,7 @@ def unique1d(ar1, return_index=False, return_inverse=False):
         flag = np.concatenate(([True], ar[1:] != ar[:-1]))
         return ar[flag]
 
-@deprecate_with_doc('')
+@deprecate
 def intersect1d_nu(ar1, ar2):
     """
     This function is deprecated.  Use intersect1d()
@@ -469,7 +469,7 @@ def intersect1d_nu(ar1, ar2):
     aux.sort()
     return aux[aux[1:] == aux[:-1]]
 
-@deprecate_with_doc('')
+@deprecate
 def setmember1d(ar1, ar2):
     """
     This function is deprecated.  Use in1d(assume_unique=True)
diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
index 755229417..76ea08dfb 100644
--- a/numpy/lib/function_base.py
+++ b/numpy/lib/function_base.py
@@ -28,7 +28,7 @@ from numpy.lib.twodim_base import diag
 from _compiled_base import _insert, add_docstring
 from _compiled_base import digitize, bincount, interp as compiled_interp
 from arraysetops import setdiff1d
-from utils import deprecate_with_doc
+from utils import deprecate
 import numpy as np
 
 #end Fernando's utilities
@@ -1226,7 +1226,7 @@ import sys
 if sys.hexversion < 0x2040000:
     from sets import Set as set
 
-@deprecate_with_doc('')
+@deprecate
 def unique(x):
     """
     This function is deprecated.  Use numpy.lib.arraysetops.unique()
diff --git a/numpy/lib/utils.py b/numpy/lib/utils.py
index 6b4d0692b..4762daebc 100644
--- a/numpy/lib/utils.py
+++ b/numpy/lib/utils.py
@@ -7,8 +7,7 @@ from numpy.core.numerictypes import issubclass_, issubsctype, issubdtype
 from numpy.core import product, ndarray
 
 __all__ = ['issubclass_', 'get_numpy_include', 'issubsctype',
-           'issubdtype', 'deprecate', 'deprecate_with_doc',
-           'get_numarray_include',
+           'issubdtype', 'deprecate', 'get_numarray_include',
            'get_include', 'info', 'source', 'who', 'lookfor',
            'byte_bounds', 'may_share_memory', 'safe_eval']
 
@@ -95,25 +94,28 @@ else:
         func.__name__ = name
         return func
 
-def deprecate(func, oldname=None, newname=None):
+def deprecate(func, old_name=None, new_name=None, message=None):
     """
     Deprecate old functions.
 
-    Issues a DeprecationWarning, adds warning to `oldname`'s docstring,
-    rebinds ``oldname.__name__`` and returns the new function object.
+    Issues a DeprecationWarning, adds warning to `old_name`'s docstring,
+    rebinds ``old_name.__name__`` and returns the new function object.
 
     Parameters
     ----------
     func : function
         The function to be deprecated.
-    oldname : str, optional
+    old_name : str, optional
         The name of the function to be deprecated. Default is None, in which
         case the name of `func` is used.
-    newname : str, optional
+    new_name : str, optional
         The new name for the function. Default is None, in which case
-        the deprecation message is that `oldname` is deprecated. If given,
-        the deprecation message is that `oldname` is deprecated and `newname`
+        the deprecation message is that `old_name` is deprecated. If given,
+        the deprecation message is that `old_name` is deprecated and `new_name`
         should be used instead.
+    message : str, optional
+        Additional explanation of the deprecation.  Displayed in the docstring
+        after the warning.
 
     Returns
     -------
@@ -134,24 +136,25 @@ def deprecate(func, oldname=None, newname=None):
     """
 
     import warnings
-    if oldname is None:
+    if old_name is None:
         try:
-            oldname = func.func_name
+            old_name = func.func_name
         except AttributeError:
-            oldname = func.__name__
-    if newname is None:
-        str1 = "%s is deprecated" % (oldname,)
-        depdoc = "%s is DEPRECATED!!" % (oldname,)
+            old_name = func.__name__
+    if new_name is None:
+        depdoc = "%s is deprecated" % old_name
     else:
-        str1 = "%s is deprecated, use %s" % (oldname, newname),
-        depdoc = '%s is DEPRECATED!! -- use %s instead' % (oldname, newname,)
+        depdoc = "%s is deprecated, use %s" % (old_name, new_name)
+
+    if message is not None:
+        depdoc += "\n" + message
 
     def newfunc(*args,**kwds):
-        """arrayrange is DEPRECATED!! -- use `arange` instead."""
-        warnings.warn(str1, DeprecationWarning)
+        """arrayrange is DEPRECATED! -- use `arange` instead."""
+        warnings.warn(depdoc, DeprecationWarning)
         return func(*args, **kwds)
 
-    newfunc = _set_function_name(newfunc, oldname)
+    newfunc = _set_function_name(newfunc, old_name)
     doc = func.__doc__
     if doc is None:
         doc = depdoc
@@ -166,24 +169,6 @@ def deprecate(func, oldname=None, newname=None):
         newfunc.__dict__.update(d)
     return newfunc
 
-def deprecate_with_doc(somestr):
-    """Decorator to deprecate functions and provide detailed documentation
-    with 'somestr' that is added to the functions docstring.
-
-    Example:
-    depmsg = 'function scipy.foo has been merged into numpy.foobar'
-    @deprecate_with_doc(depmsg)
-    def foo():
-        pass
-
-    """
-
-    def _decorator(func):
-        newfunc = deprecate(func)
-        newfunc.__doc__ += "\n" + somestr
-        return newfunc
-    return _decorator
-
 get_numpy_include = deprecate(get_include, 'get_numpy_include', 'get_include')
 
 
diff --git a/numpy/ma/extras.py b/numpy/ma/extras.py
index 02bfa3cca..0f0d504c5 100644
--- a/numpy/ma/extras.py
+++ b/numpy/ma/extras.py
@@ -48,7 +48,7 @@ import numpy.core.umath as umath
 from numpy.lib.index_tricks import AxisConcatenator
 from numpy.linalg import lstsq
 
-from numpy.lib.utils import deprecate_with_doc
+from numpy.lib.utils import deprecate
 
 #...............................................................................
 def issequence(seq):
@@ -1173,7 +1173,7 @@ def setdiff1d(ar1, ar2, assume_unique=False):
     else:
         return ma.asarray(ar1)[aux == 0]
 
-@deprecate_with_doc('')
+@deprecate
 def unique1d(ar1, return_index=False, return_inverse=False):
     """ This function is deprecated. Use ma.unique() instead. """
     output = np.unique1d(ar1,
@@ -1187,7 +1187,7 @@ def unique1d(ar1, return_index=False, return_inverse=False):
         output = output.view(MaskedArray)
     return output
 
-@deprecate_with_doc('')
+@deprecate
 def intersect1d_nu(ar1, ar2):
     """ This function is deprecated. Use ma.intersect1d() instead."""
     # Might be faster than unique1d( intersect1d( ar1, ar2 ) )?
@@ -1195,7 +1195,7 @@ def intersect1d_nu(ar1, ar2):
     aux.sort()
     return aux[aux[1:] == aux[:-1]]
 
-@deprecate_with_doc('')
+@deprecate
 def setmember1d(ar1, ar2):
     """ This function is deprecated. Use ma.in1d() instead."""
     ar1 = ma.asanyarray(ar1)