new MatplotlibDeprecationWarning class

In light of the fact that Python builtin DeprecationWarnings are ignored
by default as of Python 2.7 (see link below), this class was put in to
allow for the signaling of deprecation, but via UserWarnings which are
not ignored by default.

http://docs.python.org/dev/whatsnew/2.7.html#the-future-for-python-2-x

Prior to this commit:

```
In [1]: %pylab

Welcome to pylab, a matplotlib-based Python environment [backend: agg].
For more information, type 'help(pylab)'.

In [2]: mlab.liaupunov([1,2], np.diff)
Out[2]: 0.0
```

After this commit:
```
In [1]: %pylab

Welcome to pylab, a matplotlib-based Python environment [backend: agg].
For more information, type 'help(pylab)'.

In [2]: mlab.liaupunov([1,2], np.diff)
/home/pi/.local/lib/python2.7/site-packages/matplotlib/mlab.py:1212:
MatplotlibDeprecationWarning: This does not belong in matplotlib and
will be removed
  mDeprecation) # 2009/06/13
Out[2]: 0.0
```

Author: ivanov

CHANGELOG

@@ -1,3 +1,13 @@
+2012-12-05 Added MatplotlibDeprecationWarning class for signaling deprecation.
+           Matplotlib developers can use this class as follows:
+
+           from matplotlib import MatplotlibDeprecationWarning as mDeprecation
+
+           In light of the fact that Python builtin DeprecationWarnings are
+           ignored by default as of Python 2.7, this class was put in to allow
+           for the signaling of deprecation, but via UserWarnings which are
+           not ignored by default. - PI
+
 2012-08-11 Fix path-closing bug in patches.Polygon, so that regardless
            of whether the path is the initial one or was subsequently
            set by set_xy(), get_xy() will return a closed path if and

lib/matplotlib/__init__.py

@@ -122,6 +122,20 @@
 if not hasattr(sys, 'argv'):  # for modpython
     sys.argv = ['modpython']
 
+
+class MatplotlibDeprecationWarning(UserWarning):
+    """
+    A class for issuing deprecation warnings for Matplotlib users.
+
+    In light of the fact that Python builtin DeprecationWarnings are ignored
+    by default as of Python 2.7 (see link below), this class was put in to
+    allow for the signaling of deprecation, but via UserWarnings which are not
+    ignored by default.
+
+    http://docs.python.org/dev/whatsnew/2.7.html#the-future-for-python-2-x
+    """
+    pass
+
 """
 Manage user customizations through a rc file.
 

lib/matplotlib/axes.py

@@ -36,6 +36,7 @@
 import matplotlib.ticker as mticker
 import matplotlib.transforms as mtransforms
 import matplotlib.tri as mtri
+from matplotlib import MatplotlibDeprecationWarning as mDeprecation
 from matplotlib.container import BarContainer, ErrorbarContainer, StemContainer
 
 iterable = cbook.iterable
@@ -150,8 +151,7 @@ def set_default_color_cycle(clist):
 
     """
     rcParams['axes.color_cycle'] = clist
-    warnings.warn("Set rcParams['axes.color_cycle'] directly",
-                                                    DeprecationWarning)
+    warnings.warn("Set rcParams['axes.color_cycle'] directly", mDeprecation)
 
 
 class _process_plot_var_args(object):
@@ -1376,11 +1376,11 @@ def get_child_artists(self):
 
         .. deprecated:: 0.98
         """
-        raise DeprecationWarning('Use get_children instead')
+        raise mDeprecation('Use get_children instead')
 
     def get_frame(self):
         """Return the axes Rectangle frame"""
-        warnings.warn('use ax.patch instead', DeprecationWarning)
+        warnings.warn('use ax.patch instead', mDeprecation)
         return self.patch
 
     def get_legend(self):
@@ -3112,13 +3112,13 @@ def connect(self, s, func):
         disconnect to disconnect from the axes event
 
         """
-        raise DeprecationWarning('use the callbacks CallbackRegistry instance '
-                                 'instead')
+        raise mDeprecation('use the callbacks CallbackRegistry instance '
+                           'instead')
 
     def disconnect(self, cid):
         """disconnect from the Axes event."""
-        raise DeprecationWarning('use the callbacks CallbackRegistry instance '
-                                 'instead')
+        raise mDeprecation('use the callbacks CallbackRegistry instance '
+                           'instead')
 
     def get_children(self):
         """return a list of child artists"""
