Backport PR #10048 on branch 5.x

Implement update_display (94d6f5bc677f8ed924f46d79badaa5777b4820d5)

examples/IPython Kernel/Updating Displays.ipynb

@@ -0,0 +1,359 b''
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Updatable Displays\n",
+    "\n",
+    "Note: This feature requires notebook >= 5.0 or JupyterLab, and \n",
+    "\n",
+    "\n",
+    "IPython 6 implements a new API as part of the Jupyter Protocol version 5.1 for easily updating displays.\n",
+    "\n",
+    "When you display something, you can now pass a `display_id` argument to attach an id to that output.\n",
+    "\n",
+    "Any future display with the same ID will also update other displays that had the same ID.\n",
+    "\n",
+    "`display` with a `display_id` will return a `DisplayHandle`\n",
+    "object, which gives you easy access to update the output:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "from IPython.display import display, update_display"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'z'"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/plain": [
+       "<DisplayHandle display_id=update-me>"
+      ]
+     },
+     "execution_count": 13,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "handle = display('x', display_id='update-me')\n",
+    "handle"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "When we call `handle.display('y')`, we get a new display of 'y',\n",
+    "but in addition to that, we updated the previous display."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'z'"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "handle.display('y')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can also *just* update the existing displays,\n",
+    "without creating a new display:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "handle.update('z')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You don't have to generate display_ids yourself,\n",
+    "if you specify `display_id=True`, then a unique ID will be assigned:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'hello'"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/plain": [
+       "<DisplayHandle display_id=07fc47b2ef652ccb70addeee3eb0981a>"
+      ]
+     },
+     "execution_count": 16,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "handle = display(\"hello\", display_id=True)\n",
+    "handle"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Calling `handle.display(obj)` is the same as calling `display(obj, handle.display_id)`,\n",
+    "so you don't need to use the handle objects if you don't want to:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 17,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'z'"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "display('x', display_id='here');"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 18,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'z'"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "display('y', display_id='here');"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "And just like `display`, there is now `update_display`,\n",
+    "which is what `DisplayHandle.update` calls:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 19,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "update_display('z', display_id='here')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## More detailed example\n",
+    "\n",
+    "One of the motivating use cases for this is simple progress bars.\n",
+    "\n",
+    "Here is an example ProgressBar using these APIs:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 35,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "<progress\n",
+       "            value=10\n",
+       "            max=10\n",
+       "            style=\"width: 60ex\"/>\n",
+       "            10 / 10\n",
+       "        "
+      ],
+      "text/plain": [
+       "[============================================================] 10/10"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "import os\n",
+    "from binascii import hexlify\n",
+    "\n",
+    "class ProgressBar(object):\n",
+    "    def __init__(self, capacity):\n",
+    "        self.progress = 0\n",
+    "        self.capacity = capacity\n",
+    "        self.html_width = '60ex'\n",
+    "        self.text_width = 60\n",
+    "        self._display_id = hexlify(os.urandom(8)).decode('ascii')\n",
+    "        \n",
+    "    def __repr__(self):\n",
+    "        fraction = self.progress / self.capacity\n",
+    "        filled = '=' * int(fraction * self.text_width)\n",
+    "        rest = ' ' * (self.text_width - len(filled))\n",
+    "        return '[{}{}] {}/{}'.format(\n",
+    "            filled, rest,\n",
+    "            self.progress, self.capacity,\n",
+    "        )\n",
+    "    \n",
+    "    def _repr_html_(self):\n",
+    "        return \"\"\"<progress\n",
+    "            value={progress}\n",
+    "            max={capacity}\n",
+    "            style=\"width: {width}\"/>\n",
+    "            {progress} / {capacity}\n",
+    "        \"\"\".format(\n",
+    "            progress=self.progress,\n",
+    "            capacity=self.capacity,\n",
+    "            width=self.html_width,\n",
+    "        )\n",
+    "    \n",
+    "    def display(self):\n",
+    "        display(self, display_id=self._display_id)\n",
+    "    \n",
+    "    def update(self):\n",
+    "        update_display(self, display_id=self._display_id)\n",
+    "\n",
+    "bar = ProgressBar(10)\n",
+    "bar.display()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "And the ProgressBar has `.display` and `.update` methods:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 36,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "<progress\n",
+       "            value=10\n",
+       "            max=10\n",
+       "            style=\"width: 60ex\"/>\n",
+       "            10 / 10\n",
+       "        "
+      ],
+      "text/plain": [
+       "[============================================================] 10/10"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "import time\n",
+    "\n",
+    "bar.display()\n",
+    "\n",
+    "for i in range(11):\n",
+    "    bar.progress = i\n",
+    "    bar.update()\n",
+    "    time.sleep(0.25)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We would encourage any updatable-display objects that track their own display_ids to follow-suit with `.display()` and `.update()` or `.update_display()` methods."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.5.1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 1
+}

