Import Jupyter Notebooks notebooks as Python modules
Live Coding Demo: Using Jupyter Notebooks as Python Modules with Margo Loader.
- Official tutorial (GitHub) on using Margo loader to write Modular Jupyter notebooks. Binder
- Quick demo notebook (Google Colab) in Google Colaboratory (no install needed).
- A more realistic suite of notebooks (GitHub) for background deletion and color extraction on William Blake prints, written for the Yale Digital Humanities Lab. Binder
To install margo-loader, run:
pip install git+https://github.com/margo-notebooks/margo-loader-py
Assuming you have a file called "notebook.ipynb":
import margo_loader
import notebook
Not every cell in a Notebook makes sense to include in its module representation.
If you want to prevent a cell from being exported, start the cell with the specially-formatted comment line # :: ignore-cell ::
, like this:
# :: ignore-cell ::
print("This code will not be executed when imported with margo-loader")
This special code comment is called a Margo note. Margo notes in Python cells begin with # ::
to differentiate them from regular comments, and end with ::
.
Learn more about the underlying Margo syntax here.
An alias for ignore-cell
is skip
. So this does the same thing:
# :: skip ::
print("This code will not be executed when imported with margo-loader")
You can organize code cells into virtual submodules within
a notebook. This in effect allows you to group cells from the same notebook.
Here's an example of a few cells from the file
test_notebooks/greetings.ipynb
in this repo.
# greetings.ipynb
# :: submodule: "grumpy" ::
def say_hello(to="world"):
return f"Oh, uhh, hi {to}..."
# greetings.ipynb
# :: submodule: "nice" ::
def say_hello(to="world"):
return f"Hello, {to}! Nice to see you."
Notice we define the same say_hello
function twice. If the entire notebook
were imported, the second say_hello
would overwrite the first. However, we can
import either of these submodules or both using Python's standard import syntax once we
import margo_loader
.
>>> import margo_loader
>>> from test_notebooks.greetings import nice, grumpy
>>> nice.say_hello()
'Hello, world! Nice to see you.'
>>> grumpy.say_hello()
'Oh, uhh, hi world...'
>>>
To prevent a notebook from being imported, use:
# :: not-a-module ::
or
# :: do-not-import ::
These are currently aliases with the same behavior. If you try to import a notebook that contains a do-not-import
/not-a-module
declaration, it will raise an exception.
If you want to ignore a lot of cells during import, you can use
# :: stop-module ::
and
# :: start-module ::
to exclude blocks of cells.
Any cell including and after a cell that contains stop-module
will be excluded during import until a start-module
cell is encountered.
Conversely, any cell including and after a cell that contains start-module
will be excluded during import until a stop-module
is encountered.
Note that you can also use start
and stop
instead of start-module
and stop-module
. These are aliases.
You can use stop-module
with no subsequent start-module
. This will have the effect of ignoring all subsequent cells.
This library works with Jupyter Notebooks (.ipynb files) as well as python files
with percent cell formatting using the file extension .pynb
. These are plain
source Python files that use # %%
to split the document into cells. Read more
here.
Look at test_notebooks/hello_notebook_pynb.pynb
in this repo for an example of
a code-cell notebook.
STABILITY NOTE: This is an alpha feature. The .pynb extension may be changed in a future version
This project borrows its implementation approach from a Jupyter Notebook
documentation
example
that imports notebooks in their entirety as if they were .py
files. The key difference Margo Loader adds is use of Margo notes to create preoprocessor directives ignore-cell
and submodule
.