@@ -3167,10 +3167,10 @@ def pick(self, *args):
         each child artist will fire a pick event if mouseevent is over
         the artist and the artist has picker set
         """
-        if len(args)>1:
-            raise DeprecationWarning('New pick API implemented -- '
-                                     'see API_CHANGES in the src distribution')
-        martist.Artist.pick(self,args[0])
+        if len(args) > 1:
+            raise mDeprecation('New pick API implemented -- '
+                               'see API_CHANGES in the src distribution')
+        martist.Artist.pick(self, args[0])
 
     def __pick(self, x, y, trans=None, among=None):
         """
@@ -3730,9 +3730,9 @@ def hlines(self, y, xmin, xmax, colors='k', linestyles='solid',
         .. plot:: mpl_examples/pylab_examples/hline_demo.py
         """
         if kwargs.get('fmt') is not None:
-            raise DeprecationWarning('hlines now uses a '
-                                     'collections.LineCollection and not a '
-                                     'list of Line2D to draw; see API_CHANGES')
+            raise mDeprecation('hlines now uses a '
+                               'collections.LineCollection and not a '
+                               'list of Line2D to draw; see API_CHANGES')
 
         # We do the conversion first since not all unitized data is uniform
         # process the unit information
@@ -3810,9 +3810,9 @@ def vlines(self, x, ymin, ymax, colors='k', linestyles='solid',
         """
 
         if kwargs.get('fmt') is not None:
-            raise DeprecationWarning('vlines now uses a '
-                                     'collections.LineCollection and not a '
-                                     'list of Line2D to draw; see API_CHANGES')
+            raise mDeprecation('vlines now uses a '
+                               'collections.LineCollection and not a '
+                               'list of Line2D to draw; see API_CHANGES')
 
         self._process_unit_info(xdata=x, ydata=[ymin, ymax], kwargs=kwargs)
 
@@ -6086,7 +6086,7 @@ def scatter(self, x, y, s=20, c='b', marker='o', cmap=None, norm=None,
             edgecolors = 'none'
             warnings.warn(
                 '''replace "faceted=False" with "edgecolors='none'"''',
-                DeprecationWarning)   #2008/04/18
+                mDeprecation)  # 2008/04/18
 
         sym = None
         symstyle = 0
@@ -7999,7 +7999,7 @@ def hist(self, x, bins=10, range=None, normed=False, weights=None,
 
 
         if kwargs.get('width') is not None:
-            raise DeprecationWarning(
+            raise mDeprecation(
                 'hist now uses the rwidth to give relative width '
                 'and not absolute width')
 
@@ -8715,7 +8715,7 @@ def spy(self, Z, precision=0, marker=None, markersize=None,
         """
         if precision is None:
             precision = 0
-            warnings.DeprecationWarning("Use precision=0 instead of None")
+            warnings.warn("Use precision=0 instead of None", mDeprecation)
             # 2008/10/03
         if marker is None and markersize is None and hasattr(Z, 'tocoo'):
             marker = 's'

lib/matplotlib/backend_bases.py

@@ -46,6 +46,7 @@
 import matplotlib.tight_bbox as tight_bbox
 import matplotlib.textpath as textpath
 from matplotlib.path import Path
+from matplotlib import MatplotlibDeprecationWarning as mDeprecation
 
 try:
     from PIL import Image
@@ -2274,7 +2275,7 @@ def start_event_loop_default(self,timeout=0):
         """
         str = "Using default event loop until function specific"
         str += " to this GUI is implemented"
-        warnings.warn(str,DeprecationWarning)
+        warnings.warn(str, mDeprecation)
 
         if timeout <= 0: timeout = np.inf
         timestep = 0.01

lib/matplotlib/backends/backend_qt.py

@@ -4,9 +4,11 @@
 import sys
 import warnings
 
+from matplotlib import MatplotlibDeprecationWarning as mDeprecation
+
 warnings.warn("QT3-based backends are deprecated and will be removed after"
               " the v1.2.x release. Use the equivalent QT4 backend instead.",
-              DeprecationWarning)
+              mDeprecation)
 
 import matplotlib
 from matplotlib import verbose

lib/matplotlib/backends/backend_wx.py

@@ -25,6 +25,7 @@
 
 import numpy as np
 
+from matplotlib import MatplotlibDeprecationWarning as mDeprecation
 
 # Debugging settings here...
 # Debug level set here. If the debug level is less than 5, information
@@ -792,7 +793,7 @@ def Printer_Init(self):
 
         Deprecated.
         """
-        warnings.warn("Printer* methods will be removed", DeprecationWarning)
+        warnings.warn("Printer* methods will be removed", mDeprecation)
         self.printerData = wx.PrintData()
         self.printerData.SetPaperId(wx.PAPER_LETTER)
         self.printerData.SetPrintMode(wx.PRINT_MODE_PRINTER)
@@ -806,7 +807,7 @@ def Printer_Init(self):
 
     def _get_printerData(self):
         if self._printerData is None:
-            warnings.warn("Printer* methods will be removed", DeprecationWarning)
+            warnings.warn("Printer* methods will be removed", mDeprecation)
             self._printerData = wx.PrintData()
             self._printerData.SetPaperId(wx.PAPER_LETTER)
             self._printerData.SetPrintMode(wx.PRINT_MODE_PRINTER)
@@ -815,7 +816,7 @@ def _get_printerData(self):
 
     def _get_printerPageData(self):
         if self._printerPageData is None:
-            warnings.warn("Printer* methods will be removed", DeprecationWarning)
+            warnings.warn("Printer* methods will be removed", mDeprecation)
             self._printerPageData= wx.PageSetupDialogData()
             self._printerPageData.SetMarginBottomRight((25,25))
             self._printerPageData.SetMarginTopLeft((25,25))
@@ -834,7 +835,7 @@ def Printer_Setup(self, event=None):
         dmsg = """Width of output figure in inches.
 The current aspect ratio will be kept."""
 
-        warnings.warn("Printer* methods will be removed", DeprecationWarning)
+        warnings.warn("Printer* methods will be removed", mDeprecation)
         dlg = wx.Dialog(self, -1, 'Page Setup for Printing' , (-1,-1))
         df = dlg.GetFont()
         df.SetWeight(wx.NORMAL)
@@ -897,7 +898,7 @@ def Printer_Setup2(self, event=None):
         Deprecated.
         """
 
-        warnings.warn("Printer* methods will be removed", DeprecationWarning)
+        warnings.warn("Printer* methods will be removed", mDeprecation)
         if hasattr(self, 'printerData'):
             data = wx.PageSetupDialogData()
             data.SetPrintData(self.printerData)
@@ -921,7 +922,7 @@ def Printer_Preview(self, event=None):
 
         Deprecated.
         """
-        warnings.warn("Printer* methods will be removed", DeprecationWarning)
+        warnings.warn("Printer* methods will be removed", mDeprecation)
         po1  = PrintoutWx(self, width=self.printer_width,
                           margin=self.printer_margin)
         po2  = PrintoutWx(self, width=self.printer_width,
@@ -947,7 +948,7 @@ def Printer_Print(self, event=None):
 
         Deprecated.
         """
-        warnings.warn("Printer* methods will be removed", DeprecationWarning)
+        warnings.warn("Printer* methods will be removed", mDeprecation)
         pdd = wx.PrintDialogData()
         # SetPrintData for 2.4 combatibility
         pdd.SetPrintData(self.printerData)

lib/matplotlib/cbook.py

@@ -22,6 +22,7 @@
 from weakref import ref, WeakKeyDictionary
 
 import matplotlib
+from matplotlib import MatplotlibDeprecationWarning as mDeprecation
 
 import numpy as np
 import numpy.ma as ma
@@ -281,7 +282,7 @@ def __init__(self, *args):
             warnings.warn(
                 'CallbackRegistry no longer requires a list of callback types.'
                 ' Ignoring arguments',
-                DeprecationWarning)
+                mDeprecation)
         self.callbacks = dict()
         self._cid = 0
         self._func_cid_map = {}
@@ -1676,7 +1677,7 @@ def less_simple_linear_interpolation(x, y, xi, extrap=False):
     # deprecated from cbook in 0.98.4
     warnings.warn('less_simple_linear_interpolation has been moved to '
                   'matplotlib.mlab -- please import it from there',
-                  DeprecationWarning)
+                  mDeprecation)
     import matplotlib.mlab as mlab
     return mlab.less_simple_linear_interpolation(x, y, xi, extrap=extrap)
 
@@ -1688,7 +1689,7 @@ def vector_lengths(X, P=2.0, axis=None):
     """
     # deprecated from cbook in 0.98.4
     warnings.warn('vector_lengths has been moved to matplotlib.mlab -- '
-                  'please import it from there', DeprecationWarning)
+                  'please import it from there', mDeprecation)
     import matplotlib.mlab as mlab
     return mlab.vector_lengths(X, P=2.0, axis=axis)
 
@@ -1700,7 +1701,7 @@ def distances_along_curve(X):
     """
     # deprecated from cbook in 0.98.4
     warnings.warn('distances_along_curve has been moved to matplotlib.mlab '
-                  '-- please import it from there', DeprecationWarning)
+                  '-- please import it from there', mDeprecation)
     import matplotlib.mlab as mlab
     return mlab.distances_along_curve(X)
 
