Merge pull request matplotlib#2714 from pelson/deprecate_testing.image_util

Deprecated matplotlib.testing.image_util.

Author: tacaswell

doc/api/api_changes.rst

@@ -113,6 +113,10 @@ original location:
   does the exact same thing as `FormatStrFormatter`, but for new-style
   formatting strings.
 
+* Deprecated `matplotlib.testing.image_util` and the only function within,
+  `matplotlib.testing.image_util.autocontrast`. These will be removed
+  completely in v1.5.0.
+
 * The ``fmt`` argument of :meth:`~matplotlib.axes.Axes.plot_date` has been
   changed from ``bo`` to just ``o``, so color cycling can happen by default.
 

lib/matplotlib/cbook.py

@@ -119,6 +119,13 @@ def new_function():
 
     obj_type : str, optional
         The object type being deprecated.
+
+    Example
+    -------
+    # To warn of the deprecation of "matplotlib.name_of_module"
+    warn_deprecated('1.4.0', name='matplotlib.name_of_module',
+                    obj_type='module')
+
     """
     message = _generate_deprecation_message(
         since, message, name, alternative, pending, obj_type)
@@ -129,7 +136,7 @@ def new_function():
 def deprecated(since, message='', name='', alternative='', pending=False,
                obj_type='function'):
     """
-    Used to mark a function as deprecated.
+    Decorator to mark a function as deprecated.
 
     Parameters
     ------------
@@ -164,6 +171,13 @@ def new_function():
     pending : bool, optional
         If True, uses a PendingDeprecationWarning instead of a
         DeprecationWarning.
+        
+    Example
+    -------
+    @deprecated('1.4.0')
+    def the_function_to_deprecate():
+        pass
+    
     """
     def deprecate(func, message=message, name=name, alternative=alternative,
                   pending=pending):

lib/matplotlib/testing/image_util.py

@@ -37,7 +37,14 @@
 
 import numpy as np
 
-# TODO: Vectorize this
+from matplotlib.cbook import deprecated, warn_deprecated
+
+
+warn_deprecated('1.4.0', name='matplotlib.testing.image_util',
+                obj_type='module')
+
+
+@deprecated('1.4.0')
 def autocontrast(image, cutoff=0):
     """
     Maximize image contrast, based on histogram.  This completely