docs/source/examples/Output Widget.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "source": [
    "[Index](Index.ipynb) - [Back](Widget List.ipynb) - [Next](Widget Events.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Output widgets: leveraging Jupyter's display system"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ipywidgets as widgets"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "The `Output` widget can capture and display stdout, stderr and [rich output generated by IPython](http://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#module-IPython.display). You can also append output directly to an output widget, or clear it programmatically."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "out = widgets.Output(layout={'border': '1px solid black'})\n",
    "out"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After the widget is created, direct output to it using a context manager. You can print text to the output area:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "with out:\n",
    "    for i in range(10):\n",
    "        print(i, 'Hello world!')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rich output can also be directed to the output area. Anything which displays nicely in a Jupyter notebook will also display well in the `Output` widget."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import YouTubeVideo\n",
    "with out:\n",
    "    display(YouTubeVideo('eWzY2nGfkXk'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can even display complex mimetypes, such as nested widgets, in an output widget."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "with out:\n",
    "    display(widgets.IntSlider())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also append outputs to the output widget directly with the convenience methods `append_stdout`, `append_stderr`, or `append_display_data`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "out = widgets.Output(layout={'border': '1px solid black'})\n",
    "out.append_stdout('Output appended with append_stdout')\n",
    "out.append_display_data(YouTubeVideo('eWzY2nGfkXk'))\n",
    "out"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that `append_display_data` cannot currently be used to display widgets. The status of this bug is tracked in [this issue](https://github.com/jupyter-widgets/ipywidgets/issues/1811)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can clear the output by either using `IPython.display.clear_output` within the context manager, or we can call the widget's `clear_output` method directly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "out.clear_output()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`clear_output` supports the keyword argument `wait`. With this set to `True`, the widget contents are not cleared immediately. Instead, they are cleared the next time the widget receives something to display. This can be useful when replacing content in the output widget: it allows for smoother transitions by avoiding a jarring resize of the widget following the call to `clear_output`.\n",
    "\n",
    "Finally, we can use an output widget to capture all the output produced by a function using the `capture` decorator."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@out.capture()\n",
    "def function_with_captured_output():\n",
    "    print('This goes into the output widget')\n",
    "    raise Exception('As does this')\n",
    "    \n",
    "function_with_captured_output()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`out.capture` supports the keyword argument `clear_output`. Setting this to `True` will clear the output widget every time the function is invoked, so that you only see the output of the last invocation. With `clear_output` set to `True`, you can also pass a `wait=True` argument to only clear the output once new output is available. Of course, you can also manually clear the output any time as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "out.clear_output()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Output widgets as the foundation for interact\n",
    "\n",
    "The output widget forms the basis of how interact and related methods are implemented. It can also be used by itself to create rich layouts with widgets and code output. One simple way to customize how an interact UI looks is to use the `interactive_output` function to hook controls up to a function whose output is captured in the returned output widget. In the next example, we stack the controls vertically and then put the output of the function to the right."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = widgets.IntSlider(description='a')\n",
    "b = widgets.IntSlider(description='b')\n",
    "c = widgets.IntSlider(description='c')\n",
    "def f(a, b, c):\n",
    "    print('{}*{}*{}={}'.format(a, b, c, a*b*c))\n",
    "\n",
    "out = widgets.interactive_output(f, {'a': a, 'b': b, 'c': c})\n",
    "\n",
    "widgets.HBox([widgets.VBox([a, b, c]), out])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Debugging errors in callbacks with the output widget\n",
    "\n",
    "On some platforms, like JupyterLab, output generated by widget callbacks (for instance, functions attached to the `.observe` method on widget traits, or to the `.on_click` method on button widgets) are not displayed anywhere. Even on other platforms, it is unclear what cell this output should appear in. This can make debugging errors in callback functions more challenging. \n",
    "\n",
    "An effective tool for accessing the output of widget callbacks is to decorate the callback with an output widget's capture method. You can then display the widget in a new cell to see the callback output."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "debug_view = widgets.Output(layout={'border': '1px solid black'})\n",
    "\n",
    "@debug_view.capture(clear_output=True)\n",
    "def bad_callback(event):\n",
    "    print('This is about to explode')\n",
    "    return 1.0 / 0.0\n",
    "\n",
    "button = widgets.Button(\n",
    "    description='click me to raise an exception',\n",
    "    layout={'width': '300px'}\n",
    ")\n",
    "button.on_click(bad_callback)\n",
    "button"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "debug_view"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Integrating output widgets with the logging module\n",
    "\n",
    "While using the `.capture` decorator works well for understanding and debugging single callbacks, it does not scale to larger applications. Typically, in larger applications, one might use the [logging](https://docs.python.org/3/library/logging.html) module to print information on the status of the program. However, in the case of widget applications, it is unclear where the logging output should go.\n",
    "\n",
    "A useful pattern is to create a custom [handler](https://docs.python.org/3/library/logging.html#handler-objects) that redirects logs to an output widget. The output widget can then be displayed in a new cell to monitor the application while it runs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ipywidgets as widgets\n",
    "import logging\n",
    "\n",
    "class OutputWidgetHandler(logging.Handler):\n",
    "    \"\"\" Custom logging handler sending logs to an output widget \"\"\"\n",
    "\n",
    "    def __init__(self, *args, **kwargs):\n",
    "        super(OutputWidgetHandler, self).__init__(*args, **kwargs)\n",
    "        layout = {\n",
    "            'width': '100%', \n",
    "            'height': '160px', \n",
    "            'border': '1px solid black'\n",
    "        }\n",
    "        self.out = widgets.Output(layout=layout)\n",
    "\n",
    "    def emit(self, record):\n",
    "        \"\"\" Overload of logging.Handler method \"\"\"\n",
    "        formatted_record = self.format(record)\n",
    "        new_output = {\n",
    "            'name': 'stdout', \n",
    "            'output_type': 'stream', \n",
    "            'text': formatted_record+'\\n'\n",
    "        }\n",
    "        self.out.outputs = (new_output, ) + self.out.outputs\n",
    "        \n",
    "    def show_logs(self):\n",
    "        \"\"\" Show the logs \"\"\"\n",
    "        display(self.out)\n",
    "    \n",
    "    def clear_logs(self):\n",
    "        \"\"\" Clear the current logs \"\"\"\n",
    "        self.out.clear_output()\n",
    "\n",
    "\n",
    "logger = logging.getLogger(__name__)\n",
    "handler = OutputWidgetHandler()\n",
    "handler.setFormatter(logging.Formatter('%(asctime)s  - [%(levelname)s] %(message)s'))\n",
    "logger.addHandler(handler)\n",
    "logger.setLevel(logging.INFO)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "handler.show_logs()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "handler.clear_logs()\n",
    "logger.info('Starting program')\n",
    "\n",
    "try:\n",
    "    logger.info('About to try something dangerous...')\n",
    "    1.0/0.0\n",
    "except Exception as e:\n",
    "    logger.exception('An error occurred!')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Interacting with output widgets from background threads\n",
    "\n",
    "Jupyter's `display` mechanism can be counter-intuitive when displaying output produced by background threads. A background thread's output is printed to whatever cell the main thread is currently writing to. To see this directly, create a thread that repeatedly prints to standard out:\n",
    "\n",
    "```python\n",
    "import threading\n",
    "import time\n",
    "\n",
    "def run():\n",
    "    for i in itertools.count(0):\n",
    "        time.sleep(1)\n",
    "        print('output from background {}'.format(i))\n",
    "        \n",
    "t = threading.Thread(target=run)\n",
    "t.start()\n",
    "```\n",
    "\n",
    "This always prints in the currently active cell, not the cell that started the background thread.\n",
    "\n",
    "This can lead to surprising behaviour in output widgets. During the time in which output is captured by the output widget, *any* output generated in the notebook, regardless of thread, will go into the output widget.\n",
    "\n",
    "The best way to avoid surprises is to *never* use an output widget's context manager in a context where multiple threads generate output. Instead, we can pass an output widget to the function executing in a thread, and use `append_display_data()`, `append_stdout()`, or `append_stderr()` methods to append displayable output to the output widget."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import threading\n",
    "from IPython.display import display, HTML\n",
    "import ipywidgets as widgets\n",
    "import time\n",
    "\n",
    "def thread_func(something, out):\n",
    "    for i in range(1, 5):\n",
    "        time.sleep(0.3)\n",
    "        out.append_stdout('{} {} {}\\n'.format(i, '**'*i, something))\n",
    "    out.append_display_data(HTML(\"<em>All done!</em>\"))\n",
    "\n",
    "display('Display in main thread')\n",
    "out = widgets.Output()\n",
    "# Now the key: the container is displayed (while empty) in the main thread\n",
    "display(out)\n",
    "\n",
    "thread = threading.Thread(\n",
    "    target=thread_func,\n",
    "    args=(\"some text\", out))\n",
    "thread.start()"
   ]
  }
 ],
 "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.6.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}