@@ -1712,7 +1713,7 @@ def path_length(X):
     """
     # deprecated from cbook in 0.98.4
     warnings.warn('path_length has been moved to matplotlib.mlab '
-                  '-- please import it from there', DeprecationWarning)
+                  '-- please import it from there', mDeprecation)
     import matplotlib.mlab as mlab
     return mlab.path_length(X)
 
@@ -1724,7 +1725,7 @@ def is_closed_polygon(X):
     """
     # deprecated from cbook in 0.98.4
     warnings.warn('is_closed_polygon has been moved to matplotlib.mlab '
-                  '-- please import it from there', DeprecationWarning)
+                  '-- please import it from there', mDeprecation)
     import matplotlib.mlab as mlab
     return mlab.is_closed_polygon(X)
 
@@ -1736,7 +1737,7 @@ def quad2cubic(q0x, q0y, q1x, q1y, q2x, q2y):
     """
     # deprecated from cbook in 0.98.4
     warnings.warn('quad2cubic has been moved to matplotlib.mlab -- please '
-                  'import it from there', DeprecationWarning)
+                  'import it from there', mDeprecation)
     import matplotlib.mlab as mlab
     return mlab.quad2cubic(q0x, q0y, q1x, q1y, q2x, q2y)
 

lib/matplotlib/legend.py

@@ -31,6 +31,7 @@
 from matplotlib.offsetbox import DraggableOffsetBox
 
 from matplotlib.container import ErrorbarContainer, BarContainer, StemContainer
+from matplotlib import MatplotlibDeprecationWarning as mDeprecation
 import legend_handler
 
 
@@ -278,7 +279,7 @@ def __init__(self, parent, handles, labels,
             # counter part is None.
             if localdict[k] is not None and localdict[v] is None:
                 warnings.warn("Use '%s' instead of '%s'." % (v, k),
-                              DeprecationWarning)
+                              mDeprecation)
                 setattr(self, v, localdict[k] * axessize_fontsize)
                 continue
 

lib/matplotlib/mlab.py

@@ -148,6 +148,7 @@
 import numpy as np
 ma = np.ma
 from matplotlib import verbose
+from matplotlib import MatplotlibDeprecationWarning as mDeprecation
 
 import matplotlib.cbook as cbook
 from matplotlib import docstring
@@ -1207,7 +1208,8 @@ def liaupunov(x, fprime):
         It also seems that this function's name is badly misspelled.
     """
 
-    warnings.warn("This does not belong in matplotlib and will be removed", DeprecationWarning) # 2009/06/13
+    warnings.warn("This does not belong in matplotlib and will be removed",
+                    mDeprecation) # 2009/06/13
 
     return np.mean(np.log(np.absolute(fprime(x))))
 
@@ -1339,7 +1341,7 @@ def save(fname, X, fmt='%.18e',delimiter=' '):
     for comma-separated values.
     """
 
-    warnings.warn("use numpy.savetxt", DeprecationWarning)  # 2009/06/13
+    warnings.warn("use numpy.savetxt", mDeprecation)  # 2009/06/13
 
     if cbook.is_string_like(fname):
         if fname.endswith('.gz'):
@@ -1426,7 +1428,7 @@ def load(fname,comments='#',delimiter=None, converters=None,skiprows=0,
            Exercises many of these options.
     """
 
-    warnings.warn("use numpy.loadtxt", DeprecationWarning)  # 2009/06/13
+    warnings.warn("use numpy.loadtxt", mDeprecation)  # 2009/06/13
 
     if converters is None: converters = {}
     fh = cbook.to_filehandle(fname)