export

Exporting a notebook to a library

---

source

ExportModuleProc

def ExportModuleProc(
    args:VAR_POSITIONAL, kwargs:VAR_KEYWORD
):

A processor which exports code to a module

Specify dest where the module(s) will be exported to, and optionally a class to use to create the module (ModuleMaker, by default).

Exported cells are stored in a dict called modules, where the keys are the modules exported to. Those without an explicit module are stored in the '#' key, which will be exported to default_exp.

everything_fn = '../../tests/01_everything.ipynb'

exp = ExportModuleProc()
proc = NBProcessor(everything_fn, exp)
proc.process()
test_eq(exp.default_exp, 'everything')
assert 'print_function'  in exp.modules['#'][1].source
assert 'h_n' in exp.in_all['some.thing'][0].source

Optional export processors

---

source

black_format

def black_format(
    cell, # Cell to format
    force:bool=False, # Turn black formatting on regardless of settings.ini
):

Processor to format code with black

_cell = read_nb('../../tests/export_procs.ipynb')['cells'][0]
black_format(_cell, force=True)
test_eq(_cell.source, 'j = [1, 2, 3]')

---

source

scrub_magics

def scrub_magics(
    cell, # Cell to format
):

Processor to remove cell magics from exported code

scrub_magics is a processor that scrubs the jupyter “magics” lines out of exported cells. This can be helpful when using tools like sparkmagic or just Jupyter’s builtin magics in an nbdev project.

Usage:
This behavior can be enabled by passing scrub_magics into the --procs flag of the nbdev_export command. - nbdev_export --procs scrub_magics - nbdev_export --procs 'scrub_magics black_format'

Example:

A cell like below could export the line "hello nbdev" into the bar module. And the %%spark magic line would be omitted.

%%spark
#| export bar
"hello nbdev"

It will export as something similar to this:

# %% ../path/to/01_bar.ipynb 1
"hello nbdev"

_cell = read_nb('../../tests/export_procs.ipynb')['cells'][2]
scrub_magics(_cell)
test_eq(_cell.source, '''#| export bar
"hello nbdev"''')

---

source

optional_procs

def optional_procs(
    
):

An explicit list of processors that could be used by nb_export

# every optional processor should be explicitly listed here
test_eq(optional_procs(), ['black_format', 'scrub_magics'])

nb_export

---

source

nb_export

def nb_export(
    nbname:str, # Filename of notebook
    lib_path:str=None, # Path to destination library.  If not in a nbdev project, defaults to current directory.
    procs:NoneType=None, # Processors to use
    name:str=None, # Name of python script {name}.py to create.
    mod_maker:type=<class 'nbdev.maker.ModuleMaker'>, debug:bool=False, # Debug mode
    solo_nb:bool=False, # Export single notebook outside of an nbdev project.
):

Create module(s) from notebook

Let’s check we can import a test file:

shutil.rmtree('tmp', ignore_errors=True)
nb_export('../../tests/00_some.thing.ipynb', 'tmp')

g = exec_new('import tmp.some.thing')
test_eq(g['tmp'].some.thing.__all__, ['a'])
test_eq(g['tmp'].some.thing.a, 1)

We’ll also check that our ‘everything’ file exports correctly:

nb_export(everything_fn, 'tmp')

g = exec_new('import tmp.everything; from tmp.everything import *')
_alls = L("a b d e m n o p q".split())
for s in _alls.map("{}_y"): assert s in g, s
for s in "c_y_nall _f_y_nall g_n h_n i_n j_n k_n l_n".split(): assert s not in g, s
for s in _alls.map("{}_y") + ["c_y_nall", "_f_y_nall"]: assert hasattr(g['tmp'].everything,s), s

That notebook should also export one extra function to tmp.some.thing:

del(sys.modules['tmp.some.thing']) # remove from module cache
g = exec_new('import tmp.some.thing')
test_eq(g['tmp'].some.thing.__all__, ['a','h_n'])
test_eq(g['tmp'].some.thing.h_n(), None)

Path('../nbdev/export.py').unlink(missing_ok=True)
nb_export('04_export.ipynb')

g = exec_new('import nbdev.export')
assert hasattr(g['nbdev'].export, 'nb_export')