Skip to content

[Backport to 7.x] PR #3099 #3101

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 7, 2021
Merged

[Backport to 7.x] PR #3099 #3101

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
88626d9
Backport: Refactor outdated README
willingc Feb 7, 2021
e459874
Add sylvain feedback
willingc Feb 7, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 76 additions & 52 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
# ipywidgets: Interactive HTML Widgets

[![Version](https://img.shields.io/pypi/v/ipywidgets.svg)](https://pypi.python.org/pypi/ipywidgets)
[![Build Status](https://travis-ci.org/jupyter-widgets/ipywidgets.svg?branch=master)](https://travis-ci.org/jupyter-widgets/ipywidgets)
[![Documentation Status](http://readthedocs.org/projects/ipywidgets/badge/?version=latest)](https://ipywidgets.readthedocs.io/en/latest/?badge=latest)
[![Join the chat at https://gitter.im/ipython/ipywidgets](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jupyter-widgets/Lobby)
[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/jupyter-widgets/ipywidgets/master?filepath=docs%2Fsource%2Fexamples)

ipywidgets are [interactive HTML widgets](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb)
| Purpose | Badges |
|----------------------------|----------------------------|
| **Latest (master: future 8.0)** | [![Build Status](https://travis-ci.org/jupyter-widgets/ipywidgets.svg?branch=master)](https://travis-ci.org/jupyter-widgets/ipywidgets) [![Documentation Status: latest](https://img.shields.io/readthedocs/ipywidgets?logo=read-the-docs)](https://ipywidgets.readthedocs.io/en/latest/?badge=latest) [![Binder:master](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/jupyter-widgets/ipywidgets/master?filepath=docs%2Fsource%2Fexamples) |
| **Stable (7.6.3)** | [![Version](https://img.shields.io/pypi/v/ipywidgets.svg?logo=pypi)](https://pypi.python.org/pypi/ipywidgets) [![Conda Version](https://img.shields.io/conda/vn/conda-forge/ipywidgets.svg?logo=conda-forge)](https://anaconda.org/conda-forge/ipywidgets) [![Documentation Status: 7.6.3](https://img.shields.io/readthedocs/ipywidgets?logo=read-the-docs)](https://ipywidgets.readthedocs.io/en/7.6.3/?badge=7.6.3) [![Binder:7.x](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/jupyter-widgets/ipywidgets/7.x?filepath=docs%2Fsource%2Fexamples) |
| **Communication** | [![Join the chat at https://gitter.im/ipython/ipywidgets](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jupyter-widgets/Lobby) [![Discourse](https://img.shields.io/badge/help_forum-discourse-blue?logo=discourse)](https://discourse.jupyter.org/) |
| | |

**ipywidgets**, also known as jupyter-widgets or simply widgets, are
[interactive HTML widgets](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb)
for Jupyter notebooks and the IPython kernel.

Notebooks come alive when interactive widgets are used. Users gain control of
Expand All @@ -18,7 +20,9 @@ ipywidgets to your notebooks, and we're here to help you get started.

## Core Interactive Widgets

A [demonstration notebook](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb) provides an overview of the core interactive widgets, including:
The fundamental widgets provided by this library are called core interactive
widgets. A [demonstration notebook](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb)
provides an overview of the core interactive widgets, including:

- sliders
- progress bars
Expand All @@ -30,85 +34,104 @@ A [demonstration notebook](https://github.com/jupyter-widgets/ipywidgets/blob/ma
## Jupyter Interactive Widgets as a Framework

Besides the widgets already provided with the library, the framework can be
extended with custom widget libraries.

A template project is available in the form of a cookie cutter [here](https://github.com/jupyter-widgets/widget-ts-cookiecutter).
extended with the development of **custom widget libraries**. For detailed
information, please refer to the [ipywidgets documentation](https://ipywidgets.readthedocs.io/en/latest/).

This project is meant to help custom widget authors get started with the
packaging and the distribution of Jupyter interactive widgets.
### Cookiecutter template for custom widget development

It produces a project for a Jupyter interactive widget library following the
current best practices for using interactive widgets. An implementation for a
placeholder "Hello World" widget is provided.
A template project for building custom widgets is available as a
[**cookiecutter**](https://github.com/jupyter-widgets/widget-ts-cookiecutter).
This cookiecutter project helps custom widget authors get started with the
packaging and the distribution of their custom Jupyter interactive widgets.
The cookiecutter produces a project for a Jupyter interactive widget library
following the current best practices for using interactive widgets. An
implementation for a placeholder "Hello World" widget is provided as an example.

Popular widget libraries such as
[bqplot](https://github.com/bloomberg/bqplot),
[pythreejs](https://github.com/jovyan/pythreejs) and
[ipyleaflet](https://github.com/ellisonbg/ipyleaflet)

follow exactly the same template and directory structure. They can serve as
[bqplot](https://github.com/bqplot/bqplot),
[pythreejs](https://github.com/jupyter-widgets/pythreejs) and
[ipyleaflet](https://github.com/jupyter-widgets/ipyleaflet)
follow exactly the same template and directory structure. They serve as
more advanced examples of usage of the Jupyter widget infrastructure.

For detailed information, please refer to the [ipywidgets documentation](https://ipywidgets.readthedocs.io/en/latest/).

## More advanced examples
### Popular custom widget examples

Examples of custom widget libraries built upon ipywidgets are

- [bqplot](https://github.com/bloomberg/bqplot) a 2d data visualization library
- [bqplot](https://github.com/bqplot/bqplot) a 2d data visualization library
enabling custom user interactions.
- [pythreejs](https://github.com/jovyan/pythreejs) a Jupyter - Three.js wrapper,
- [pythreejs](https://github.com/jupyter-widgets/pythreejs) a Jupyter - Three.js wrapper,
bringing Three.js to the notebook.
- [ipyleaflet](https://github.com/ellisonbg/ipyleaflet) a leaflet widget for Jupyter.
- [ipyleaflet](https://github.com/jupyter-widgets/ipyleaflet) a leaflet widget for Jupyter.

## Install

Install the current version of ipywidgets using pip or conda.
The stable version of ipywidgets can be installed with [pip](#with-pip) or [conda](#with-conda).
If using JupyterLab, review the [Front-end extension for JupyterLab](#front-end-extension-for-jupyterlab) section.

- With pip:
### With pip

```
```sh
pip install ipywidgets
jupyter nbextension enable --py --sys-prefix widgetsnbextension # can be skipped for notebook version 5.3 and above
# Skip the next step if using JupyterLab or Classic notebook version 5.3 and above
jupyter nbextension enable --py --sys-prefix widgetsnbextension
```

- With conda:
### With conda

```
```sh
conda install -c conda-forge ipywidgets
```

See the [Installation](docs/source/user_install.md) section of the documentation for additional details.
### Front-end extension for JupyterLab

### Installing from git
Install the front-end extension to JupyterLab (note that this requires nodejs
to be installed):

If you want to install ipywidgets from git, **you will need the
[yarn](https://yarnpkg.com/) package manager version 1.2.1 or later**.
Installing from git is more complicated and requires a developer install, see the [developer install](docs/source/dev_install.md) instructions.
- For JupyterLab 1.0.x and 1.1.x, use `jupyter labextension install @jupyter-widgets/[email protected]`
- For JupyterLab 1.2.x, use `jupyter labextension install @jupyter-widgets/[email protected]`
- For JupyterLab 2.x, use `jupyter labextension install @jupyter-widgets/[email protected]`

To install the latest master version from the root directory of the source
code, run ``dev-install.sh``. To only build the Python package enter ``pip install -e .``.
See the [Installation](docs/source/user_install.md) section of the documentation
for additional details.

#### Compatibility
### Developer install from source

| ipywidgets version | Required notebook version |
| ------------------- | ------------------------- |
| master | 4.4 |
| 5.x | 4.2 |
| 4.1.x | 4.1 |
| 4.0.x | 4.0 |
Installing from source is more complicated and requires a developer install,
see the detailed [developer install](docs/source/dev_install.md) instructions.

[Change log](docs/source/changelog.md)
If you want to install ipywidgets from source, **you will need the
[yarn](https://yarnpkg.com/) package manager version 1.2.1 or later**.
To install the latest master version from the root directory of the source
code, run ``dev-install.sh``. To only build the Python package enter
``pip install -e .``.

## Usage

See the [examples](docs/source/examples.md) section of the documentation. The widgets are being used in a variety of ways; some uses can be seen in these notebooks:
[Demo notebook of interactive widgets](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb)

## Change log

[Change log](docs/source/changelog.md)

### Version Compatibility with Front-End Clients

Refer to change log for more detail.

- [Demo notebook of interactive widgets](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb)
| ipywidgets | JupyterLab | [Classic Notebook](https://github.com/jupyter/notebook) | [nbclassic](https://github.com/jupyterlab/nbclassic) |
| ---------- | :--------------: | :--------------: | :---------: |
| master | | - | TBD |
| 7.6.3 | | | 0.2.6 |
| **Legacy** | | | |
| 6.x | | | - |
| 5.x | | 4.2 | - |
| 4.1.x | | 4.1 | - |
| 4.0.x | | 4.0 | - |

## Contributing to ipywidgets

- [Developer information](CONTRIBUTING.md)
[Developer information](CONTRIBUTING.md)

## License

Expand All @@ -120,6 +143,7 @@ See the [LICENSE](LICENSE) file in this repository for details.
## Project Jupyter resources

- [Project Jupyter website](https://jupyter.org)
- [Online Demo of Jupyter Notebook at try.jupyter.org](https://try.jupyter.org)
- [Online Demo at try.jupyter.org](https://try.jupyter.org)
- [Documentation for Project Jupyter](https://jupyter.readthedocs.io/en/latest/index.html) [[PDF](https://media.readthedocs.org/pdf/jupyter/latest/jupyter.pdf)]
- [![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter)
- [![Discourse](https://img.shields.io/badge/help_forum-discourse-blue?logo=discourse)](https://discourse.jupyter.org/)
[![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter)