A tool to make your notebook sexier than before.
Project description
nbsexy:
nbsexy is a little tool to check whether your notebook is clean and readable (and also, sexy). You can use it either as a CLI tool or pre-commit hook.
Install (for now):
pip install nbsexy
Checks:
Currently, there are five check flags available:
-
--cell_count
: Check number of cell in notebook doesnot exceed certain number (default 20). Too many cells means you proability do too many thing in a single notebook, you can consider split it to several files. -
--is_ascending
: Check the cell number(execution_counts) is in ascending order. Notebook should be able to restart and run again without any error. If the cell number is not in ascending order, error may happend when you try to run it. -
--has_md
: Check notebook has at least one markdown cell. You should use markdown cell to tell everyone the story about this notebook. Otherwise, it just a bunch of unoriginazed codes. -
--line_in_cell
: Check all code cell in notebook have lines less than certain number. Cells with too many lines, just like script with too many lines, make me sick :confounded: . -
--total_line_in_nb
check sum of lines in all code cells doesnot exceed certain number. Like I said, too many line make me sick.
experimental: execute notebook with (or without) parameter.
Usage:
With flag --execute
, you can execute your notebook, if there's any error raised in any cell, nbsexy will exit with return code 1, and label as failed
.
By default, nbsexy will try to find parameters in notebook (explain below), and execute notebook with these parameters. If you want to execute without using these parameter, you can set flag: --execute_without_parameters
.
Parameter Execution:
* Why Parameter Execution:
Often, your notebook may have some cells, that will take you hours or even days to execute. It may not be practical to simply re-run these cells when you use nbsexy to execute notebooks.
In this case, you can set some parameters, which can ease or control the cost of computation in your notebook.
Take deep learning training loop as an example, below is a code snippet:
N_EPOCH = 50
for epoch in range(N_EPOCH):
train_a_epoch() # cost a lot of time!!
By setting N_EPOCH=1
, you can limit this training loop run only once when execute. Or you can also set other parameter to control the size of model or amount of training data you load.
* How to set parameter:
with the help of papermill, we can parameterize jupyter notebook and then execute it.
To parameterize your notebook, you need to create at least two cell, one with tag parameters
and one with tag nbsexy-parameters
. The nbsexy-parameters
cell should be on top of parameters
cell.
You can specify parameters you want to use in the nbsexy-parameters
cell. When nbsexy is called with flag --execute
, it will replace the "parameters in parameters
cell" with "parameters in nbsexy-parameters
", and then execute.
* How to Add Tags:
You can find the tag function in the toolbar, it maybe on the left or right base on your jupyterlab's version.
Limitation:
- The parameters must be basic types like int, float, str, list, dict, tuple, set. To pass function or object as parameters, you can create a dict mapping and use key as a parameter to select your object. Like this:
- You can create as many cells with
nbsexy-parameters
tag as you like, but you can create only oneparameters
cell. And all thenbsexy-parameters
cell should be on top ofparameters
cells.
Use nbsexy as pre-commit hook:
- install pre-commit
pip install pre-commit
- edit your
.pre-commit-config.yaml
file, something like...
default_language_version:
python: python3.6
repos:
- repo: https://github.com/hyades910739/nbsexy
rev: 0.0.3
hooks:
- id: nbsexy-cell-count
verbose: true
args: [--max_cell_count=15]
- id: nbsexy-is-ascending
verbose: true
- id: nbsexy-has-md
verbose: true
- id: nbsexy-line-in-cell
verbose: true
- id: nbsexy-total-line-in-nb
verbose: true
- install hooks:
pre-commit install
- try to run your hook with:
pre-commit run --all-files
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.