Package: nbless
IntroductionThenblessPython package allows you to (de)construct, convert, and executeJupyter
Notebooksinyour terminal (e.g.bash,zsh,fish, etc.) oryour favorite Python environment (e.g.PyCharmorVisual Studio Code).ThenblessPython package consists of 6 Python functions and shell commands:nbconv, which converts a notebook into various formats.nbdeck, which prepares a notebook to be viewed as or converted into slides.nbexec, which runs a notebook from top to bottom and saves an executed version.nbless, which callsnbuildandnbexecto create and execute a notebook.nbraze, which extracts code and markdown files from a notebook.nbuild, which creates a notebook from source files, e.g. Python (.py) and R (.R) scripts, markdown (.md), and text (.txt) files.For a related package that provides programmatic tools for working withR Markdown(Rmd) files,
check out theRmdawn Python package.Documentation and codeThe documentation is hosted athttps://py4ds.github.io/nbless/.The code is hosted athttps://github.com/py4ds/nbless.Installationpipinstallnblessor clone therepo, e.g.git clonehttps://github.com/py4ds/nblessand install locally
using setup.py (python setup.py install) orpip(pip install .).UsageConverting Jupyter notebooks withnbconvThenbconvshell command can export a
notebook to many different formats using thenbconvertlibrary.
Converting to all formats except HTML requires pandoc.
Exporting to PDF requires LaTeX.The supported exporters areasciidocpdfhtmllatexmarkdownpythonrstscriptslidesFor example,nbconvcan create a python script by extracting
the content from code cells and discarding all output and markdown
content.nbconvnotebook.ipynb--exporterpython# Ornbconvnotebook.ipynb-epythonIn the example above, the output file would benotebook.py, but you can
provide a more descriptive name for the output file with the--out_fileor-oflag:nbconvnotebook.ipynb--out_filescript.py# Ornbconvnotebook.ipynb-oscript.pyIf theexporteris not provided,nbconvwill try to infer the exporter type
from theout_fileextension.If neither theexporterorout_filearguments are provided, the exporter will be set to html.nbconvnotebook.ipynbUnlike the shell command,
thenbconvPython function does not create a file on its own.
To create a converted file with Python, use thepathliblibrary.frompathlibimportPathfromnblessimportnbconv# Create notebook.py from notebook.ipynbfilename,contents=nbconv("notebook.ipynb","python")Path(filename).write_text(contents)# Create report.html from notebook.ipynbfilename,contents=nbconv("notebook.ipynb","html")Path('report.html').write_text(contents)Creating HTML slides withnbdeckandnbconvWithnbdeck, you can prepare HTML slides from a Jupyter notebook.nbdecknotebook.ipynb-oslides.ipynbnbconvslides.ipynb-eslides-oslides.htmlYou can runnbdeckwithoutnbconv,
if you do not want to create HTML slides and instead want to usenbvieweror theRISE extension.
If anout_filename is not provided, the notebook file contents will be
printed.
You can provide a more descriptive name for the executed output notebook with
the--out_fileor-oflag or by redirecting the output to a file with>.nbdecknotebook.ipynb--out_fileslides.ipynb# Ornbdecknotebook.ipynb-oslides.ipynb# Ornbdecknotebook.ipynb>slides.ipynbUnlike the shell command,
thenbdeckPython function does not create a file on its own.
To create a converted file, use thenbformatandpathliblibraries.importnbformatfromnblessimportnbconv,nbdeck# Create HTML slides from notebook.ipynb in notebooks foldernbformat.write(nbdeck("notebook.ipynb"),"slides.ipynb")filename,contents=nbconv("slides.ipynb","slides")Path(filename).write_text(contents)Executing a notebook withnbexecThenbexeccommand runs the input notebook from top to bottom.
If anout_filename is not provided, the executed notebook contents will be
printed.nbexecnotebook.ipynbYou can provide a more descriptive name for the executed output notebook with
the--out_fileor-oflag or by redirecting the output to a file with>.nbexecnotebook.ipynb--out_fileexecuted.ipynb# Ornbexecnotebook.ipynb-oexecuted.ipynb# Ornbexecnotebook.ipynb>executed.ipynbThe default kernel ispython3, but it is possible to specify the kernel
that will be used to run notebook with the--kernelor-kflag.nbexecnotebook.ipynb--kernelir--out_filenotebook.ipynb# Ornbexecnotebook.ipynb-kir-onotebook.ipynbYou can preview the default output filename and the raw notebook output by
runningnbexecwith only the positional argument:nbexecnotebook.ipynbUnlike the shell command,
thenbexecPython function does not create a file on its own.
To create a notebook file, use thenbformatlibrary.importnbformatfromnblessimportnbexec# Create notebook.ipynb from notebook.ipynbnb=nbexec("notebook.ipynb")nbformat.write(nb,"executed.ipynb")Rnb=nbexec("Rnotebook.ipynb")nbformat.write(Rnb,"Rexecuted.ipynb",kernel="ir")Creating and executing a Jupyter notebook withnblessThenblessshell command executes a notebook created from code and markdown/text files.nblessREADME.mdplot.pynotes.txt>executed.ipynbThe default kernel ispython3, but it is possible to specify the kernel that will be used to run notebook with the--kernelor-kflag.nblessREADME.mdplot.pynotes.txt--kernelir>Rnotebook.ipynb# OrnblessREADME.mdplot.pynotes.txt-kir>Rnotebook.ipynbInstead of redirecting to a file (>), you can use the--out_fileor-oflag:nblessREADME.mdplot.pynotes.txt--out_fileexecuted.ipynb# OrnblessREADME.mdplot.pynotes.txt-oexecuted.ipynbUnlike the shell command,
thenblessPython function does not create a file on its own.
To create a notebook file, use thenbformatlibrary.importnbformatfromnblessimportnbless# Build and execute a notebook with nblessnb=nbless(["plot.py","notes.txt"])nbformat.write(nb,"executed.ipynb")Rnb=nbless(["plot.R","notes.txt"],kernel="ir")nbformat.write(Rnb,"Rexecuted.ipynb")Extracting source files from a Jupyter notebook withnbrazeThenbrazeshell command takes the contents ofJupyter Notebook code cellsand turns them into code files, e.g. Python or R code files (.pyor.R). The contents ofmarkdown cellsare turned into markdown files.nbrazenotebook.ipynbThe default code file extension fornbrazeispy, but it is possible to
set the file extension with the--extensionor-eflag. If thelanguage_infokey is defined in the Jupyter notebook metadata,nbrazecan try to infer the code file extension from the programming language.nbrazenotebook.ipynb--extensionRnbrazenotebook.ipynb-ejsfromnblessimportnbraze# Create source files from notebook.ipynbnbraze("notebook.ipynb")nbraze("notebook.ipynb",extension="R")Creating a Jupyter notebook withnbuildThenbuildshell command takes the contents of Python or R code files
(.pyor.R) and stores them asJupyter Notebook code
cells.
The contents of all other files are stored inmarkdown
cells.nbuildREADME.mdplot.pynotes.txt>notebooks/notebook.ipynbInstead of redirecting to a file (>), you can use the--out_fileor-oflag:nbuildREADME.mdplot.pynotes.txt--out_filenotebooks/notebook.ipynb# OrnbuildREADME.mdplot.pynotes.txt-onotebooks/notebook.ipynbYou can preview the raw notebook output by runningnbuildwith only the positional arguments:nbuildREADME.mdplot.pynotes.txtThenbuildPython function does not create a file on its own.
To create a notebook file, use thenbformatlibrary.importnbformatfromnblessimportnbuild# Create notebook.ipynb from plot.py and notes.txtnb=nbuild(["plot.py","notes.txt"])nbformat.write(nb,"notebook.ipynb")Related projectspandocjupytextnotedownNext StepsCurrently, notebook metadata is lost when usingnbraze/nbuild/nbless.Enablenbuild/nblessto accept metadata via ametadata.jsonfile.Enablenbrazeto output metadata via ametadata.jsonfile.