Jupyter/Extensions
From charlesreid1
Notebook extensions
To enable/install a notebook extension:
jupyter nbextension enable <nbextension require path>
Example: Jupyter/Base16mpl
Also see: https://github.com/ipython-contrib/jupyter_contrib_nbextensions
Server extensions
To enable/install a server extension:
jupyter serverextension enable <sererextension require path and flags>
Example: Jupyter/MPI
User-Contributed Notebook Extensions
Full instructions here:
Start by installing the different nb extensions available:
pip3 install jupyter_contrib_nbextensions
Install the notebook extension files:
jupyter contrib nbextension install --user
Command line options:
--user to install into the user's home jupyter directories
--system to perform installation into system-wide jupyter directories
--sys-prefix to install into python's sys.prefix, useful for instance in virtual environments, such as with conda
--symlink to symlink the nbextensions rather than copying each file (recommended, on non-Windows platforms).
--debug, for more-verbose output
To enable an extension:
jupyter nbextension enable <nbextension require path>
for example,
jupyter nbextension enable codefolding/main jupyter nbextension enable toc2/main
To disable the extension again, use
jupyter nbextension disable <nbextension require path>
Making An Extension
Rolling Your Own
See ipyvolume: https://github.com/maartenbreddels/ipyvolume
Basically just defines a function _jupyter_nbextension_paths: https://github.com/maartenbreddels/ipyvolume/blob/master/ipyvolume/__init__.py#L12
And that's it.
def _jupyter_nbextension_paths():
return [{
'section': 'notebook',
'src': 'static',
'dest': 'ipyvolume',
'require': 'ipyvolume/extension'
}]
To install it, the recommended method is:
pip install ipyvolume jupyter nbextension enable --py --sys-prefix ipyvolume
Or with a dev version (git):
$ git clone https://github.com/maartenbreddels/ipyvolume.git $ cd ipyvolume $ pip install -e . $ jupyter nbextension install --py --symlink --sys-prefix ipyvolume $ jupyter nbextension enable --py --sys-prefix ipyvolume
Build Extensions from Gists
The Vision
This is an intriguing blog post: https://mindtrove.info/4-ways-to-extend-jupyter-notebook/#nb-extensions
Today, the recommended way of installing, loading, and unloading extensions requires running a few snippets of code either within a notebook associated with an IPython kernel or in an external Python script. To install, for example, minrk's gist nbextension, you can execute the following code in a notebook.import notebook.nbextensions notebook.nbextensions.install_nbextension('https://rawgithub.com/minrk/ipython_extensions/master/nbextensions/gist.js', user=True)The code above downloads the JavaScript file and copies it into your Jupyter data directory (e.g., ~/.local/share/jupyter/nbextensions). Once installed, you can load the gist extension by executing the following JavaScript in a code cell:
%%javascript Jupyter.utils.load_extensions('gist')The cell above emits a <script> element into the output area of the notebook cell. That script loads the gist.js JavaScript module from the Notebook server backend. On load, the gist extension adds a button appears to the toolbar which you can click to post the current notebook document as a gist.
Now a notebook configuration file can be updated to load the extension automatically:
from notebook.services.config import ConfigManager
cm = ConfigManager()
cm.update('notebook', {"load_extensions": {"gist": True}})
How It Works
Again, see: https://mindtrove.info/4-ways-to-extend-jupyter-notebook/#nb-extensions
(From 2015, but about Jupyter - how much has changed?)
To actually put this into practice, all of the logic goes into a JS file. It must conform to AMD specification so it can be loaded by Require.js.
A load_ipython_extension function should be defined in the module - Jupyter will invoke this after it initializes its own components.
From the load_ipython_extension function, you can manipulate the DOM of the page, invoke several APIs provided by Jupyter, listen for Jupyter events, load other modules, etc.
Example
Let's say we want to make an extension called smoketest. It would go in the src/jupyter_contrib_nbextensions/nbextensions directory:
$ cd jupyter_contrib_nbextensions $ ls -R src/jupyter_contrib_nbextensions/nbextensions smoketest src/jupyter_contrib_nbextensions/nbextensions/smoketest: README.md smoke.css smoke.js smoketest.yaml
Start with the yaml config file:
$ cat smoketest.yaml Type: IPython Notebook Extension Name: smoketest Link: README.md Description: Smoketest for adding a css style Main: main.js Compatibility: 4.x, 5.x
The JS file is kept simple, drawing from the examples, and just adds a CSS file to the header:
/**
* ----------------------------------------------------------------------------
* Smoke test: modify css with bootstrap
* ----------------------------------------------------------------------------
*/
define([
'require',
'jquery',
'base/js/events'
], function (
requirejs,
$,
events
) {
'use strict';
}
function load_css (name) {
$('<link/>').attr({
type: 'text/css',
rel: 'stylesheet',
href: requirejs.toUrl(name)
}).appendTo('head');
}
var load_jupyter_extension = function () {
load_css('./main.css');
/*
events.on("notebook_loaded.Notebook", do_stuff);
events.on("kernel_ready.Kernel", do_stuff);
events.on("output_appended.OutputArea", do_stuff);
events.on("rendered.MarkdownCell", do_stuff);
*/
};
return {
'load_jupyter_extension': load_jupyter_extension,
'load_ipython_extension': load_jupyter_extension
};
});
Same thing with the CSS file, which just changes the header h1 color and a test div text color to red:
h1 {
color: #ff0000;
}
div#crazy {
color: #ff0000;
}
To actually install this, go back to the jupyter_contrib_nbextensions directory:
cd jupyter_contrib_nbextensions jupyter contrib nbextension install --user
here's the output:
$ jupyter contrib nbextension install --user
[I 19:35:06 InstallContribNbextensionsApp] jupyter contrib nbextension install --user
[I 19:35:06 InstallContribNbextensionsApp] Installing jupyter_contrib_nbextensions nbextension files to jupyter data directory
[I 19:35:06 InstallContribNbextensionsApp] Installing /Users/charles/codes/ipy/jupyter_contrib_nbextensions/src/jupyter_contrib_nbextensions/nbextensions/smoketest -> smoketest
[I 19:35:06 InstallContribNbextensionsApp] Making directory: /Users/charles/Library/Jupyter/nbextensions/smoketest/
[I 19:35:06 InstallContribNbextensionsApp] Copying: /Users/charles/codes/ipy/jupyter_contrib_nbextensions/src/jupyter_contrib_nbextensions/nbextensions/smoketest/main.css -> /Users/charles/Library/Jupyter/nbextensions/smoketest/main.css
[I 19:35:06 InstallContribNbextensionsApp] Copying: /Users/charles/codes/ipy/jupyter_contrib_nbextensions/src/jupyter_contrib_nbextensions/nbextensions/smoketest/main.js -> /Users/charles/Library/Jupyter/nbextensions/smoketest/main.js
[I 19:35:06 InstallContribNbextensionsApp] Copying: /Users/charles/codes/ipy/jupyter_contrib_nbextensions/src/jupyter_contrib_nbextensions/nbextensions/smoketest/README.md -> /Users/charles/Library/Jupyter/nbextensions/smoketest/README.md
[I 19:35:06 InstallContribNbextensionsApp] Copying: /Users/charles/codes/ipy/jupyter_contrib_nbextensions/src/jupyter_contrib_nbextensions/nbextensions/smoketest/smoketest.yaml -> /Users/charles/Library/Jupyter/nbextensions/smoketest/smoketest.yaml
----------------------8<------------------------
[I 19:35:06 InstallContribNbextensionsApp] Installing jupyter_contrib_nbextensions items to config in /Users/charles/.jupyter
Enabling: jupyter_nbextensions_configurator
- Writing config: /Users/charles/.jupyter
- Validating...
jupyter_nbextensions_configurator OK
Enabling notebook nbextension nbextensions_configurator/config_menu/main...
Enabling tree nbextension nbextensions_configurator/tree_tab/main...
[I 19:35:06 InstallContribNbextensionsApp] Enabling notebook extension contrib_nbextensions_help_item/main...
[I 19:35:06 InstallContribNbextensionsApp] - Validating: OK
[I 19:35:06 InstallContribNbextensionsApp] - Editing config: /Users/charles/.jupyter/jupyter_nbconvert_config.json
[I 19:35:06 InstallContribNbextensionsApp] -- Configuring nbconvert template path
[I 19:35:06 InstallContribNbextensionsApp] -- Configuring nbconvert preprocessors
[I 19:35:06 InstallContribNbextensionsApp] - Writing config: /Users/charles/.jupyter/jupyter_nbconvert_config.json
[I 19:35:06 InstallContribNbextensionsApp] -- Writing updated config file /Users/charles/.jupyter/jupyter_nbconvert_config.json
This will also modify your startup Jupter config file to include the template location:
{
"version": 1,
"Exporter": {
"template_path": [
".",
"/usr/local/lib/python3.6/site-packages/jupyter_contrib_nbextensions/templates",
"/Users/charles/codes/ipy/jupyter_contrib_nbextensions/src/jupyter_contrib_nbextensions/templates"
],
The last step is to tell it where you have your include files, in this case smoke.js:
jupyter nbextension enable smoketest/smoke
Bundling and Distributing
Linked article recommends writing setup.py to install jupyter-pip to take care of packaging a python module/package as a Jupyter extension.
jupyter-pip eases the setup process for that...??? - https://github.com/jdfreder/jupyter-pip
Using User Contributed Notebook Extensions
Use this repo as a template: https://github.com/ipython-contrib/jupyter_contrib_nbextensions
This repo contains a large selection of extensions for notebook. An extension consists of a Javascript file and, optionally, a CSS file.
By loading an extension, you can provide functionality from the Javascript portion of a Jupyter notebook (ajax, updating text, rendering equations, etc.)
Start by checking out a copy (optional):
git clone https://github.com/ipython-contrib/jupyter_contrib_nbextensions
Now build nb extensions:
cd jupyter_contrib_nbextensions pip install -e .
or directly from pip to just use the extensions:
pip install jupyter_contrib_nbextensions
or directly from github to also just use the extensions:
pip install https://github.com/ipython-contrib/jupyter_contrib_nbextensions/tarball/master