Metadata-Version: 2.1
Name: voila
Version: 0.5.7
Summary: Voilà turns Jupyter notebooks into standalone web applications
Project-URL: Homepage, https://github.com/voila-dashboards/voila
Author: Voila Development Team
License: BSD License
        
        Copyright (c) 2018 Voilà contributors.
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
          a. Redistributions of source code must retain the above copyright notice,
             this list of conditions and the following disclaimer.
        
          b. Redistributions in binary form must reproduce the above copyright
             notice, this list of conditions and the following disclaimer in the
             documentation and/or other materials provided with the distribution.
        
          c. Neither the name of the authors nor the names of the contributors to
             this package may be used to endorse or promote products
             derived from this software without specific prior written
             permission.
        
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
        ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
        ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
        LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
        OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
        DAMAGE.
License-File: LICENSE
Keywords: Jupyter,JupyterLab,Voila
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 3
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Requires-Dist: jupyter-client<9,>=7.4.4
Requires-Dist: jupyter-core>=4.11.0
Requires-Dist: jupyter-server<3,>=2.0.0
Requires-Dist: jupyterlab-server<3,>=2.3.0
Requires-Dist: nbclient>=0.4.0
Requires-Dist: nbconvert<8,>=6.4.5
Requires-Dist: traitlets<6,>=5.0.3
Requires-Dist: websockets>=9.0
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: jupyter-releaser; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: pydata-sphinx-theme; extra == 'docs'
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-autobuild; extra == 'docs'
Requires-Dist: sphinxcontrib-video; extra == 'docs'
Provides-Extra: test
Requires-Dist: ipykernel; extra == 'test'
Requires-Dist: ipywidgets; extra == 'test'
Requires-Dist: matplotlib; extra == 'test'
Requires-Dist: mock; extra == 'test'
Requires-Dist: numpy; extra == 'test'
Requires-Dist: pandas; extra == 'test'
Requires-Dist: papermill; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-tornasync; extra == 'test'
Description-Content-Type: text/markdown

# ![voila](docs/voila-logo.svg)

[![Documentation](http://readthedocs.org/projects/voila/badge/?version=latest)](https://voila.readthedocs.io/en/latest/?badge=latest)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/voila-dashboards/voila/stable?urlpath=voila%2Ftree%2Fnotebooks)
[![Discourse](https://img.shields.io/badge/help_forum-discourse-blue.svg)](https://discourse.jupyter.org)
[![Join the Gitter Chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/QuantStack/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

Rendering of live Jupyter notebooks with interactive widgets.

## Introduction

Voilà turns Jupyter notebooks into standalone web applications.

Unlike the usual HTML-converted notebooks, each user connecting to the Voilà
tornado application gets a dedicated Jupyter kernel which can execute the
callbacks to changes in Jupyter interactive widgets.

- By default, Voilà disallows execute requests from the front-end, preventing
  execution of arbitrary code.
- By default, Voilà runs with the `strip_sources` option, which strips out the
  input cells from the rendered notebook.

## Installation

Voilà can be installed with the mamba (or conda) package manager from conda-forge

```
mamba install -c conda-forge voila
```

or from PyPI

```
pip install voila
```

### JupyterLab preview extension

Voilà provides a JupyterLab extension that displays a Voilà preview of your Notebook in a side-pane.

Starting with JupyterLab 3.0, the extension is **automatically installed** after installing `voila`
with `pip install voila`.

If you would like to install the extension from source, run the following command.

```
jupyter labextension install @voila-dashboards/jupyterlab-preview
```

## Usage

### As a standalone tornado application

To render the `bqplot` example notebook as a standalone app, run
`voila bqplot.ipynb`.
To serve a directory of jupyter notebooks, run `voila` with no argument.

For example, to render the example notebook `bqplot.ipynb` from this repository with Voilà, you can first update your current environment with the requirements of this notebook (in this case in a [conda environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) and render the notebook with

```
mamba env update -f .binder/environment.yml
cd notebooks/
voila bqplot.ipynb
```

For more command line options (e.g., to specify an alternate port number),
run `voila --help`.

### As a server extension to `notebook` or `jupyter_server`

Voilà can also be used as a Jupyter server extension, both with the
[notebook](https://github.com/jupyter/notebook) server or with
[jupyter_server](https://github.com/jupyter/jupyter_server).

To install the Jupyter server extension, run

```
jupyter serverextension enable voila
jupyter server extension enable voila
```

When running the Jupyter server, the Voilà app is accessible from the base url
suffixed with `voila`.

## Documentation

To get started with using Voilà, check out the full documentation:

https://voila.readthedocs.io/

## Examples

The following two examples show how a standalone Jupyter notebook can be turned into a separate app, from the command-line integration.

### Rendering a notebook including interactive widgets and rich mime-type rendering

![Voilà basics](voila-basics.gif)

### Rendering a notebook making use of a custom widget library ([bqplot](https://github.com/bloomberg/bqplot))

![Voilà bqplot](voila-bqplot.gif)

### Showing the source code for a Voilà notebook

The sources of the Jupyter notebook can be displayed in a Voilà app if option `strip_sources` is set to `False`.

![Voilà sources](voila-sources.gif)

### Voilà dashboards with other language kernels\*\*

Voilà is built upon Jupyter standard formats and protocols, and is agnostic to the programming language of the notebook. In this example, we present an example of a Voilà application powered by the C++ Jupyter kernel [xeus-cling](https://github.com/jupyter-xeus/xeus-cling), and the [xleaflet](https://github.com/jupyter-xeus/xleaflet) project.

![Voilà cling](voila-cling.gif)

## The Voilà Gallery

The [Voilà Gallery](https://voila-gallery.org) is a collection of live dashboards and applications built with Voilà and Jupyter widgets.

Most of the examples rely on widget libraries such as ipywidgets, ipyleaflet, ipyvolume, bqplot and ipympl, and showcase how to build complex web applications entirely based on notebooks.

New examples can be added to the gallery by following the steps listed in the [voila-gallery/gallery](https://github.com/voila-gallery/gallery) repository.

## Development

See [CONTRIBUTING.md](./CONTRIBUTING.md) to know how to contribute and set up a development environment.

## Related projects

Voilà depends on [nbconvert](https://github.com/jupyter/nbconvert) and
[jupyter_server](https://github.com/jupyter/jupyter_server/).

## License

We use a shared copyright model that enables all contributors to maintain the
copyright on their contributions.

This software is licensed under the BSD-3-Clause license. See the
[LICENSE](LICENSE) file for details.
