new MatplotlibDeprecationWarning class (against 1.2.x)

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 mplDeprecation
+
+           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 mplDeprecation
 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", mplDeprecation)
 
 
 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 mplDeprecation('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', mplDeprecation)
         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 mplDeprecation('use the callbacks CallbackRegistry instance '
+                             'instead')
 
     def disconnect(self, cid):
         """disconnect from the Axes event."""
-        raise DeprecationWarning('use the callbacks CallbackRegistry instance '
-                                 'instead')
+        raise mplDeprecation('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 mplDeprecation('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 mplDeprecation('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 mplDeprecation('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
+                mplDeprecation)  # 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 mplDeprecation(
                 '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", mplDeprecation)
             # 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 mplDeprecation
 
 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, mplDeprecation)
 
         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 mplDeprecation
+
 warnings.warn("QT3-based backends are deprecated and will be removed after"
               " the v1.2.x release. Use the equivalent QT4 backend instead.",
-              DeprecationWarning)
+              mplDeprecation)
 
 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 mplDeprecation
 
 # 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", mplDeprecation)
         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", mplDeprecation)
             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", mplDeprecation)
             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", mplDeprecation)
         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", mplDeprecation)
         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", mplDeprecation)
         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", mplDeprecation)
         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 mplDeprecation
 
 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)
+                mplDeprecation)
         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)
+                  mplDeprecation)
     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', mplDeprecation)
     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', mplDeprecation)
     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', mplDeprecation)
     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', mplDeprecation)
     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', mplDeprecation)
     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 mplDeprecation
 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)
+                              mplDeprecation)
                 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 mplDeprecation
 
 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",
+                  mplDeprecation) # 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", mplDeprecation)  # 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", mplDeprecation)  # 2009/06/13
 
     if converters is None: converters = {}
     fh = cbook.to_filehandle(fname)