Package: nbsrc
Jupyter notebooks from/to Python or R scriptsJupyter notebooks are complex files, that contain source code, metadata, and
rich outputs. Here we offer a simple and complementary format for Jupyter
notebooks, as pure python (or R) companion scripts.The resulting python scripts are perfect candidates for
keeping notebooks under version control. They can be
edited outside of Jupyter, using
your favorite text editor, or even standard merge tools if you wish to merge
multiple contributions to a notebook.With thenbsrcpackage, any python or R script can be loaded as a notebook
in Jupyter. If a classicalipynbnotebook with a matching name exists,
outputs for matching inputs are reconstructed. And, if you associate python
and jupyter files as recommended below, when aipynbnotebook opens, the
corresponding inputs are taken from thepyfile, which you may have updated
outside of Jupyter.Can I have a demo?Sure. Try our package onbinder!
There, you will be ableto open and execute arbitrary python files as notebooks (give a try to
the matplotlib demo namedfilled_step.py)to open a notebook, then edit the companion python script, and reload the notebook,
to find up-to-date inputs in Jupyter.How does the python version look like?Below is an example of a Jupyter notebook, together with its python representation.We have hundreds of tests that ensure thatRound trip conversion: python to notebook to python, is identityRound trip conversion, starting from a Jupyter notebook, preserves source
and metadata, not outputs. In some occasions (consecutive blank lines in
code cells), cells may be splitted into smaller ones.Pythonnotebookin JupyterPythonscriptThe representation of notebooks as R scripts follows thestandardfor that language.How do I activate the companion script?generate a jupyter config, if you don't have one yet, withjupyter notebook --generate-configedit the config and include the below:c.NotebookApp.contents_manager_class='nbrmd.RmdFileContentsManager'c.ContentsManager.default_nbrmd_formats='ipynb,py'Then, make sure you have thenbrmdpackage up-to-date, and re-start jupyter, i.e. runpipinstallnbrmd--upgrade
jupyternotebookWith the above configuration, every Jupyter notebook will have a companion.pyscript. And every.pyscript that you edit in Jupyter
will have a companion.ipynbnotebook.If you prefer the.ipynbnotebook not to be created by Jupyter when a.pyscript is edited, setc.ContentsManager.default_nbrmd_formats = ''(as the default value isipynb). Outputs for scripts, however,
will not be saved any more.Per notebook configurationWith the above configuration, every notebook will have a companion.pyfile.If you prefer that the companion script be generated only for a few notebooks,
then remove thec.ContentsManager.default_nbrmd_formatsline from Jupyter's
configuration, and instead edit the notebook metadata as follows:{
  "kernelspec": {
    "name": "python3",
    (...)
  },
  "language_info": {
    (...)
  },
  "nbrmd_formats": "ipynb,py"
}Accepted formats are:.ipynb,.Rmd,.pyand.R.In case you want both.pyand.Rmd, please note that the
order matters: the first non-.ipynbextension
is the one used as the reference source for notebook inputs.What is the difference betweennbsrcandnbrmd?nbrmdis a python package that represents Jupyter notebooks as R markdown
files. It is also where notebooks as python scripts are implemented. But
I felt notebooks as scripts deserved a standalone documentation, and
that's the main reason for having thenbsrcpackage.You don't actually need thenbsrcpackage unless you want the command line
conversion tools.Command line conversionThenbsrcpackage provides anbsrcscript that converts Jupyter notebooks
to R or python scripts, and vice-versa.Install it withpip install nbsrc --upgradeand then use it as:nbsrcjupyter.ipynb# this prints the `.py` or `.R` alternativenbsrcjupyter.ipynb-i# this creates a jupyter.py or jupyter.R filenbsrcjupyter.py-i# and this, a jupyter.ipynb filenbsrcjupyter.py-i-p# update the jupyter.ipynb file and preserve outputs that correspond to unchanged inputsAlternatively, thenbsrcpackage provides twonbconvertexporters that you can use withnbconvertjupyter.ipynb--topynotebook
nbconvertjupyter.ipynb--tornotebook