Merge remote-tracking branch 'matplotlib/master'

Author: ericmjl

doc/devel/documenting_mpl.rst

@@ -86,21 +86,23 @@ function that takes a ``**kwargs``.  The requirements are:
 2. as automated as possible so that as properties change, the docs
    are updated automagically.
 
-The functions :attr:`matplotlib.artist.kwdocd` and
-:func:`matplotlib.artist.kwdoc` to facilitate this.  They combine
+The function :func:`matplotlib.artist.kwdoc` and the decorator
+:func:`matplotlib.docstring.dedent_interpd` facilitate this.  They combine
 python string interpolation in the docstring with the matplotlib
 artist introspection facility that underlies ``setp`` and ``getp``.
-The ``kwdocd`` is a single dictionary that maps class name to a
-docstring of ``kwargs``.  Here is an example from
+The ``kwdoc`` function gives the list of properties as a docstring. In order
+to use this in another docstring, first update the
+``matplotlib.docstring.interpd`` object, as seen in this example from
 :mod:`matplotlib.lines`::
 
   # in lines.py
-  artist.kwdocd['Line2D'] = artist.kwdoc(Line2D)
+  docstring.interpd.update(Line2D=artist.kwdoc(Line2D))
 
 Then in any function accepting :class:`~matplotlib.lines.Line2D`
 pass-through ``kwargs``, e.g., :meth:`matplotlib.axes.Axes.plot`::
 
   # in axes.py
+  @docstring.dedent_interpd
   def plot(self, *args, **kwargs):
       """
       Some stuff omitted
@@ -114,7 +116,6 @@ pass-through ``kwargs``, e.g., :meth:`matplotlib.axes.Axes.plot`::
       information
       """
       pass
-  plot.__doc__ = cbook.dedent(plot.__doc__) % artist.kwdocd
 
 Note there is a problem for :class:`~matplotlib.artist.Artist`
 ``__init__`` methods, e.g., :meth:`matplotlib.patches.Patch.__init__`,
@@ -123,7 +124,7 @@ work until the class is fully defined and we can't modify the
 ``Patch.__init__.__doc__`` docstring outside the class definition.
 There are some some manual hacks in this case, violating the
 "single entry point" requirement above -- see the
-``artist.kwdocd['Patch']`` setting in :mod:`matplotlib.patches`.
+``docstring.interpd.update`` calls in :mod:`matplotlib.patches`.
 
 .. _formatting-mpl-docs:
 

doc/faq/usage_faq.rst

@@ -430,7 +430,8 @@ WXAgg          Agg rendering to to a :term:`wxWidgets` canvas
 WX             Native :term:`wxWidgets` drawing to a :term:`wxWidgets` Canvas
                (not recommended) (requires wxPython_)
 TkAgg          Agg rendering to a :term:`Tk` canvas (requires TkInter_)
-Qt4Agg         Agg rendering to a :term:`Qt4` canvas (requires PyQt4_)
+Qt4Agg         Agg rendering to a :term:`Qt4` canvas (requires PyQt4_ or ``pyside``)
+Qt5Agg         Agg rendering in a :term:`Qt5` canvas (requires PyQt5_)
 macosx         Cocoa rendering in OSX windows
                (presently lacks blocking show() behavior when matplotlib
                is in non-interactive mode)
@@ -448,6 +449,7 @@ macosx         Cocoa rendering in OSX windows
 .. _wxPython: http://www.wxpython.org/
 .. _TkInter: http://wiki.python.org/moin/TkInter
 .. _PyQt4: http://www.riverbankcomputing.co.uk/software/pyqt/intro
+.. _PyQt5: http://www.riverbankcomputing.co.uk/software/pyqt/intro
 
 How do I select PyQt4 or PySide?
 ========================================

doc/glossary/index.rst

@@ -73,9 +73,9 @@ Glossary
   pyqt
       `pyqt <http://wiki.python.org/moin/PyQt>`_ provides python
       wrappers for the :term:`Qt` widgets library and is required by
-      the matplotlib QtAgg and Qt4Agg backends.  Widely used on linux
+      the matplotlib Qt5Agg and Qt4Agg backends.  Widely used on linux
       and windows; many linux distributions package this as
-      'python-qt3' or 'python-qt4'.
+      'python-qt5' or 'python-qt4'.
 
   python
       `python <http://python.org>`_ is an object oriented interpreted
@@ -91,13 +91,18 @@ Glossary
 
 
   Qt
-      `Qt <http://trolltech.com/products/qt/>`__ is a cross-platform
+      `Qt <http://www.qt.io/>`__ is a cross-platform
       application framework for desktop and embedded development.
 
   Qt4
