Merge pull request #4229 from jdfreder/clearoutput

Clear_output: Animation & widget related changes.

docs/source/whatsnew/pr/clear_output.rst

@@ -0,0 +1,9 b''
+clear_output changes
+--------------------
+
+* There is no longer a 500ms delay when calling ``clear_output``.
+* The ability to clear stderr and stdout individually was removed.
+* A new ``wait`` flag that prevents ``clear_output`` from being executed until new 
+  output is available.  This eliminates animation flickering by allowing the 
+  user to double buffer the output.
+* The output div height is remembered when the ``wait=True`` flag is used.

IPython/core/display.py

@@ -657,35 +657,19 b' class Image(DisplayObject):'
         return unicode(s.split('.')[-1].lower())
 
 
-def clear_output(stdout=True, stderr=True, other=True):
+def clear_output(wait=False):
     """Clear the output of the current cell receiving output.
 
-    Optionally, each of stdout/stderr or other non-stream data (e.g. anything
-    produced by display()) can be excluded from the clear event.
-
-    By default, everything is cleared.
-
     Parameters
     ----------
-    stdout : bool [default: True]
-        Whether to clear stdout.
-    stderr : bool [default: True]
-        Whether to clear stderr.
-    other : bool [default: True]
-        Whether to clear everything else that is not stdout/stderr
-        (e.g. figures,images,HTML, any result of display()).
-    """
+    wait : bool [default: false]
+        Wait to clear the output until new output is available to replace it."""
     from IPython.core.interactiveshell import InteractiveShell
     if InteractiveShell.initialized():
-        InteractiveShell.instance().display_pub.clear_output(
-            stdout=stdout, stderr=stderr, other=other,
-        )
+        InteractiveShell.instance().display_pub.clear_output(wait)
     else:
         from IPython.utils import io
-        if stdout:
-            print('\033[2K\r', file=io.stdout, end='')
-            io.stdout.flush()
-        if stderr:
-            print('\033[2K\r', file=io.stderr, end='')
-            io.stderr.flush()
-
+        print('\033[2K\r', file=io.stdout, end='')
+        io.stdout.flush()
+        print('\033[2K\r', file=io.stderr, end='')
+        io.stderr.flush()

IPython/core/displaypub.py

@@ -108,14 +108,12 b' class DisplayPublisher(Configurable):'
         if 'text/plain' in data:
             print(data['text/plain'], file=io.stdout)
 
-    def clear_output(self, stdout=True, stderr=True, other=True):
+    def clear_output(self, wait=False):
         """Clear the output of the cell receiving output."""
-        if stdout:
-            print('\033[2K\r', file=io.stdout, end='')
-            io.stdout.flush()
-        if stderr:
-            print('\033[2K\r', file=io.stderr, end='')
-            io.stderr.flush()
+        print('\033[2K\r', file=io.stdout, end='')
+        io.stdout.flush()
+        print('\033[2K\r', file=io.stderr, end='')
+        io.stderr.flush()
 
 
 class CapturingDisplayPublisher(DisplayPublisher):
@@ -125,8 +123,8 b' class CapturingDisplayPublisher(DisplayPublisher):'
     def publish(self, source, data, metadata=None):
         self.outputs.append((source, data, metadata))
     
-    def clear_output(self, stdout=True, stderr=True, other=True):
-        super(CapturingDisplayPublisher, self).clear_output(stdout, stderr, other)
+    def clear_output(self, wait=False):
+        super(CapturingDisplayPublisher, self).clear_output(wait)
         if other:
             # empty the list, *do not* reassign a new list
             del self.outputs[:]

IPython/html/static/notebook/js/codecell.js

@@ -241,7 +241,7 b' var IPython = (function (IPython) {'
      * @method execute
      */
     CodeCell.prototype.execute = function () {
-        this.output_area.clear_output(true, true, true);
+        this.output_area.clear_output();
         this.set_input_prompt('*');
         this.element.addClass("running");
         if (this.last_msg_id) {
@@ -390,8 +390,8 b' var IPython = (function (IPython) {'
     };
 
 
-    CodeCell.prototype.clear_output = function (stdout, stderr, other) {
-        this.output_area.clear_output(stdout, stderr, other);
+    CodeCell.prototype.clear_output = function (wait) {
+        this.output_area.clear_output(wait);
     };
 
 

IPython/html/static/notebook/js/notebook.js

@@ -1339,7 +1339,7 b' var IPython = (function (IPython) {'
         var cells = this.get_cells();
         for (var i=0; i<ncells; i++) {
             if (cells[i] instanceof IPython.CodeCell) {
-                cells[i].clear_output(true,true,true);
+                cells[i].clear_output();
                 // Make all In[] prompts blank, as well
                 // TODO: make this configurable (via checkbox?)
                 cells[i].set_input_prompt();

IPython/html/static/notebook/js/outputarea.js

@@ -31,7 +31,7 b' var IPython = (function (IPython) {'
         this.outputs = [];
         this.collapsed = false;
         this.scrolled = false;
-        this.clear_out_timeout = null;
+        this.clear_queued = null;
         if (prompt_area === undefined) {
             this.prompt_area = true;
         } else {
@@ -289,7 +289,12 b' var IPython = (function (IPython) {'
     OutputArea.prototype.append_output = function (json, dynamic) {
         // If dynamic is true, javascript output will be eval'd.
         this.expand();
-        this.flush_clear_timeout();
+
+        // Clear the output if clear is queued.
+        if (this.clear_queued) {
+            this.clear_output(false);
+        }
+
         if (json.output_type === 'pyout') {
             this.append_pyout(json, dynamic);
         } else if (json.output_type === 'pyerr') {
@@ -300,6 +305,7 b' var IPython = (function (IPython) {'
             this.append_stream(json);
         }
         this.outputs.push(json);
+        this.element.height('auto');
         var that = this;
         setTimeout(function(){that.element.trigger('resize');}, 100);
     };
@@ -553,7 +559,6 b' var IPython = (function (IPython) {'
     OutputArea.prototype.append_raw_input = function (content) {
         var that = this;
         this.expand();
-        this.flush_clear_timeout();
         var area = this.create_output_area();
         
         // disable any other raw_inputs, if they are left around
@@ -606,81 +611,35 b' var IPython = (function (IPython) {'
 
 
     OutputArea.prototype.handle_clear_output = function (content) {
-        this.clear_output(content.stdout, content.stderr, content.other);
+        this.clear_output(content.wait);
     };
 
 
-    OutputArea.prototype.clear_output = function (stdout, stderr, other) {
-        var that = this;
-        if (this.clear_out_timeout != null){
-            // fire previous pending clear *immediately*
-            clearTimeout(this.clear_out_timeout);
-            this.clear_out_timeout = null;
-            this.clear_output_callback(this._clear_stdout, this._clear_stderr, this._clear_other);
-        }
-        // store flags for flushing the timeout
-        this._clear_stdout = stdout;
-        this._clear_stderr = stderr;
-        this._clear_other = other;
-        this.clear_out_timeout = setTimeout(function() {
-            // really clear timeout only after a short delay
-            // this reduces flicker in 'clear_output; print' cases
-            that.clear_out_timeout = null;
-            that._clear_stdout = that._clear_stderr = that._clear_other = null;
-            that.clear_output_callback(stdout, stderr, other);
-        }, 500
-        );
-    };
+    OutputArea.prototype.clear_output = function(wait) {
+        if (wait) {
 
+            // If a clear is queued, clear before adding another to the queue.
+            if (this.clear_queued) {
+                this.clear_output(false);
+            };
 
-    OutputArea.prototype.clear_output_callback = function (stdout, stderr, other) {
-        var output_div = this.element;
+            this.clear_queued = true;
+        } else {
 
-        if (stdout && stderr && other){
+            // Fix the output div's height if the clear_output is waiting for
+            // new output (it is being used in an animation).
+            if (this.clear_queued) {
+                var height = this.element.height();
+                this.element.height(height);
+                this.clear_queued = false;
+            }
+            
             // clear all, no need for logic
-            output_div.html("");
+            this.element.html("");
             this.outputs = [];
             this.unscroll_area();
             return;
-        }
-        // remove html output
-        // each output_subarea that has an identifying class is in an output_area
-        // which is the element to be removed.
-        if (stdout) {
-            output_div.find("div.output_stdout").parent().remove();
-        }
-        if (stderr) {
-            output_div.find("div.output_stderr").parent().remove();
-        }
-        if (other) {
-            output_div.find("div.output_subarea").not("div.output_stderr").not("div.output_stdout").parent().remove();
-        }
-        this.unscroll_area();
-        
-        // remove cleared outputs from JSON list:
-        for (var i = this.outputs.length - 1; i >= 0; i--) {
-            var out = this.outputs[i];
-            var output_type = out.output_type;
-            if (output_type == "display_data" && other) {
-                this.outputs.splice(i,1);
-            } else if (output_type == "stream") {
-                if (stdout && out.stream == "stdout") {
-                    this.outputs.splice(i,1);
-                } else if (stderr && out.stream == "stderr") {
-                    this.outputs.splice(i,1);
-                }
-            }
-        }
-    };
-
-
-    OutputArea.prototype.flush_clear_timeout = function() {
-        var output_div = this.element;
-        if (this.clear_out_timeout){
-            clearTimeout(this.clear_out_timeout);
-            this.clear_out_timeout = null;
-            this.clear_output_callback(this._clear_stdout, this._clear_stderr, this._clear_other);
-        }
+        };
     };
 
 

IPython/kernel/zmq/zmqshell.py

@@ -86,14 +86,11 b' class ZMQDisplayPublisher(DisplayPublisher):'
             parent=self.parent_header, ident=self.topic,
         )
 
-    def clear_output(self, stdout=True, stderr=True, other=True):
-        content = dict(stdout=stdout, stderr=stderr, other=other)
-        
-        if stdout:
-            print('\r', file=sys.stdout, end='')
-        if stderr:
-            print('\r', file=sys.stderr, end='')
-        
+    def clear_output(self, wait=False):
+        content = dict(wait=wait)
+
+        print('\r', file=sys.stdout, end='')
+        print('\r', file=sys.stderr, end='')
         self._flush_streams()
         
         self.session.send(

IPython/parallel/client/asyncresult.py

@@ -391,7 +391,7 b' class AsyncResult(object):'
         tic = time.time()
         while not self.ready() and (timeout < 0 or time.time() - tic <= timeout):
             self.wait(interval)
-            clear_output()
+            clear_output(wait=True)
             print("%4i/%i tasks finished after %4i s" % (self.progress, N, self.elapsed), end="")
             sys.stdout.flush()
         print()

docs/source/development/messaging.rst

@@ -984,6 +984,20 b' Message type: ``status``::'
         execution_state : ('busy', 'idle', 'starting')
     }
 
+Clear output
+------------
+
+This message type is used to clear the output that is visible on the frontend.
+
+Message type: ``clear_output``::
+
+    content = {
+
+        # Wait to clear the output until new output is available.  Clears the
+        # existing output immediately before the new output is displayed.  
+        # Useful for creating simple animations with minimal flickering.
+        'wait' : bool,
+    }
 
 Messages on the stdin ROUTER/DEALER sockets
 ===========================================

examples/notebooks/Animations Using clear_output.ipynb

@@ -21,7 +21,7 b''
      "source": [
       "Sometimes you want to clear the output area in the middle of a calculation.  This can be useful for doing simple animations. In terminals, there is the carriage-return (`'\\r'`) for overwriting a single line, but the notebook frontend can clear the whole output area, not just a single line.\n",
       "\n",
-      "To clear output in the Notebook you can use the `clear_output` function."
+      "To clear output in the Notebook you can use the `clear_output()` function.  If you are clearing the output every frame of an animation, calling `clear_output()` will create noticeable flickering.  You can use `clear_output(wait=True)` to add the *clear_output* call to a queue.  When data becomes available to replace the existing output, the *clear_output* will be called immediately before the new data is added.  This avoids the flickering by not rendering the cleared output to the screen."
      ]
     },
     {
@@ -58,7 +58,7 b''
       "from IPython.display import display, clear_output\n",
       "for i in range(10):\n",
       "    time.sleep(0.25)\n",
-      "    clear_output()\n",
+      "    clear_output(wait=True)\n",
       "    print(i)\n",
       "    sys.stdout.flush()"
      ],
@@ -166,7 +166,7 b''
       "for n in range(1,10):\n",
       "    time.sleep(1)\n",
       "    ax.plot(x, jn(x,n))\n",
-      "    clear_output()\n",
+      "    clear_output(wait=True)\n",
       "    display(f)\n",
       "\n",
       "# close the figure at the end, so we don't get a duplicate\n",

examples/parallel/InteractiveMPI-publish-data.ipynb

@@ -271,7 +271,7 b''
       "        # We clear the notebook output before plotting this if in-place \n",
       "        # plot updating is requested\n",
       "        if in_place:\n",
-      "            clear_output()\n",
+      "            clear_output(wait=True)\n",
       "        display(fig)\n",
       "        \n",
       "        return fig"
@@ -333,7 +333,7 b''
       "        msg = 'Simulation completed!'\n",
       "    tmon = dt.datetime.now() - t0\n",
       "    if plots_in_place and fig is not None:\n",
-      "        clear_output()\n",
+      "        clear_output(wait=True)\n",
       "        plt.close('all')\n",
       "        display(fig)\n",
       "    print msg\n",

examples/parallel/InteractiveMPI.ipynb

@@ -281,7 +281,7 b''
       "    plt.axis('off')\n",
       "    # We clear the notebook output before plotting this if in-place plot updating is requested\n",
       "    if in_place:\n",
-      "        clear_output()\n",
+      "        clear_output(wait=True)\n",
       "    display(fig)\n",
       "    return fig"
      ],
@@ -377,7 +377,7 b''
       "        msg = 'Simulation completed!'\n",
       "    tmon = dt.datetime.now() - t0\n",
       "    if plots_in_place and fig is not None:\n",
-      "        clear_output()\n",
+      "        clear_output(wait=True)\n",
       "        plt.close('all')\n",
       "        display(fig)\n",
       "    print msg\n",

examples/widgets/directview/directview.js

@@ -108,7 +108,7 b' DirectViewWidget.prototype.set_kernel = function (kernel) {'
 
 
 DirectViewWidget.prototype.execute = function () {
-    this.output_area.clear_output(true, true, true);
+    this.output_area.clear_output();
     this.element.addClass("running");
     var callbacks = {
         'execute_reply': $.proxy(this._handle_execute_reply, this),