Fearless interactivity for Jupyter notebooks.
Project description
➤ nbsafety
About
nbsafety
adds a layer of protection to computational notebooks by solving the
stale dependency problem, a problem which exists due to the fact that
notebooks segment execution into "cells" with implicit dependencies amongst
themselves. Here's an example in action:
Step 0: modify cell 1 | Step 1: rerun cell 1 |
---|---|
Step 2: rerun cell 2 | Step 3: rerun cell 3 |
---|---|
When the first cell is rerun, the second cell now contains a reference to an updated f
and
is suggested for re-execution with a turquoise highlight. The third cell contains a reference
to a stale y
-- y
is stale due to its dependency on an old value of f
. As such, the third
cell is marked as unsafe for re-execution with a red highlight.
Once the second cell is rerun, it is now suggested to re-execute the third cell in order to
refresh its stale output.
nbsafety
accomplishes its magic using a combination of a runtime tracer (to
build the implicit dependency graph) and a static checker (to provide warnings
before running a cell), both of which are deeply aware of Python's data model.
In particular, nbsafety
requires minimal to no changes in user
behavior, opting to get out of the way unless absolutely necessary and letting
you use notebooks the way you prefer.
Install
pip install nbsafety
If using JupyterLab, we highly recommend installing the companion extension:
jupyter labextension install jupyterlab-nbsafety # optional but highly recommended if using JupyterLab
Interface
The JupyterLab extension and bundled Jupyter notebook extension both show cells with unsafe executions (due to uses of variables with stale dependencies) as being annotated with red UI elements, and recommends cells to run (in order to refresh variables with stale dependencies) by displaying them with turquoise UI elements.
Running
Because nbsafety
is implemented as a custom Jupyter kernel, it works for both
Jupyter notebooks and JupyterLab (if using JupyterLab, the additional
labextension is recommended). To run an nbsafety
kernel, select "Python 3
(nbsafety)" from the list of notebook types in Jupyter's "New" dropdown
dialogue. For JupyterLab, similarly select "Python 3 (nbsafety)" from the list
of available kernels in the Launcher tab.
Jupyter Notebook Entrypoint: | Jupyter Lab Entrypoint: |
---|---|
Troubleshooting Install
The kernel and nbextension should be installed automatically, but in case the kernel is not available as an option or the UI elements are not showing up, try running the following:
python -m nbsafety.install
jupyter nbextension install --py nbsafety --sys-prefix
jupyter nbextension enable --py nbsafety --sys-prefix
Uninstall
In addition to pip uninstall nbsafety
, it is also necessary
to deregister the kernel from Jupyter for a full uninstall
(as well as the extension from JupyterLab, if using JupyterLab):
jupyter kernelspec uninstall nbsafety
jupyter labextension uninstall jupyterlab-nbsafety
License
Code in this project licensed under the BSD-3-Clause License.
➤ Contributors
Stephen Macke | Ray Gong | Shreya Shankar |
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for nbsafety-0.0.61-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2f4c7f4796ccb8fc253799ddf4053da234e8c74ef016393dd51d19e1a8470ac5 |
|
MD5 | 2708fe17ba391879472d13e78d0f9afd |
|
BLAKE2b-256 | 9387198795bb347a578f9699e04b8232108993e9436f924d94cda355e2d75409 |