Jupyter Blog - David Brochart

Plug your application into the Jupyter world

2023-10-23T06:09:00+00:00

Kernels are a simple but powerful abstraction in the Jupyter architecture. They encapsulate language interpreters and make them accessible through a standardized interface. This is the key to Jupyter’s remarkable versatility, with over 100 supported languages. Embedding a kernel in your custom application can seamlessly expose it to the Jupyter ecosystem. Not only can you attach JupyterLab to your program for e.g. state inspection, as you would do with a debugger, but you can truly extend your application with all the power of the Jupyter ecosystem.

Applications: GUI and API

Several applications such as FreeCAD, Blender, or QGIS provide a Python API to access their functionalities programmatically, and include an embedded Python console which allows using this API from within the application. Users can both use the graphical user interface and operate on the application in a scripted fashion depending on their needs.

Python consoles in FreeCAD, Blender, and QGIS (from left to right).

If you think about it, these are the kinds of workflows that Jupyter has always been about, but Jupyter has evolved in the opposite direction. Instead of adding scripting to GUIs, Jupyter added GUIs to scripting. At first, Jupyter was IPython, a console for interactive computing. Then it went to the Web and became IPython Notebook, renamed to Jupyter Notebook. With the browser it became possible to display richer content and create small GUIs, using Jupyter Widgets. Then JupyterLab was created and allowed to create fully-fledged desktop-like applications in the browser, like 3-D CAD modelers.

JupyterLab showing notebooks using JupyterCAD and ipyleaflet.

Jupyter put a lot of attention on building a good experience interacting with the Python REPL, which is not the main focus of domain-specific desktop applications. The Python console embedded in desktop applications is often quite raw. Allowing users to connect from Jupyter can enable a much better experience.

What if there was a bridge that allowed you to connect both worlds, your application on one side and Jupyter on the other side? What is the common denominator allowing code to interact with an application, while also being shared with Jupyter? In the Jupyter infrastructure, we call it a kernel.

Jupyter kernels

Kernels provide a standardized way to expose language interpreters to applications, in a language-agnostic fashion. You can think of it as a server that accepts requests such as “execute this piece of code” and that replies with a result. The result is actually a data representation, it can be as simple as “3” for an input of “1+2”, or a complex interactive plot. A kernel usually lives in a separate process on your machine, but it can also run in the same process, or even remotely on another machine. Someone wanting to connect to this kernel will need the connection information such as the IP address and the ports of the different communication “channels”. It is stored in what is called a connection file.

The Jupyter kernel protocol allows clients to interact with different languages.

Anyone who has access to this connection file can then execute code in the kernel. This is “shared code”, meaning that every client to this kernel eventually runs code in the same interpreter. If one client sets a variable “a=1”, other clients will see this variable. They are all running the “same program”. If the kernel runs in the same process as the application, then the kernel can interact directly with it. This way of sharing the execution engine serves as a bridge between the application and Jupyter.

Now it is just a matter of exposing the connection file so that e.g. JupyterLab can see it. The application launching the kernel can save the connection file to a specific directory, and give the path to JupyterLab. And that’s it, JupyterLab can run a notebook using this kernel, allowing it to interact with the application.

Getting started

The xeus-qt-python repository is a great place to start and see how to embed a Python kernel inside a Qt application. Under the hood, it uses xeus-qt, an integration of the xeus kernel architecture in the Qt event loop. The Qt application actually runs JupyterLab in a Qt WebEngine window. Users can run code in a notebook and interact with the application, which in turn can interact with the notebook. Here, we create a Qt button from a notebook. When clicking on the button, a callback prints a message in the notebook. This demonstrates a two-way binding between the Qt application and JupyterLab.

Example of a Qt application embedding JupyterLab.

SlicerJupyter from Kitware was one of the first applications to take advantage of this approach. You can read more in this blog post. We hope that this technology will unlock a new brand of use-cases and allow applications to reach a new audience through the Jupyter ecosystem. Please reach out to us if you need help!

About the author

