"""
This module was adapted from the `Jupyter notebook documentation <https://github.com/jupyter/notebook/blob/master/docs/source/examples/Notebook/Importing%20Notebooks.ipynb>`_ (copyright (c) Jupyter Development Team, and distributed under the terms of the `Modified BSD License <https://github.com/jupyter/notebook/blob/master/COPYING.md>`_) for use in the ``stackclub`` package.
"""
import io, os, sys, types
from IPython import get_ipython
from nbformat import read
from IPython.core.interactiveshell import InteractiveShell
from io import StringIO
import contextlib
[docs]def find_notebook(fullname, path=None):
"""
Find a notebook, given its fully qualified name and an optional path.
Parameters
----------
fullname: string
Name of the notebook to be found (without ipynb extension)
path: string, optional
Path of folder containing notebook.
Returns
-------
nb_path: string
File name of notebook, if found (else None)
Notes
-----
The input notebook name "foo.bar" is turned into "foo/bar.ipynb".
Tries turning "Foo_Bar" into "Foo Bar" if Foo_Bar
does not exist.
"""
name = fullname.rsplit('.', 1)[-1]
if not path:
path = ['']
for d in path:
nb_path = os.path.join(d, name + ".ipynb")
if os.path.isfile(nb_path):
return nb_path
# let import Notebook_Name find "Notebook Name.ipynb"
nb_path = nb_path.replace("_", " ")
if os.path.isfile(nb_path):
return nb_path
return None
[docs]@contextlib.contextmanager
def stdoutIO(stdout=None):
"""
Catch the stdout of the imported notebook cells.
Notes
-----
Adapted from `stackoverflow.com/questions/3906232 <https://stackoverflow.com/questions/3906232/python-get-the-print-output-in-an-exec-statement/3906390#3906390>`_ Note that this approach does not capture any rich notebook output, e.g. from ``IPython.display``.
"""
old = sys.stdout
if stdout is None:
stdout = StringIO()
sys.stdout = stdout
yield stdout
sys.stdout = old
return
[docs]class NotebookLoader(object):
"""
Module Loader for Jupyter Notebooks
"""
def __init__(self, path=None):
self.shell = InteractiveShell.instance()
self.path = path
[docs] def load_module(self, fullname):
"""
Import a notebook as a module
Parameters
----------
fullname: string
Name of notebook (without the .ipynb extension)
Returns
-------
mod: module
Notebook in module form, after it has been imported (executed).
Notes
-----
All code cells in the notebook are executed, silently
(by redirecting the standard output).
"""
path = find_notebook(fullname, self.path)
print ("Importing code from Jupyter notebook %s" % path)
# load the notebook object
with io.open(path, 'r', encoding='utf-8') as f:
nb = read(f, 4)
# create the module and add it to sys.modules
# if name in sys.modules:
# return sys.modules[name]
mod = types.ModuleType(fullname)
mod.__file__ = path
mod.__loader__ = self
mod.__dict__['get_ipython'] = get_ipython
sys.modules[fullname] = mod
# extra work to ensure that magics that would affect the user_ns
# actually affect the notebook module's ns
save_user_ns = self.shell.user_ns
self.shell.user_ns = mod.__dict__
try:
for cell in nb.cells:
if cell.cell_type == 'code':
# transform the input to executable Python
code = self.shell.input_transformer_manager.transform_cell(cell.source)
# run the code in the module, catching the stdout:
with stdoutIO() as s:
try:
exec(code, mod.__dict__)
except:
print("Something wrong with one of the imported notebook cells:")
print(s.getvalue())
finally:
self.shell.user_ns = save_user_ns
return mod
[docs]class NotebookFinder(object):
"""
Module finder that locates Jupyter Notebooks.
Notes
-----
Once an instance of this class is appended to ``sys.meta_path``,
the ``import`` statement will work on notebook names.
Examples
--------
To gain the ability to import notebooks, we just import the :mod:`nbimport` module.
The DataInventory notebook might contain a useful function - here's how we'd
import it:
>>> import stackclub
>>> import DataInventory
We can also import remote notebooks, using :mod:`wimport`:
>>> import stackclub
>>> dm_butler_skymap_notebook = "https://github.com/LSSTDESC/DC2-analysis/raw/master/tutorials/dm_butler_skymap.ipynb"
>>> skymapper = stackclub.wimport(dm_butler_skymap_notebook, vb=True)
The `DataInventory notebook <https://github.com/LSSTScienceCollaborations/StackClub/blob/master/Basics/DataInventory.ipynb>`_ provides a live demo of this example.
"""
def __init__(self):
self.loaders = {}
[docs] def find_module(self, fullname, path=None):
"""
Find the notebook module and return a suitable loader.
Parameters
----------
fullname: string
Name of the notebook to be found (without ipynb extension)
path: string
Path of folder containing notebook (optional).
Returns
-------
loaders[path]: NotebookLoader
Suitable loader object for dealing with Notebook import statements.
"""
nb_path = find_notebook(fullname, path)
if not nb_path:
return
key = path
if path:
# lists aren't hashable
key = os.path.sep.join(path)
if key not in self.loaders:
self.loaders[key] = NotebookLoader(path)
return self.loaders[key]
# Register the NotebookFinder:
sys.meta_path.append(NotebookFinder())