Merge pull request matplotlib#4091 from tacaswell/repl_hook

ENH : add function to add displayhook

Author: efiring

boilerplate.py

@@ -56,7 +56,6 @@ def %(func)s(%(argspec)s):
         %(ax)s.hold(hold)
     try:
         %(ret)s = %(ax)s.%(func)s(%(call)s)
-        draw_if_interactive()
     finally:
         %(ax)s.hold(%(washold)s)
 %(mappable)s
@@ -69,7 +68,6 @@ def %(func)s(%(argspec)s):
 @docstring.copy_dedent(Axes.%(func)s)
 def %(func)s(%(argspec)s):
     %(ret)s = gca().%(func)s(%(call)s)
-    draw_if_interactive()
     return %(ret)s
 """
 
@@ -85,7 +83,6 @@ def {name}():
 
     if im is not None:
         im.set_cmap(cm.{name})
-    draw_if_interactive()
 
 """
 
@@ -219,8 +216,9 @@ def format_value(value):
             else:
                 def_edited = []
                 for val in defaults:
-                    if isinstance(val, unicode):
-                        val = val.encode('ascii', 'ignore')
+                    if six.PY2:
+                        if isinstance(val, unicode):
+                            val = val.encode('ascii', 'ignore')
                     def_edited.append(val)
                 defaults = tuple(def_edited)
 
@@ -273,7 +271,7 @@ def format_value(value):
 
             # Since we can't avoid using some function names,
             # bail out if they are used as argument names
-            for reserved in ('gca', 'gci', 'draw_if_interactive'):
+            for reserved in ('gca', 'gci'):
                 if reserved in bad:
                     msg = 'Axes method %s has kwarg named %s' % (func, reserved)
                     raise ValueError(msg)

doc/users/whats_new/2015-05_interactive_OO.rst

@@ -0,0 +1,38 @@
+Interactive OO usage
+--------------------
+
+All `Artists` now keep track of if their internal state has been
+changed but not reflected in the display ('stale') by a call to
+``draw``.  It is thus possible to pragmatically determine if a given
+`Figure` needs to be re-drawn in an interactive session.
+
+To facilitate interactive usage a ``draw_all`` method has been added
+to ``pyplot`` which will redraw all of the figures which are 'stale'.
+
+To make this convenient for interactive use matplotlib now registers
+a function either with IPython's 'post_execute' event or with the
+displayhook in the standard python REPL to automatically call
+``plt.draw_all`` just before control is returned to the REPL.  This ensures
+that the draw command is deferred and only called once.
+
+The upshot of this is that for interactive backends (including
+``%matplotlib notebook``) in interactive mode (with ``plt.ion()``)
+
+.. ipython :: python
+
+   import matplotlib.pyplot as plt
+
+   fig, ax = plt.subplots()
+
+   ln, = ax.plot([0, 1, 4, 9, 16])
+
+   plt.show()
+
+   ln.set_color('g')
+
+
+will automatically update the plot to be green.  Any subsequent
+modifications to the ``Artist`` objects will do likewise.
+
+This is the first step of a larger consolidation and simplification of
+the pyplot internals.

lib/matplotlib/_pylab_helpers.py

@@ -139,5 +139,15 @@ def set_active(cls, manager):
         cls._activeQue.append(manager)
         cls.figs[manager.num] = manager
 
+    @classmethod
+    def draw_all(cls, force=False):
+        """
+        Redraw all figures registered with the pyplot
+        state machine.
+        """
+        for f_mgr in cls.get_all_fig_managers():
+            # TODO add logic to check if figure is stale
+            if force or f_mgr.canvas.figure.stale:
+                f_mgr.canvas.draw_idle()
 
 atexit.register(Gcf.destroy_all)

lib/matplotlib/artist.py

@@ -68,6 +68,14 @@ 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
+
+
 class Artist(object):
     """
     Abstract base class for someone who renders into a
@@ -78,6 +86,7 @@ class Artist(object):
     zorder = 0
 
     def __init__(self):
+        self._stale = True
         self._axes = None
         self.figure = None
 
@@ -210,9 +219,33 @@ def axes(self, new_axes):
                              "probably trying to re-use an artist "
                              "in more than one Axes which is not "
                              "supported")
+
         self._axes = new_axes
+        if new_axes is not None and new_axes is not self:
+            self.add_callback(_stale_axes_callback)
+
         return new_axes
 
+    @property
+    def stale(self):
+        """
+        If the artist is 'stale' and needs to be re-drawn for the output to
+        match the internal state of the artist.
+        """
+        return self._stale
+
+    @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()
+
     def get_window_extent(self, renderer):
         """
         Get the axes bounding box in display space.
