From 18fe03d76186b3e69f3b4ac3f4e29c276f56fe45 Mon Sep 17 00:00:00 2001
From: Phil Elson <pelson.pub@gmail.com>
Date: Fri, 10 Jan 2014 10:46:33 +0000
Subject: [PATCH] Deprecated matplotlib.testing.image_util.

---
 doc/api/api_changes.rst              |  4 ++++
 lib/matplotlib/cbook.py              | 16 +++++++++++++++-
 lib/matplotlib/testing/image_util.py |  9 ++++++++-
 3 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
index 88b1e8e7c17f..e6a0c1adc588 100644
--- a/doc/api/api_changes.rst
+++ b/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.
 
diff --git a/lib/matplotlib/cbook.py b/lib/matplotlib/cbook.py
index 570b91846f8c..c5e96a5bda5f 100644
--- a/lib/matplotlib/cbook.py
+++ b/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):
diff --git a/lib/matplotlib/testing/image_util.py b/lib/matplotlib/testing/image_util.py
index 65e9f1afae65..92bc0d6e8962 100644
--- a/lib/matplotlib/testing/image_util.py
+++ b/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