xdoctest.utils.util_notebook module

Utilities for handling Jupyter / IPython notebooks

This code is copied and modified from nbimporter (https://github.com/grst/nbimporter/blob/master/nbimporter.py) which is not actively maintained (otherwise we would use it as a dependency).

Note that using this behavior is very much discouraged, it would be far better if you maintained your reusable code in separate python modules. See https://github.com/grst/nbimporter for reasons.

---

Allow for importing of IPython Notebooks as modules from Jupyter v4.

Updated from module collated here: https://github.com/adrn/ipython/blob/master/examples/Notebook/Importing%20Notebooks.ipynb

Importing from a notebook is different from a module: because one typically keeps many computations and tests besides exportable defs, here we only run code which either defines a function or a class, or imports code from other modules and notebooks. This behaviour can be disabled by setting NotebookLoader.default_options[‘only_defs’] = False.

Furthermore, in order to provide per-notebook initialisation, if a special function __nbinit__() is defined in the notebook, it will be executed the first time an import statement is. This behaviour can be disabled by setting NotebookLoader.default_options[‘run_nbinit’] = False.

Finally, you can set the encoding of the notebooks with NotebookLoader.default_options[‘encoding’]. The default is ‘utf-8’.

class xdoctest.utils.util_notebook.CellDeleter

Bases: NodeTransformer

Removes all nodes from an AST which are not suitable for exporting out of a notebook.

visit(node)

Visit a node.

class xdoctest.utils.util_notebook.NotebookLoader(path=None)

Bases: object

Module Loader for Jupyter Notebooks.

default_options = {'encoding': 'utf-8', 'only_defs': False, 'run_nbinit': True}

load_module(fullname=None, fpath=None)

import a notebook as a module

xdoctest.utils.util_notebook.import_notebook_from_path(ipynb_fpath, only_defs=False)

Import an IPython notebook as a module from a full path and try to maintain clean sys.path variables.

Parameters:

• ipynb_fpath (str | PathLike) – path to the ipython notebook file to import

• only_defs (bool, default=False) – if True ignores all non-definition statements

Example

>>> # xdoctest: +REQUIRES(PY3, module:IPython, module:nbconvert)
>>> from xdoctest import utils
>>> from os.path import join
>>> self = utils.TempDir()
>>> dpath = self.ensure()
>>> ipynb_fpath = join(dpath, 'test_import_notebook.ipydb')
>>> cells = [
>>>     utils.codeblock(
>>>         '''
>>>         def foo():
>>>             return 'bar'
>>>         '''),
>>>     utils.codeblock(
>>>         '''
>>>         x = 1
>>>         ''')
>>> ]
>>> _make_test_notebook_fpath(ipynb_fpath, cells)
>>> module = import_notebook_from_path(ipynb_fpath)
>>> assert module.foo() == 'bar'
>>> assert module.x == 1

xdoctest.utils.util_notebook.execute_notebook(ipynb_fpath, timeout=None, verbose=None)

Execute an IPython notebook in a separate kernel

Parameters:

ipynb_fpath (str | PathLike) – path to the ipython notebook file to import

Returns:

nb

The executed notebook.

dict: resources

Additional resources used in the conversion process.

Return type:

nbformat.notebooknode.NotebookNode

Example

>>> # xdoctest: +REQUIRES(PY3, module:IPython, module:nbconvert, CPYTHON)
>>> from xdoctest import utils
>>> from os.path import join
>>> self = utils.TempDir()
>>> dpath = self.ensure()
>>> ipynb_fpath = join(dpath, 'hello_world.ipydb')
>>> _make_test_notebook_fpath(ipynb_fpath, [utils.codeblock(
>>>     '''
>>>     print('hello world')
>>>     ''')])
>>> nb, resources = execute_notebook(ipynb_fpath, verbose=3)
>>> print('resources = {!r}'.format(resources))
>>> print('nb = {!r}'.format(nb))
>>> for cell in nb['cells']:
>>>     if len(cell['outputs']) != 1:
>>>         import warnings
>>>         warnings.warn('expected an output, is this the issue '
>>>                       'described [here](https://github.com/nteract/papermill/issues/426)?')