@@ -283,6 +316,7 @@ def set_transform(self, t):
         self._transform = t
         self._transformSet = True
         self.pchanged()
+        self.stale = True
 
     def get_transform(self):
         """
@@ -499,6 +533,7 @@ def set_snap(self, snap):
         Only supported by the Agg and MacOSX backends.
         """
         self._snap = snap
+        self.stale = True
 
     def get_sketch_params(self):
         """
@@ -546,13 +581,15 @@ def set_sketch_params(self, scale=None, length=None, randomness=None):
             self._sketch = None
         else:
             self._sketch = (scale, length or 128.0, randomness or 16.0)
+        self.stale = True
 
     def set_path_effects(self, path_effects):
         """
         set path_effects, which should be a list of instances of
         matplotlib.patheffect._Base class or its derivatives.
         """
         self._path_effects = path_effects
+        self.stale = True
 
     def get_path_effects(self):
         return self._path_effects
@@ -572,7 +609,10 @@ def set_figure(self, fig):
         ACCEPTS: a :class:`matplotlib.figure.Figure` instance
         """
         self.figure = fig
-        self.pchanged()
+        if self.figure and self.figure is not self:
+            self.add_callback(_stale_figure_callback)
+            self.pchanged()
+        self.stale = True
 
     def set_clip_box(self, clipbox):
         """
@@ -582,6 +622,7 @@ def set_clip_box(self, clipbox):
         """
         self.clipbox = clipbox
         self.pchanged()
+        self.stale = True
 
     def set_clip_path(self, path, transform=None):
         """
@@ -634,8 +675,10 @@ def set_clip_path(self, path, transform=None):
         if not success:
             print(type(path), type(transform))
             raise TypeError("Invalid arguments to set_clip_path")
-
+        # this may result in the callbacks being hit twice, but grantees they
+        # will be hit at least once
         self.pchanged()
+        self.stale = True
 
     def get_alpha(self):
         """
@@ -684,7 +727,10 @@ def set_clip_on(self, b):
         ACCEPTS: [True | False]
         """
         self._clipon = b
+        # This may result in the callbacks being hit twice, but ensures they
+        # are hit at least once
         self.pchanged()
+        self.stale = True
 
     def _set_gc_clip(self, gc):
         'Set the clip properly for the gc'
@@ -723,11 +769,13 @@ def set_agg_filter(self, filter_func):
 
         """
         self._agg_filter = filter_func
+        self.stale = True
 
     def draw(self, renderer, *args, **kwargs):
         'Derived classes drawing method'
         if not self.get_visible():
             return
+        self.stale = False
 
     def set_alpha(self, alpha):
         """
@@ -738,6 +786,7 @@ def set_alpha(self, alpha):
         """
         self._alpha = alpha
         self.pchanged()
+        self.stale = True
 
     def set_visible(self, b):
         """
@@ -747,6 +796,7 @@ def set_visible(self, b):
         """
         self._visible = b
         self.pchanged()
+        self.stale = True
 
     def set_animated(self, b):
         """
@@ -756,6 +806,7 @@ def set_animated(self, b):
         """
         self._animated = b
         self.pchanged()
+        self.stale = True
 
     def update(self, props):
         """
@@ -778,6 +829,7 @@ def update(self, props):
         self.eventson = store
         if changed:
             self.pchanged()
+            self.stale = True
 
     def get_label(self):
         """
@@ -796,6 +848,7 @@ def set_label(self, s):
         else:
             self._label = None
         self.pchanged()
+        self.stale = True
 
     def get_zorder(self):
         """
@@ -812,6 +865,7 @@ def set_zorder(self, level):
         """
         self.zorder = level
         self.pchanged()
+        self.stale = True
 
     def update_from(self, other):
         'Copy properties from *other* to *self*.'
@@ -826,6 +880,7 @@ def update_from(self, other):
         self._sketch = other._sketch
         self._path_effects = other._path_effects
         self.pchanged()
+        self.stale = True
 
     def properties(self):
         """