The stackclub Package

The Stack Club tutorial Jupyter notebooks make use of a number of homegrown functions and classes, which are kept in the stackclub package for easy import. You can browse these modules below.

Finding Documentation

There are a number of good places to find information about the classes and functions in the LSST software Stack: the built-in Jupyter notebook help() function already gets us a long way, but if you want to locate and read the source code, the stackclub.where_is function can help.

where_is.where_is(object, in_the=None)

Print a markdown hyperlink to the source code of object.

Parameters:

• object (python object) – The class or function you are looking for.
• in_the (string, optional) – The kind of place you want to look in: [‘source’, ‘repo’, ‘technotes’]

Examples

>>> from stackclub import where_is
>>> from lsst.daf.persistence import Butler
>>> where_is(Butler.get, in_the='source')
>>> where_is(Butler, in_the='repo')
>>> where_is(Butler, in_the='technotes')

Notes

See also the FindingDocs tutorial notebook for a working demo.

Importing Notebooks as Modules

Once this module has been imported, further import statements will treat Jupyter notebooks as importable modules. It’s unlikely that you will need to call any of the functions or classes in nbimport yourself - this section is just for reference.

This module was adapted from the Jupyter notebook documentation (copyright (c) Jupyter Development Team, and distributed under the terms of the Modified BSD License) for use in the stackclub package.

class nbimport.NotebookFinder

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 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 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 provides a live demo of this example.

find_module(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] – Suitable loader object for dealing with Notebook import statements.

Return type:

NotebookLoader

class nbimport.NotebookLoader(path=None)

Module Loader for Jupyter Notebooks

load_module(fullname)

Import a notebook as a module

Parameters:fullname (string) – Name of notebook (without the .ipynb extension) Returns:mod – Notebook in module form, after it has been imported (executed). Return type:module

Notes

All code cells in the notebook are executed, silently (by redirecting the standard output).

nbimport.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 – File name of notebook, if found (else None)

Return type:

string

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.

nbimport.stdoutIO(stdout=None)

Catch the stdout of the imported notebook cells.

Notes

Adapted from stackoverflow.com/questions/3906232 Note that this approach does not capture any rich notebook output, e.g. from IPython.display.

Importing Modules from the Web

This is pretty experimental!

wimport.wimport(url, vb=False)

Download a module and import it.

Parameters:

• url (string) – Web address of the target module
• vb (boolean, optional) – Verbose in operation [def=False]

Returns:

globals()[modulename] – The module, as imported.

Return type:

module

Notes

wimport maintains a secret local cache of downloaded modules, hidden from the user so that they are not tempted to edit the module locally. (If they need to do that, they should clone the relevant repo.)

Examples

Suppose the stackclub library did _not_ include the where_is module: we could still download it and import it, using wimport.

>>> where_is_url = "https://github.com/LSSTScienceCollaborations/StackClub/raw/issue/79/library/stackclub/where_is.py"
>>> from stackclub import wimport
>>> so = wimport(where_is_url, vb=True)
>>> so.where_is(Butler.get, in_the='source')