David Brochart is a technical director at QuantStack. He mostly works on the Jupyter backend stack. He contributed to the development of real-time collaboration in JupyterLab, and created the Jupyverse project, a next-generation implementation of the Jupyter server.

Acknowledgments

This work was made possible thanks to several contributors. Mariana Meireles was the initial author of xeus-qt. Thorsten Beier is a scientific software developer at QuantStack and contributes to the xeus kernel ecosystem. He is the initial creator of the xeus-qt-python demonstration. Johan Mabille is a technical director at QuantStack and he is the main author of xeus. Afshin Darian is a technical director at QuantStack and worked on the UI in JupyterLab 4.0 allowing to use an external kernel.

Accelerating JupyterLab

2022-10-10T17:38:00+00:00

The next major release of JupyterLab will be significantly faster than previous versions. This was achieved both through systematic tracking of performance bugs and through significant upgrades to the Jupyter communication protocol and rendering mechanism for documents.

1. Setting up rigorous performance measurements

The first step to any measurable improvement in performance is to set up systematic measurement of performance.

The JupyterLab project now includes a UI performance benchmarking tool, in the form of a GitHub action that can be triggered on any pull request to check how performance is impacted by the change. The implementation of this new GitHub action is available in this repository: https://github.com/jupyterlab/benchmarks.

This tool measures the time required for performing the following actions: opening a test notebook, switching from the test notebook to a copy of it opened in another tab, switching from the test notebook to a text editor, switching back, searching for a word in the test notebook and closing the test notebook. There are multiple example notebooks in the test suites. Benchmark results are posted as comments on the pull request. You can see such a benchmark report here: #11494#issuecomment-976393815

Example report from the new benchmarking tool — each execution time distribution is represented by a box-plot graph (the box spans from the 1st to the 3rd quartiles with the white line positioned at the median value).

The addition of this benchmarking tool immediately allowed for optimization on how notebooks are hidden when switching tabs. Hiding can be done by adding a CSS class that enables some CSS rule, or forcibly setting display to “none”. Depending on the browser, picking one way or another of hiding content may trigger a reflow of the entire page, so we made this a settable with an option in the JupyterLab config.

The benchmark GitHub action was developed by Frédéric Collonval.

2. Upgrading to CodeMirror 6

The rendering of the text editor used in notebooks can be very expensive, especially in the case of large notebooks with many cells. Jupyter has historically relied on CodeMirror as its based text editor.

JupyterLab 4 includes an upgrade from CodeMirror 5 to CodeMirror 6, which is a complete rewrite of the text editor. This work can be found in pull requests #11638, #12877, and #12861 — modifying over 150 files of the JupyterLab codebase. Benchmarks indicate a rendering speedup factor between 2 and 3 on the large notebooks used in the benchmarking suite.

Benchmark report on the CodeMirror 6 migration PR

Note: CodeMirror 6 is also an important stepping stone towards making Jupyter notebooks accessible to people who need screen readers and other devices.

The migration of JupyterLab to CodeMirror 6 was performed by Johan Mabille.

3. Virtual rendering of notebooks

In JupyterLab 4, the notebook will only render the parts of the documents that are visible in the viewport. It significantly improves the rendering speed of large notebooks. The main pull request implementing this feature is available here: #12554.

Significant preparation work was required for this Pull Request, especially regarding the “search feature” and the “table of content” components that both made use of the notebook view instead of the document model. This was done in PRs #11689 and #12374 respectively.

The end results showed significant improvement in the rendering speed of large notebook files, with a speedup of 3 to 4, which come on top of the already improved performance from the CodeMirror 6 migration.

Benchmark report on the Virtual Rendering of notebooks

The virtual rendering of notebooks was developed by Frédéric Collonval.

4. Jupyter protocol alignment

The Jupyter server serves as a relay between the frontends such as JupyterLab or the notebook and kernels. The server ⇄ kernel communication is done over ZeroMQ sockets, with the well-specified Jupyter kernel protocol. The server ⇄ client communication is done over WebSockets.

Unfortunately, up until recently, the server ⇄ kernel (ZMQ), and the server ⇄ client (WebSocket) protocols differed slightly so that the server had to parse each message and re-serialise it in both directions. This processing cost is small for short messages such as execution requests and replies which are typically very short, however, it can become very costly when dealing with larger datasets being sent or retrieved from the front-end, such as large tables, complex mime type rendering. This misalignment of the ZMQ and WebSocket protocol can then become a real bottleneck.

In Jupyter Server 2, the WebSocket connection supports a new “aligned” protocol, in which messages can simply be copied over to and from ZeroMQ messages, which is supported by JupyterLab 4. (This work was done in PRs #657 (jupyter-server), #154 (jupyverse), and #11841 (JupyterLab)). This new aligned protocol is an opt-in, so that legacy Jupyter front-end are still expected to function with Jupyter Server 2.

Benchmarks indicate a large speedup factor (at least one order of magnitude, and more for larger messages) in the performance of the Jupyter server when displaying large data sets in Jupyter widgets. However, this is not captured by the JupyterLab benchmark tests which focus on the rendering performances.

The procol alignment work was done by David Brochart.

5. Lumino 2

The JupyterLab frontend is built upon the Lumino framework, which provides utilities for building in-browser desktop-like applications. It provides the foundations for such applications, including a uniform component wrapper that handles lifecycle management and efficient propagation of front-end events to an entire application, (e.g., resize events, drag-and-drop, layout calculation). Lumino also provides several high-performance components such as a drag-and-drop dock panel (used as the application shell for JupyterLab) and a best-in-class data grid component.

JupyterLab 4 includes a major upgrade of the Lumino. The main changes in Lumino 2 include the migration to ES2018, which allowed for the removal of large parts of the codebase prodiving features that are now natively available in JavaScript, such as native iterators, removing polyfills for promises, and special-case logic for idiosyncrasies of legacy browsers like IE. This upgrade is also leading to across-the-board performance improvements in the front-end, although not for the rendering of large documents. Lumino 2 supports background processing of UI components when the application resides in a background browser tab (a feature that may be back-ported to Lumino 1.x as well).

The Lumino 2 upgrade and integration in JupyterLab was done by Afshin Darian.

6. A faster Lumino data grid

Optimizations to the Lumino data grid widget were also implemented, speeding up the rendering in the case of merged cells (cf. PR #394). The Lumino datagrid is used in various parts of the JupyterLab UI, such as the table view for CSV files. It is also used extensively in third-party extensions such as the ipydatagrid Jupyter widget and the BeakerX table display.

The Lumino data grid optimization was done by Martin Renou.

Acknowledgement

The work by the QuantStack team on JupyterLab performance improvements was done in collaboration with Two Sigma. Several of these pull requests required major changes across the JupyterLab codebase. We are very grateful to Two Sigma for supporting the development of the Jupyter project at such a deep level.

We are grateful to Juliette Taka for the illustrations.

About the authors

Frédéric Collonval, who led the charge on JupyterLab performance improvements, is a technical director at QuantStack. He is a member of the core JupyterLab core team and authored several JupyterLab extensions.

Johan Mabille is a technical director at QuantStack, very active in the Jupyter ecosystem. He regularly contributes to JupyterLab, and developed the Xeus framework for creating Jupyter kernels.

David Brochart is a scientific software developer at QuantStack, very active in the Jupyter ecosystem. He is a maintainer of the Jupyter-server project, and the main author of Jupyverse. David also contributes to the geo-science open-source stack built atop Jupyter.

Afshin Darian is a technical director at QuantStack. He is the co-creator of the JupyterLab project and continues working on the project to this day.

nbterm: Jupyter Notebooks in the terminal

2021-04-26T16:42:00+00:00

Jupyter notebooks are mostly known for their web-based user interface, such as JupyterLab or the Classic Notebook. They offer a great user experience, allow for rich output rendering, provide interactivity through e.g. widgets, and make possible working with remote kernels.

If just like me you tend to never leave the terminal in your workflow, you may be missing a tool to interact with Jupyter notebooks without switching to a web browser. While the Jupyter Console already allows you to interact with a Jupyter kernel in the terminal, it is more comparable to a shell than a notebook.

The notebook differs from the console in that it’s bound to a document, interleaving rich text and executable code. This makes the code representation more structured, while allowing for interactivity. Well, until recently this wasn’t possible in the terminal. But today, we are proud to announce nbterm!

Side-by-side comparison of the JupyterLab web notebook and nbterm.

Getting started with nbterm

Launching a notebook is as easy as entering:

$ nbterm my_notebook.ipynb

You can also create a new one if you don’t pass a notebook argument. Almost immediately, you will get a full-screen application that looks like this:

nbterm has other command line options:

$ nbterm --help
Usage: nbterm [OPTIONS] [NOTEBOOK_PATH]

Arguments:
  [NOTEBOOK_PATH]  Path to the notebook.  [default: ]

Options:
  --no-kernel                     Don't launch a kernel.
  --run                           Run the notebook.
  --save-path TEXT                Path to save the notebook.
  --version                       Show the version and exit.
  --help                          Show this message and exit.

For example, it is possible to run all cells of a notebook in batch mode, using:

$ nbterm --run my_notebook.ipynb

If you didn’t specify a new name with --save-path, a new notebook named my_notebook_run.ipynb will be created, with all cell outputs populated. This mode of execution is similar to the nbclient library, but accessible in the command line.

Embedding nbterm

It is also possible to use it as a library and embed it in your own application. Besides, all user interactions can be scripted. For instance, you can rearrange the cells and then run all cells like this:

import asyncio
from nbterm import Notebook

nb = Notebook("my_notebook.ipynb")
nb.cut_cell(3)
nb.paste_cell(1)
asyncio.run(nb.run_all())
nb.save()

A lightweight Jupyter stack

While you probably can’t tell the difference, nbterm doesn’t reuse the base Jupyter components such as jupyter-client and nbformat (respectively implementing the Jupyter kernel protocol and the Jupyter Notebook format). The reason is that nbterm was started as a toy project to see how hard it would be to have a minimalist notebook client.

As a Jupyter contributor, I am mostly involved in the maintenance and modernization of these packages. I wanted to experiment with a new project without the backward-compatibility constraints. This resulted in a rather lean code base, and its simplicity makes it suitable to serve as a reference for other language implementations.

The roadmap

While nbterm is obviously more limited than the Notebook, there are several potential improvement directions. Having rich(er) outputs is one of them. The terminal is pretty much limited to showing characters, but people have done great things with ASCII art. An attempt has been made a while ago with an ASCII back-end for matplotlib. And although it’s only on macOS for now, some terminals are capable of showing real pictures, and there exists a Matplotlib back-end for iTerm2.

Another nice feature would be to add some interactivity. In the Notebook, this is typically achieved using widgets, but they are inherently web-based, so this is not an option. Maybe we could imagine something similar to ipywidgets for the terminal, and have simple things like sliders, buttons, menus and such. I am keeping an eye on the awesome Rich library, with which you can already create dashboards, and GUI applications in the future.

Try it!

nbterm really has the look and feel of the Notebook you already know and love, with (almost) the same key bindings, so you won’t be lost. As coders, we love the terminal, and libraries like prompt-toolkit and Rich in Python, or cpp-terminal in C++, make it possible to build beautiful applications. You can install nbterm today using your favorite package manager:

$ pip install nbterm

or:

$ mamba install nbterm -c conda-forge

Be sure to update frequently, as it is improving every day. And if you want to contribute, please get in touch on the GitHub repository.

Acknowledgements

The development of nbterm is sponsored by QuantStack.

About the author

David Brochart is a scientific software developer at QuantStack. He is a contributor to several libraries in the Jupyter ecosystem, such as nbclient, jupyter-client, jupyter-server, ipykernel, and ipywidgets.