Add push_notebook helper function

holoviz · philippjfr · Jun 29, 2021 · Jun 29, 2021 · Jun 29, 2021 · bb691d73634f5b612be4d18a4c654858c1923ff0
commit bb691d73634f5b612be4d18a4c654858c1923ff0
diff --git a/examples/gallery/streaming/streaming_bokeh.ipynb b/examples/gallery/streaming/streaming_bokeh.ipynb
@@ -0,0 +1,63 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import panel as pn\n",
+    "\n",
+    "from bokeh.plotting import figure\n",
+    "from bokeh.models import ColumnDataSource\n",
+    "\n",
+    "pn.extension()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p = figure(sizing_mode='stretch_width', title='Bokeh streaming example')\n",
+    "\n",
+    "xs = np.arange(1000)\n",
+    "ys = np.random.randn(1000).cumsum()\n",
+    "x, y = xs[-1], ys[-1]\n",
+    "\n",
+    "cds = ColumnDataSource(data={'x': xs, 'y': ys})\n",
+    "\n",
+    "p.line('x', 'y', source=cds)\n",
+    "\n",
+    "bk_pane = pn.pane.Bokeh(p)\n",
+    "bk_pane.servable()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def stream():\n",
+    "    global x, y\n",
+    "    x += 1\n",
+    "    y += np.random.randn()\n",
+    "    cds.stream({'x': [x], 'y': [y]})\n",
+    "    pn.io.push_notebook(bk_pane) # Only needed when running in notebook context\n",
+    "    \n",
+    "pn.state.add_periodic_callback(stream, 100)"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}
diff --git a/examples/reference/panes/Bokeh.ipynb b/examples/reference/panes/Bokeh.ipynb
@@ -19,6 +19,8 @@
    "source": [
     "The ``Bokeh`` pane allows displaying any displayable [Bokeh](http://bokeh.org) model inside a Panel app. Since Panel is built on Bokeh internally, the Bokeh model is simply inserted into the plot. Since Bokeh models are ordinarily only displayed once, some Panel-related functionality such as syncing multiple views of the same model may not work. Nonetheless this pane type is very useful for combining raw Bokeh code with the higher-level Panel API.\n",
     "\n",
+    "When working in a notebook any changes to a Bokeh objects may not be synced automatically requiring an explicit call to `pn.state.push_notebook` with the Panel component containing the Bokeh object.\n",
+    "\n",
     "#### Parameters:\n",
     "For the ``theme`` parameter, see the [bokeh themes docs](https://docs.bokeh.org/en/latest/docs/reference/themes.html).\n",
     "\n",
@@ -78,7 +80,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "To update a plot with a live server, we can simply modify the underlying model and then ``trigger`` an update on the pane's object parameter:"
+    "To update a plot with a live server, we can simply modify the underlying model. If we are working in a Jupyter notebook we also have to call the `pn.io.push_notebook` helper function on the component or explicitly trigger an event with `bokeh_pane.param.trigger('object')`:"
    ]
   },
   {
@@ -88,7 +90,7 @@
    "outputs": [],
    "source": [
     "r.data_source.data['color'] = Category20[len(x)]\n",
-    "bokeh_pane.param.trigger('object')"
+    "pn.io.push_notebook(bokeh_pane)"
    ]
   },
   {
@@ -168,7 +170,6 @@
     "for w in [offset, amplitude, phase, freq]:\n",
     "    w.on_change('value', update_data)\n",
     "\n",
-    "\n",
     "# Set up layouts and add to document\n",
     "inputs = column(text, offset, amplitude, phase, freq)\n",
     "\n",

diff --git a/examples/user_guide/Overview.ipynb b/examples/user_guide/Overview.ipynb
@@ -66,6 +66,10 @@
     "\n",
     "> Given a Panel model `pn.ipywidget` will return an ipywidget model that renders the object in the notebook. This can be useful for including an panel widget in an ipywidget layout and deploying Panel objects using [Voilà](https://github.com/voila-dashboards/voila/).\n",
     "\n",
+    "##### ``pn.io.push_notebook``\n",
+    "\n",
+    "> When working with Bokeh models directly in a Jupyter Notebook any changes to the model are not automatically sent to the frontend. Instead we have to explicitly call `pn.io.push_notebook` on the Panel component(s) wrapping the Bokeh component being updated.\n",
+    "\n",
     "##### Rich display\n",
     "\n",
     "Jupyter notebooks allow the final value of a notebook cell to display itself, using a mechanism called [rich display](https://ipython.readthedocs.io/en/stable/config/integrating.html#rich-display). As long as `pn.extension()` has been called in a notebook, all Panel components (widgets, panes, and panels) will display themselves when placed on the last line of a notebook cell.\n",

diff --git a/panel/io/__init__.py b/panel/io/__init__.py
@@ -16,7 +16,7 @@
 from .server import get_server, init_doc, serve, unlocked, with_lock # noqa
 from .notebook import ( # noqa
     block_comm, ipywidget, _jupyter_server_extension_paths,
-    load_notebook, push
+    load_notebook, push, push_notebook
 )
 
 panel_logger = logging.getLogger('panel')

diff --git a/panel/io/notebook.py b/panel/io/notebook.py
@@ -75,6 +75,22 @@ def push_on_root(ref):
     if comm and 'embedded' not in root.tags:
         push(doc, comm)
 
+
+def push_notebook(*objs):
+    """
+    A utility for pushing updates to the frontend given a Panel
+    object.  This is required when modifying any Bokeh object directly
+    in a notebook session.
+
+    Arguments
+    ---------
+    objs: panel.viewable.Viewable
+    """
+    for obj in objs:
+        for ref in obj._models:
+            push_on_root(ref)
+
+
 DOC_NB_JS = _env.get_template("doc_nb_js.js")
 AUTOLOAD_NB_JS = _env.get_template("autoload_panel_js.js")
 NB_TEMPLATE_BASE = _env.get_template('nb_template.html')