IPython/core/display.py

@@ -11,6 +11,7 b' try:'
 except ImportError:
     from base64 import encodestring as base64_encode
 
+from binascii import b2a_hex
 import json
 import mimetypes
 import os
@@ -27,7 +28,7 b" __all__ = ['display', 'display_pretty', 'display_html', 'display_markdown',"
 'display_javascript', 'display_pdf', 'DisplayObject', 'TextDisplayObject',
 'Pretty', 'HTML', 'Markdown', 'Math', 'Latex', 'SVG', 'JSON', 'Javascript',
 'Image', 'clear_output', 'set_matplotlib_formats', 'set_matplotlib_close',
-'publish_display_data']
+'publish_display_data', 'update_display', 'DisplayHandle']
 
 #-----------------------------------------------------------------------------
 # utility functions
@@ -79,7 +80,8 b' def _display_mimetype(mimetype, objs, raw=False, metadata=None):'
 # Main functions
 #-----------------------------------------------------------------------------
 
-def publish_display_data(data, metadata=None, source=None):
+# use * to indicate transient is keyword-only
+def publish_display_data(data, metadata=None, source=None, *, transient=None, **kwargs):
     """Publish data and metadata to all frontends.
 
     See the ``display_data`` message in the messaging documentation for
@@ -114,14 +116,32 b' def publish_display_data(data, metadata=None, source=None):'
         to specify metadata about particular representations.
     source : str, deprecated
         Unused.
+    transient : dict, keyword-only
+        A dictionary of transient data, such as display_id.
         """
     from IPython.core.interactiveshell import InteractiveShell