-      `Qt4 <http://trolltech.com/products/qt/>`__ is the most recent
-      version of Qt cross-platform application framework for desktop
-      and embedded development.
+      `Qt4 <http://doc.qt.io/qt-4.8/index.html>`__ is the previous,
+      but most widely used, version of Qt cross-platform application
+      framework for desktop and embedded development.
+
+  Qt5
+      `Qt5 <http://doc.qt.io/qt-5/index.html>`__ is the current
+      version of Qt cross-platform application
+      framework for desktop and embedded development.
 
   raster graphics
       `Raster graphics

doc/users/whats_new/styles.rst

@@ -0,0 +1,15 @@
+Styles
+------
+
+Several new styles have been added, including many styles from the Seaborn project.
+Additionally, in order to prep for the upcoming 2.0 style-change release, a 'classic' and 'default' style has been added.
+For this release, the 'default' and 'classic' styles are identical.
+By using them now in your scripts, you can help ensure a smooth transition during future upgrades of matplotlib, so that you can upgrade to the snazzy new defaults when you are ready! ::
+
+    import matplotlib.style
+    matplotlib.style.use('classic')
+
+The 'default' style will give you matplotlib's latest plotting styles::
+
+    matplotlib.style.use('default')
+

examples/pylab_examples/major_minor_demo1.py

@@ -1,4 +1,3 @@
-#!/usr/bin/env python
 """
 Demonstrate how to use major and minor tickers.
 
@@ -19,7 +18,7 @@
 some base.  The FormatStrFormatter uses a string format string (e.g.,
 '%d' or '%1.2f' or '%1.1f cm' ) to format the tick
 
-The pylab interface grid command changes the grid settings of the
+The pyplot interface grid command changes the grid settings of the
 major ticks of the y and y axis together.  If you want to control the
 grid of the minor ticks for a given axis, use for example
 

examples/pylab_examples/manual_axis.py

@@ -5,11 +5,10 @@
 
 This example should be considered deprecated and is left just for demo
 purposes for folks wanting to make a pseudo-axis
-
 """
 
 import numpy as np
-from pylab import figure, show
+import matplotlib.pyplot as plt
 import matplotlib.lines as lines
 
 
@@ -47,7 +46,7 @@ def make_yaxis(ax, xloc=0, offset=0.05, **props):
 props = dict(color='black', linewidth=2, markeredgewidth=2)
 x = np.arange(200.)
 y = np.sin(2*np.pi*x/200.) + np.random.rand(200) - 0.5
-fig = figure(facecolor='white')
+fig = plt.figure(facecolor='white')
 ax = fig.add_subplot(111, frame_on=False)
 ax.axison = False
 ax.plot(x, y, 'd', markersize=8, markerfacecolor='blue')
@@ -56,4 +55,4 @@ def make_yaxis(ax, xloc=0, offset=0.05, **props):
 make_xaxis(ax, 0, offset=0.1, **props)
 make_yaxis(ax, 0, offset=5, **props)
 
-show()
+plt.show()

examples/pylab_examples/matplotlib_icon.py

@@ -1,20 +1,21 @@
-#!/usr/bin/env python
 """
 make the matplotlib svg minimization icon
 """
+import matplotlib.pyplot as plt
 import matplotlib
-#matplotlib.use('Svg')
-from pylab import *
+import numpy as np
 
-rc('grid', ls='-', lw=2, color='k')
-fig = figure(figsize=(1, 1), dpi=72)
-axes([0.025, 0.025, 0.95, 0.95], axisbg='#bfd1d4')
+matplotlib.rc('grid', ls='-', lw=2, color='k')
+fig = plt.figure(figsize=(1, 1), dpi=72)
+plt.axes([0.025, 0.025, 0.95, 0.95], axisbg='#bfd1d4')
 
-t = arange(0, 2, 0.05)
-s = sin(2*pi*t)
-plot(t, s, linewidth=4, color="#ca7900")
-axis([-.2, 2.2, -1.2, 1.2])
+t = np.arange(0, 2, 0.05)
+s = np.sin(2*np.pi*t)
+plt.plot(t, s, linewidth=4, color="#ca7900")
+plt.axis([-.2, 2.2, -1.2, 1.2])
 
-# grid(True)
-setp(gca(), xticklabels=[], yticklabels=[])
-savefig('matplotlib', facecolor='0.75')
+ax = plt.gca()
+ax.set_xticklabels([])
+ax.set_yticklabels([])
+
+plt.show()

examples/pylab_examples/system_monitor.py

@@ -21,13 +21,13 @@ def get_net():
 def get_stats():
     return get_memory(), get_cpu(), get_net()
 
-
-# turn interactive mode on for dynamic updates.  If you aren't in
-# interactive mode, you'll need to use a GUI event handler/timer.
-plt.ion()
-
 fig, ax = plt.subplots()
 ind = np.arange(1, 4)
+
+# show the figure, but do not block
+plt.show(block=False)
+
+
 pm, pc, pn = plt.bar(ind, get_stats())
 centers = ind + 0.5*pm.get_width()
 pm.set_facecolor('r')
@@ -44,10 +44,21 @@ def get_stats():
 for i in range(200):  # run for a little while
     m, c, n = get_stats()
 
+    # update the animated artists
     pm.set_height(m)
     pc.set_height(c)
     pn.set_height(n)
+
+    # ask the canvas to re-draw itself the next time it
+    # has a chance.
+    # For most of the GUI backends this adds an event to the queue
+    # of the GUI frameworks event loop.
+    fig.canvas.draw_idle()
     try:
+        # make sure that the GUI framework has a chance to run its event loop
+        # and clear any GUI events.  This needs to be in a try/except block
+        # because the default implemenation of this method is to raise
+        # NotImplementedError
         fig.canvas.flush_events()
     except NotImplementedError:
         pass

lib/matplotlib/animation.py

@@ -1030,17 +1030,18 @@ def __init__(self, fig, artists, *args, **kwargs):
 
     def _init_draw(self):
         # Make all the artists involved in *any* frame invisible
-        axes = []
+        figs = set()
         for f in self.new_frame_seq():
             for artist in f:
                 artist.set_visible(False)
+                artist.set_animated(self._blit)
                 # Assemble a list of unique axes that need flushing
-                if artist.axes not in axes:
-                    axes.append(artist.axes)
+                if artist.axes.figure not in figs:
+                    figs.add(artist.axes.figure)
 
         # Flush the needed axes
-        for ax in axes:
-            ax.figure.canvas.draw()
+        for fig in figs:
+            fig.canvas.draw()
 
     def _pre_draw(self, framedata, blit):
         '''
@@ -1155,6 +1156,8 @@ def _init_draw(self):
             self._draw_frame(next(self.new_frame_seq()))
         else:
             self._drawn_artists = self._init_func()
+            for a in self._drawn_artists:
+                a.set_animated(self._blit)
 
     def _draw_frame(self, framedata):
         # Save the data for potential saving of movies.
@@ -1167,3 +1170,5 @@ def _draw_frame(self, framedata):
         # Call the func with framedata and args. If blitting is desired,
         # func needs to return a sequence of any artists that were modified.
         self._drawn_artists = self._func(framedata, *self._args)
+        for a in self._drawn_artists:
+            a.set_animated(self._blit)

lib/matplotlib/artist.py

@@ -68,12 +68,9 @@ def draw_wrapper(artist, renderer, *args, **kwargs):
     return draw_wrapper
 
 
-def _stale_figure_callback(self):
-    self.figure.stale = True
-
-
-def _stale_axes_callback(self):
-    self.axes.stale = True
+def _stale_axes_callback(self, val):
+    if self.axes:
+        self.axes.stale = val
 
 
 class Artist(object):
@@ -87,6 +84,7 @@ class Artist(object):
 
     def __init__(self):
         self._stale = True
+        self.stale_callback = None
         self._axes = None
         self.figure = None
 
@@ -124,6 +122,7 @@ def __getstate__(self):
         # remove the unpicklable remove method, this will get re-added on load
         # (by the axes) if the artist lives on an axes.
         d['_remove_method'] = None
+        d['stale_callback'] = None
         return d
 
     def remove(self):
@@ -222,7 +221,7 @@ def axes(self, new_axes):
 
         self._axes = new_axes
         if new_axes is not None and new_axes is not self:
-            self.add_callback(_stale_axes_callback)
+            self.stale_callback = _stale_axes_callback
 
         return new_axes
 
@@ -236,15 +235,16 @@ def stale(self):
 
     @stale.setter
     def stale(self, val):
-        # only trigger call-back stack on being marked as 'stale'
-        # when not already stale
-        # the draw process will take care of propagating the cleaning
-        # process
-        if not (self._stale == val):
-            self._stale = val
-            # only trigger propagation if marking as stale
-            if self._stale:
-                self.pchanged()
+        self._stale = val
+
+        # if the artist is animated it does not take normal part in the
+        # draw stack and is not expected to be drawn as part of the normal
+        # draw loop (when not saving) so do not propagate this change
+        if self.get_animated():
+            return
+
+        if val and self.stale_callback is not None:
+            self.stale_callback(self, val)
 
     def get_window_extent(self, renderer):
         """
@@ -608,9 +608,19 @@ def set_figure(self, fig):
 
         ACCEPTS: a :class:`matplotlib.figure.Figure` instance
         """
+        # if this is a no-op just return
+        if self.figure is fig:
+            return
+        # if we currently have a figure (the case of both `self.figure`
+        # and `fig` being none is taken care of above) we then user is
+        # trying to change the figure an artist is associated with which
+        # is not allowed for the same reason as adding the same instance
+        # to more than one Axes
+        if self.figure is not None:
+            raise RuntimeError("Can not put single artist in "
+                               "more than one figure")
         self.figure = fig
         if self.figure and self.figure is not self:
-            self.add_callback(_stale_figure_callback)
             self.pchanged()
         self.stale = True
 
@@ -804,9 +814,9 @@ def set_animated(self, b):
 
         ACCEPTS: [True | False]
         """
-        self._animated = b
-        self.pchanged()
-        self.stale = True
+        if self._animated != b:
+            self._animated = b
+            self.pchanged()
 
     def update(self, props):
         """