Validation of Jupyter notebooks and kernels
Project description
JUPYTER NOTEBOOK VALIDATION
PROJECT OVERVIEW
This repository contains scripts used to validate ipynb notebooks and Jupyter kernels.
The goals of this project are to be able to:
- Execute validation of Jupyter kernels using ipynb notebooks in the terminal
- Execute validations non-interactively in a CI pipeline
- Check execution output for errors
- Compare output of an execution to known output
- Select different Jupyter kernels to use
- Log results of notebook executions and tests
Example partial output from validation tests run in the terminal:
Example ipynb notebook output created from failed execution of a notebook:
INSTALL
The jnbv module can be installed from gitlab.com or TestPyPi
Install with pip
Create a virtual environment if you don't already have one:
python3 -m venv venv
Activate your environment, in this example it's in venv/:
source venv/bin/activate
Install the code from TestPyPi (temporarily - will use PyPi eventually):
pip install nbformat==5.1.3 papermill==2.3.3
pip install -i https://test.pypi.org/simple/ jnbv
Note the seperate installation of dependencies - temporary procedure while using TestPyPi.
Or install from gitlab, dependencies will be installed:
pip install git+https://gitlab.com/MAXIV-SCISW/JUPYTERHUB/jnbv.git
Install with conda
If you have a conda environment, add the following lines to the list of dependencies to your yaml file:
- git
- pip
- pip:
- git+https://gitlab.com/MAXIV-SCISW/JUPYTERHUB/jnbv.git
Now update your conda environment, for example the base conda environment which is in the directory venv/:
venv/bin/conda env update --name base --file my-conda-env.yml
USAGE
jnbv -h
EXECUTE NOTEBOOK
For this, you will need to have:
- A base environment in which jnbv has been installed (see above)
- An ipynb notebook file
- A Jupyter kernel that will be used to execute the file
Once you have all these items, the base environment should be activated:
source venv/bin/activate
Check to see what kernels you have available:
jupyter kernelspec list
Available kernels:
hdf5-kernel /var/www/jupyterhub/jnbv/venv/share/jupyter/kernels/hdf5-kernel
python3 /var/www/jupyterhub/jnbv/venv/share/jupyter/kernels/python3
If you don't have any kernels, then install ipykernel into your environment with either pip or conda:
pip install ipykernel
conda install ipykernel
and then you should have the default kernel "python3" available.
If you don't have an ipynb notebook handy, you can get an example notebook file here:
wget https://gitlab.com/MAXIV-SCISW/JUPYTERHUB/jnbv/-/raw/master/development/the-meaning-of-life.ipynb
And then the ipynb notebook can be executed in the terminal, using the default kernel python3 for example:
jnbv the-meaning-of-life.ipynb \
--kernel_name python3 \
--execute
READ NOTEBOOK
By defualt, the result of executing an ipynb file is a new ipynb file named output.ipynb. It can be read in the terminal with:
jnbv output.ipynb --read
TEST NOTEBOOK
The same file can be checked for errors:
jnbv output.ipynb --test
COMPARE NOTEBOOKS
And two ipynb notebooks can be compared:
jnbv output.ipynb --compare the-meaning-of-life.ipynb
EXECUTE, TEST, COMPARE, SAVE
All steps can be made to run in succession with one command:
jnbv the-meaning-of-life.ipynb \
--kernel_name python3 \
--execute --read --test --compare --save
Or, more simply using the --validate option, which is a combination of 5 other options:
jnbv the-meaning-of-life.ipynb \
--kernel_name python3 \
--validate
Note that above the option --save was also added, which then creates the output
directory test-results/, and within that creates subdirectories with kernel
names, date stamps, and finally log files and new ipynb files.
For example:
test-results/
└── python3/
└── 2021-06-11_14-39-40/
├── the-meaning-of-life.ipynb
└── the-meaning-of-life.log
Example output from executing a simple notebook using the default kernel:
CONTRIBUTING
To contribute to this project, see: CONTRIBUTING.md
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 jnbv-2021.7.21.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 78454547165b799c3e1f60b6a6635b956f6c7fdf7e27d538aa293cf83f708e06 |
|
MD5 | 7ee5d4440dbb1274b2101caa40c03f85 |
|
BLAKE2b-256 | 4c352f74907a7ca93e90cf8894c887f70ed0f52d7c179b4bc3460b927c93f1f4 |