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='source', assuming_its_a=None)[source]¶ Print a markdown hyperlink to the source code of object.
Parameters: - object (python object or string) – The class or function you are looking for, or the name of a python object or file.
- in_the (string, optional) – The kind of place you want to look in: [‘source’, ‘repo’, ‘technotes’]
- assuming_its_a (string, optional) – The kind of object you think you have: `[‘cmdlinetask’], default=None
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') >>> where_is("makeDiscreteSkyMap.py", in_the="source", assuming_its_a="cmdlinetask")
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
[source]¶ Module finder that locates Jupyter Notebooks.
Notes
Once an instance of this class is appended to
sys.meta_path
, theimport
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)[source]¶ 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:
-
-
class
nbimport.
NotebookLoader
(path=None)[source]¶ Module Loader for Jupyter Notebooks
-
load_module
(fullname)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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 thewhere_is
module: we could still download it and import it, usingwimport
.>>> 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')