Jupyter/Extensions
From charlesreid1
Contents
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
Installing Notebook Extensions
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
How It Works
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 WORKING OK
Let's say we want to make an extension called smoketest. It would go in the src/jupyter_contrib_nbextensions/nbextensions directory:
$ git clone https://github.com/ipython-contrib/jupyter_contrib_nbextensions.git $ 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
Output from last command should be a success:
$ jupyter nbextension enable smoketest/smoke
Enabling notebook extension smoketest/smoke...
- Validating: OK
Example Summarized
git clone https://github.com/ipython-contrib/jupyter_contrib_nbextensions.git cd jupyter_contrib_nbextensions jupyter contrib nbextension install --user jupyter nbextension enable smoketest/smoke
Using 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.)
To just use the extensions, install directly from pip:
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
Also see
Bundling Jupyter extensions as packages: