And Voilà!
… from Jupyter notebooks to standalone applications and dashboards
The goal of Project Jupyter is to improve the workflows of researchers, educators, scientists, and other practitioners of scientific computing, from the exploratory phase of their work to the communication of the results.
But interactive notebooks are not the best communication tool for all audiences. While they have proven invaluable to provide a narrative alongside the source, they are not ideal to address non-technical readers, who may be put off by the presence of code cells, or the need to run the notebook to see the results. Finally, following the order as the code often results in the most interesting content to be at the end of the document.
Another challenge with sharing notebooks is the security model. How can we offer the interactivity of a notebook making use of e.g. Jupyter widgets without allowing arbitrary code execution by the end user?
We set ourselves to solve these challenges, and we are happy to announce the first release of Voilà.
Voilà turns Jupyter notebooks into standalone web applications.
- Voilà supports Jupyter interactive widgets, including the roundtrips to the kernel.
- Voilà does not permit arbitrary code execution by consumers of dashboards.
- Built upon Jupyter standard protocols and file formats, Voilà works with any Jupyter kernel (C++, Python, Julia), making it a language-agnostic dashboarding system.
- Voilà is extensible. It includes a flexible template system to produce rich application layouts.
Installation and first-time use
Voilà can be installed from pypi:
pip install voilaor conda-forge:
conda install voila -c conda-forgeUpon installation, several components are installed, one of which is the voila command-line utility. You can try it by typing voila notebook.ipynb. It results in the browser opening to a new tornado application showing markdown cells, rich outputs, and interactive widgets.
As you can see in the screencast, Jupyter interactive widgets remain fully functional even when they require computation by the kernel.
You can immediately try out some of the command-line options to Voilà
- with
--strip_sources=False, input cells will be included in the resulting web application (as read-only pygment snippets). - with
--theme=dark, Voilà will make use of the dark JupyterLab theme, which will apply to code cells, widgets and all other visible components.
Note that code is only shown, voilà does not allow users to edit or execute arbitrary code.
Voilà's execution model
The execution model of Voilà is the following: upon connection to a notebook URL, Voilà launches the kernel for that notebook, and runs all the cells as it populates the notebook model with the outputs.
After the execution, the associated kernel is not shut down. The notebook is converted to HTML and served to the user. The rendered HTML includes JavaScript that establishes a connection to the kernel. Jupyter interactive widgets referred in cell outputs are rendered and connected to their counterpart in the kernel. The kernel is only shut down when the user closes their browser tab.
The current version of Voilà only responds to the initial GET request when all the cells have finished running, which may take a long time, but there is ongoing work on enabling progressive rendering, which should make it into a release soon.
An important aspect of this execution model is that the front-end does not determine what code is run by the backend. In fact, unless specified otherwise (with option --strip-sources=False), the source of the rendered notebook does not even make it to the front-end. The instance of the jupyter_server instantiated by Voilà actually disallows execute requests by default.
Support for custom interactive widgets
Voilà can render custom Jupyter widget libraries, including (but not limited to) bqplot, ipyleafet, ipyvolume, ipympl, ipysheet, plotly, ipywebrtc, etc.
Together with ipympl, Voilà is actually a simple means to render interactive matplotlib figures in a standalone web application:
Voilà is language-agnostic
Voilà can be used to produce applications with any Jupyter kernel. The following screencast shows how Voilà can be used to produce a simple dashboard in C++ making use of leaflet.js maps, with the xeus-cling C++ kernel and the xleaflet package.
We hope that Voilà will be a stimulant to other languages (R, Julia, JVM/Java) to provide stronger widgets support.
Richer layouts with Voilà templates
The main extension point to Voilà is the custom template system. The HTML served to the end-user is produced from the notebook model by applying a Jinja template, which can be defined by the user.
An example template for voilà is the voila-gridstack template, which can be installed from pypi with
pip install voila-gridstackYou can try it by typing voila notebook.ipynb --template=gridstack.
The gridstack Voilà template makes use of the cell metadata to lay out the application.
A roadmap item for the gridstack Voilà template is to support the entire spec for the deprecated jupyter dashboards and to create a WYSIWYG editor for these templates in the form of a JupyterLab extension.
Note that voila-gridstack template is still at an early stage of development.
How to make custom Voilà templates?
A Voilà template is actually a folder placed in the standard directoryPREFIX/share/jupyter/voila/templates and which may include
nbconverttemplates (the jinja templates used to transform the notebook into HTML)staticresources- custom
tornadotemplates such as404.htmletc.
All of these are optional. It may also contain a conf.json file to set up which template to use as a base. The directory structure for a Voilà template is the following:
PREFIX/share/jupyter/voila/templates/template_name/
|
├── conf.json # Template configuration file
├── nbconvert_templates/ # Custom nbconvert templates
├── static/ # Static directory
└── templates/ # Custom tornado templatesThe Voilà template system can be used to completely override the behavior of the front-end. One can make use of modern JavaScript frameworks such as React or Vue.js to produce modern UI including Jupyter widgets and outputs.
Another example template for Voilà is voila-vuetify, which is built upon vue.js:
The voila-gridstack and voila-vuetify templates are still at an early stage of development, but will be iterated upon quickly in the next weeks as we are exploring templates.
A Jupyter server extension
Beyond the voila command-line utility, the Voilà package also include a Jupyter server extension, so that Voilà dashboards can be served alongside the Jupyter notebook application.
When Voilà is installed, a running Jupyter server will serve the Voilà web application under BASE_URL/voila.
The Jupyter Community Workshop on Dashboarding
From June 3rd to June 6th 2019, a community workshop on dashboarding with Project Jupyter took place in Paris. Over thirty Jupyter contributors and community members gathered to discuss dashboarding technologies and hack together.
Several dashboarding solutions such as Dash and Panel were presented during the workshop and featured at the PyData Paris Meetup which was organized on the same week.
The workshop was also the occasion for several contributors to start working on Voilà. Custom templates, a dashboard gallery, logos and UX mockups for JupyterLab extensions have been developed.
We will soon publish a more detailed post on the workshop, detailing the many tracks of development that have been explored!
What is coming?
There is a lot of planned work around Voilà in the next weeks and months. Current work streams include better integration with JupyterHub for publicly sharing dashboard between users, as well as JupyterLab extensions (a Voilà "preview" extension for notebooks, and a WYSIWYG editor for dashboard layouts). There are also ongoing discussions with the OVH cloud provider (which already supports binder by handling some of its traffic) on hosting a binder-like service dedicated to Voilà dashboards. So stay tuned for more exciting developments!
Last but not least, we are especially excited about what you will be building upon Voilà!
Acknowledgments
The development of Voilà and related packages at QuantStack is sponsored by Bloomberg.
We are also grateful to the attendees of the Jupyter Community Workshop on Dashboarding for their numerous contributions to Voilà!
We would like to thank Chris Holdgraf for his work on improving documentation, and integration with JupyterHub.
We should mention Yuvi Panda and Pascal Bugnion for getting the voila-galleryproject off the ground during the workshop. We are grateful to Zach Sailer for his continued work on improvingjupyter_server. We should finally not forget to mention the prior art by Pascal Bugnion with the Jupyter widgets server which was also an inspiration for Voilà.
About the Authors
Sylvain Corlay is the founder and CEO of QuantStack and a core team member for Project Jupyter.
Maarten Breddels is an independent scientific software developer partnering with QuantStack on numerous projects, and a core developer of Project Jupyter.
