deprecate undocumented matplotlib/mpl.py

`matplotlib/mpl.py` is a file which used to get imported via ipython's
`%pyplot` interface as module named `mpl`, yet it isn't clear at all
what it's role is.

Given that in our own code, and in the rest of our python neighborhood,
we often do `import matplotlib as mpl`, it's quite a bit confusing to
have something with the `mpl` name within matplotlib not be the
`matplotlib` module itself.

This module was only used in `pylab` interface, where it was simply
imported in one line via `from matplotlib import mpl` and never used
again. With the exception of mpl.finance, all of the modules in mpl.py
were readily available simply via "import matplotlib as mpl".

pylab's mpl.finance functionality is retained for backwards
compatability.

Author: ivanov

CHANGELOG

@@ -17,6 +17,9 @@
            This allows backends to utilize additional text attributes, like
            the alignment of text elements. - pwuertz
 
+2012-11-26 deprecate matplotlib/mpl.py, which was used only in pylab.py and is
+           now replaced by the more suitable `import matplotlib as mpl`. - PI
+
 2012-11-16 plt.set_cmap no longer throws errors if there is not already
            an active colorable artist, such as an image, and just sets
            up the colormap to use from that point forward. - PI
@@ -27,6 +30,7 @@
            color so that any alpha set by  markerfacecolor will respected.
 	   - Thomas Caswell
 
+>>>>>>> deprecate undocumented `matplotlib/mpl.py`
 2012-11-13 Add a symmetric log normalization class to colors.py.
            Also added some tests for the normalization class.
            Till Stensitzki

lib/matplotlib/mpl.py

@@ -1,3 +1,8 @@
+import warnings
+warnings.warn(
+    "matplotlib.mpl is deprecated and will be removed in the next release."
+    "Please use `import matplotlib as mpl` instead",
+    DeprecationWarning)
 from matplotlib import artist
 from matplotlib import axis
 from matplotlib import axes

lib/matplotlib/pylab.py

@@ -219,7 +219,10 @@
 from matplotlib.cbook import flatten, is_string_like, exception_to_str, \
      silent_list, iterable, dedent
 
-from matplotlib import mpl  # pulls in most modules
+import matplotlib as mpl
+# make mpl.finance module available for backwards compatability, in case folks
+# using pylab interface depended on not having to import it
+import matplotlib.finance
 
 from matplotlib.dates import date2num, num2date,\
         datestr2num, strpdate2num, drange,\