-    InteractiveShell.instance().display_pub.publish(
+
+    display_pub = InteractiveShell.instance().display_pub
+
+    # only pass transient if supplied,
+    # to avoid errors with older ipykernel.
+    # TODO: We could check for ipykernel version and provide a detailed upgrade message.
+    if transient:
+        kwargs['transient'] = transient
+
+    display_pub.publish(
         data=data,
         metadata=metadata,
+        **kwargs
     )
 
-def display(*objs, **kwargs):
+
+def _new_id():
+    """Generate a new random text id with urandom"""
+    return b2a_hex(os.urandom(16)).decode('ascii')
+
+
+def display(*objs, include=None, exclude=None, metadata=None, transient=None, display_id=None, **kwargs):
     """Display a Python object in all frontends.
 
     By default all representations will be computed and sent to the frontends.
@@ -146,11 +166,34 b' def display(*objs, **kwargs):'
         A dictionary of metadata to associate with the output.
         mime-type keys in this dictionary will be associated with the individual
         representation formats, if they exist.
+    transient : dict, optional
+        A dictionary of transient data to associate with the output.
+        Data in this dict should not be persisted to files (e.g. notebooks).
+    display_id : str, optional
+        Set an id for the display.
+        This id can be used for updating this display area later via update_display.
+        If given as True, generate a new display_id
+    kwargs: additional keyword-args, optional
+        Additional keyword-arguments are passed through to the display publisher.
+    
+    Returns
+    -------
+    
+    handle: DisplayHandle
+        Returns a handle on updatable displays, if display_id is given.
+        Returns None if no display_id is given (default).
     """
-    raw = kwargs.get('raw', False)
-    include = kwargs.get('include')
-    exclude = kwargs.get('exclude')
-    metadata = kwargs.get('metadata')
+    raw = kwargs.pop('raw', False)
+    if transient is None:
+        transient = {}
+    if display_id:
+        if display_id == True:
+            display_id = _new_id()
+        transient['display_id'] = display_id
+    if kwargs.get('update') and 'display_id' not in transient:
+        raise TypeError('display_id required for update_display')
+    if transient:
+        kwargs['transient'] = transient
 
     from IPython.core.interactiveshell import InteractiveShell
 
@@ -159,7 +202,7 b' def display(*objs, **kwargs):'
 
     for obj in objs:
         if raw:
-            publish_display_data(data=obj, metadata=metadata)
+            publish_display_data(data=obj, metadata=metadata, **kwargs)
         else:
             format_dict, md_dict = format(obj, include=include, exclude=exclude)
             if not format_dict:
@@ -168,7 +211,69 b' def display(*objs, **kwargs):'
             if metadata:
                 # kwarg-specified metadata gets precedence
                 _merge(md_dict, metadata)
-            publish_display_data(data=format_dict, metadata=md_dict)
+            publish_display_data(data=format_dict, metadata=md_dict, **kwargs)
+    if display_id:
+        return DisplayHandle(display_id)
+
+
+# use * for keyword-only display_id arg
+def update_display(obj, *, display_id, **kwargs):
+    """Update an existing display by id
+
+    Parameters
+    ----------
+
+    obj:
+        The object with which to update the display
+    display_id: keyword-only
+        The id of the display to update
+    """
+    kwargs['update'] = True
+    display(obj, display_id=display_id, **kwargs)
+
+
+class DisplayHandle(object):
+    """A handle on an updatable display
+
+    Call .update(obj) to display a new object.
+
+    Call .display(obj) to add a new instance of this display,
+    and update existing instances.
+    """
+
+    def __init__(self, display_id=None):
+        if display_id is None:
+            display_id = _new_id()
+        self.display_id = display_id
+
+    def __repr__(self):
+        return "<%s display_id=%s>" % (self.__class__.__name__, self.display_id)
+
+    def display(self, obj, **kwargs):
+        """Make a new display with my id, updating existing instances.
+        
+        Parameters
+        ----------
+        
+        obj:
+            object to display
+        **kwargs:
+            additional keyword arguments passed to display
+        """
+        display(obj, display_id=self.display_id, **kwargs)
+
+    def update(self, obj, **kwargs):
+        """Update existing displays with my id
+        
+        Parameters
+        ----------
+        
+        obj:
+            object to display
+        **kwargs:
+            additional keyword arguments passed to update_display
+        """
+        update_display(obj, display_id=self.display_id, **kwargs)
 
 
 def display_pretty(*objs, **kwargs):

IPython/core/displaypub.py

@@ -53,7 +53,8 b' class DisplayPublisher(Configurable):'
             if not isinstance(metadata, dict):
                 raise TypeError('metadata must be a dict, got: %r' % data)
 
-    def publish(self, data, metadata=None, source=None):
+    # use * to indicate transient, update are keyword-only
+    def publish(self, data, metadata=None, source=None, *, transient=None, update=False, **kwargs):
         """Publish data and metadata to all frontends.
 
         See the ``display_data`` message in the messaging documentation for
@@ -89,6 +90,13 b' class DisplayPublisher(Configurable):'
             the data itself.
         source : str, deprecated
             Unused.
+        transient: dict, keyword-only
+            A dictionary for transient data.
+            Data in this dictionary should not be persisted as part of saving this output.
+            Examples include 'display_id'.
+        update: bool, keyword-only, default: False
+            If True, only update existing outputs with the same display_id,
+            rather than creating a new output.
         """
 
         # The default is to simply write the plain text data using sys.stdout.

IPython/core/tests/test_display.py

@@ -5,6 +5,8 b' import json'
 import os
 import warnings
 
+from unittest import mock
+
 import nose.tools as nt
 
 from IPython.core import display
@@ -189,3 +191,114 b' def test_video_embedding():'
         html = v._repr_html_()
         nt.assert_in('src="data:video/xyz;base64,YWJj"',html)
 
+
+def test_display_id():
+    ip = get_ipython()
+    with mock.patch.object(ip.display_pub, 'publish') as pub:
+        handle = display.display('x')
+        nt.assert_is(handle, None)
+        handle = display.display('y', display_id='secret')
+        nt.assert_is_instance(handle, display.DisplayHandle)
+        handle2 = display.display('z', display_id=True)
+        nt.assert_is_instance(handle2, display.DisplayHandle)
+    nt.assert_not_equal(handle.display_id, handle2.display_id)
+
+    nt.assert_equal(pub.call_count, 3)
+    args, kwargs = pub.call_args_list[0]
+    nt.assert_equal(args, ())
+    nt.assert_equal(kwargs, {
+        'data': {
+            'text/plain': repr('x')
+        },
+        'metadata': {},
+    })
+    args, kwargs = pub.call_args_list[1]
+    nt.assert_equal(args, ())
+    nt.assert_equal(kwargs, {
+        'data': {
+            'text/plain': repr('y')
+        },
+        'metadata': {},
+        'transient': {
+            'display_id': handle.display_id,
+        },
+    })
+    args, kwargs = pub.call_args_list[2]
+    nt.assert_equal(args, ())
+    nt.assert_equal(kwargs, {
+        'data': {
+            'text/plain': repr('z')
+        },
+        'metadata': {},
+        'transient': {
+            'display_id': handle2.display_id,
+        },
+    })
+
+
+def test_update_display():
+    ip = get_ipython()
+    with mock.patch.object(ip.display_pub, 'publish') as pub:
+        with nt.assert_raises(TypeError):
+            display.update_display('x')
+        display.update_display('x', display_id='1')
+        display.update_display('y', display_id='2')
+    args, kwargs = pub.call_args_list[0]
+    nt.assert_equal(args, ())
+    nt.assert_equal(kwargs, {
+        'data': {
+            'text/plain': repr('x')
+        },
+        'metadata': {},
+        'transient': {
+            'display_id': '1',
+        },
+        'update': True,
+    })
+    args, kwargs = pub.call_args_list[1]
+    nt.assert_equal(args, ())
+    nt.assert_equal(kwargs, {
+        'data': {
+            'text/plain': repr('y')
+        },
+        'metadata': {},
+        'transient': {
+            'display_id': '2',
+        },
+        'update': True,
+    })
+
+
+def test_display_handle():
+    ip = get_ipython()
+    handle = display.DisplayHandle()
+    nt.assert_is_instance(handle.display_id, str)
+    handle = display.DisplayHandle('my-id')
+    nt.assert_equal(handle.display_id, 'my-id')
+    with mock.patch.object(ip.display_pub, 'publish') as pub:
+        handle.display('x')
+        handle.update('y')
+
+    args, kwargs = pub.call_args_list[0]
+    nt.assert_equal(args, ())
+    nt.assert_equal(kwargs, {
+        'data': {
+            'text/plain': repr('x')
+        },
+        'metadata': {},
+        'transient': {
+            'display_id': handle.display_id,
+        }
+    })
+    args, kwargs = pub.call_args_list[1]
+    nt.assert_equal(args, ())
+    nt.assert_equal(kwargs, {
+        'data': {
+            'text/plain': repr('y')
+        },
+        'metadata': {},
+        'transient': {
+            'display_id': handle.display_id,
+        },
+        'update': True,
+    })