{
“cells”: [
{

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“# Distributing Jupyter Extensions as Python Packages”

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“## Overviewn”, “### How can the notebook be extended?n”, “The Jupyter Notebook client and server application are both deeply customizable. Their behavior can be extended by creating, respectively:n”, “n”, “- nbextension: a notebook extensionn”, ” - a single JS file, or directory of JavaScript, Cascading StyleSheets, etc. that contain atn”, ” minimum a JavaScript module packaged as ann”, ” [AMD modules](https://en.wikipedia.org/wiki/Asynchronous_module_definition)n”, ” that exports a function load_ipython_extensionn”, “- server extension: an importable Python modulen”, ” - that implements load_jupyter_server_extensionn”, “- bundler extension: an importable Python module with generated File -> Download as / Deploy as menu item triggern”, ” - that implements bundle

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“### Why create a Python package for Jupyter extensions?n”, “Since it is rare to have a server extension that does not have any frontend components (an nbextension), for convenience and consistency, all these client and server extensions with their assets can be packaged and versioned together as a Python package with a few simple commands, or as of Notebook 5.3, handled automatically by your package manager of choice. This makes installing the package of extensions easier and less error-prone for the user.”

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“## Installation of Jupyter Extensionsn”, “### Install a Python package containing Jupyter Extensionsn”, “There are several ways that you may get a Python package containing Jupyter Extensions. Commonly, you will use a package manager for your system:n”, “`shell\n", "pip install helpful_package\n", "# or\n", "conda install helpful_package\n", "# or\n", "apt-get install helpful_package\n", "\n", "# where 'helpful_package' is a Python package containing one or more Jupyter Extensions\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“### Automatic installation and Enablingn”, “> New in Notebook 5.3n”, “n”, “The absolute simplest case requires no user interaction at all! Configured correctly, after installing with their package manager of choice, both server and frontend extensions can be enabled by default in the environment where they were installed, i.e. –sys-prefix. See the setup.py in the example below.”

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“### Enable a Server Extensionn”, “n”, “The simplest case would be to enable a server extension which has no frontend components. n”, “n”, “A pip user that wants their configuration stored in their home directory would type the following command:n”, “`shell\n", "jupyter serverextension enable --py helpful_package\n", "`n”, “n”, “Alternatively, a virtualenv or conda user can pass –sys-prefix which keeps their environment isolated and reproducible. For example:n”, “`shell\n", "# Make sure that your virtualenv or conda environment is activated\n", "[source] activate my-environment\n", "\n", "jupyter serverextension enable --py helpful_package --sys-prefix\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“### Install the nbextension assets”

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“If a package also has an nbextension with frontend assets that must be available (but not neccessarily enabled by default), install these assets with the following command:n”, “`shell\n", "jupyter nbextension install --py helpful_package # or --sys-prefix if using virtualenv or conda\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“### Enable nbextension assetsn”, “If a package has assets that should be loaded every time a Jupyter app (e.g. lab, notebook, dashboard, terminal) is loaded in the browser, the following command can be used to enable the nbextension:n”, “`shell\n", "jupyter nbextension enable --py helpful_package # or --sys-prefix if using virtualenv or conda\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“## Did it work? Check by listing Jupyter Extensions.n”, “After running one or more extension installation steps, you can list what is presently known about nbextensions, server extensions, or bundler extensions. The following commands will list which extensions are available, whether they are enabled, and other extension details:n”, “n”, “`shell\n", "jupyter nbextension list\n", "jupyter serverextension list\n", "jupyter bundlerextension list\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“## Additional resources on creating and distributing packages n”, “n”, “> Of course, in addition to the files listed, there are number of other files one needs to build a proper package. Here are some good resources:n”, “- [The Hitchhiker’s Guide to Packaging](https://the-hitchhikers-guide-to-packaging.readthedocs.io/en/latest/quickstart.html)n”, “- [Repository Structure and Python](https://kenreitz.org/essays/2013/01/27/repository-structure-and-python) by Kenneth Reitzn”, “n”, “> How you distribute them, too, is important:n”, “- [Packaging and Distributing Projects](https://python-packaging-user-guide.readthedocs.io/tutorials/distributing-packages/)n”, “- [conda: Building packages](https://conda.io/projects/conda-build/en/latest/user-guide/tutorials/building-conda-packages.html)n”

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“## Example - Server extension”

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“### Creating a Python package with a server extensionn”, “n”, “Here is an example of a python module which contains a server extension directly on itself. It has this directory structure:n”, “`\n", "- setup.py\n", "- MANIFEST.in\n", "- my_module/\n", "  - __init__.py\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“### Defining the server extensionn”, “This example shows that the server extension and its load_jupyter_server_extension function are defined in the __init__.py file.n”, “n”, “#### my_module/__init__.pyn”, “n”, “`python\n", "def _jupyter_server_extension_paths():\n", "    return [{\n", "        \"module\": \"my_module\"\n", "    }]\n", "\n", "\n", "def load_jupyter_server_extension(nbapp):\n", "    nbapp.log.info(\"my module enabled!\")\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“### Install and enable the server extensionn”, “Which a user can install with:n”, “`\n", "jupyter serverextension enable --py my_module [--sys-prefix]\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“## Example - Server extension and nbextension”

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“### Creating a Python package with a server extension and nbextensionn”, “Here is another server extension, with a front-end module. It assumes this directory structure:n”, “n”, “`\n", "- setup.py\n", "- MANIFEST.in\n", "- my_fancy_module/\n", "  - __init__.py\n", "  - static/\n", "    index.js\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {

“collapsed”: true

}, “source”: [

“### Defining the server extension and nbextensionn”, “This example again shows that the server extension and its load_jupyter_server_extension function are defined in the __init__.py file. This time, there is also a function _jupyter_nbextension_paths for the nbextension.n”, “n”, “#### my_fancy_module/__init__.pyn”, “n”, “`python\n", "def _jupyter_server_extension_paths():\n", "    return [{\n", "        \"module\": \"my_fancy_module\"\n", "    }]\n", "\n", "# Jupyter Extension points\n", "def _jupyter_nbextension_paths():\n", "    return [dict(\n", "        section=\"notebook\",\n", "        # the path is relative to the `my_fancy_module` directory\n", "        src=\"static\",\n", "        # directory in the `nbextension/` namespace\n", "        dest=\"my_fancy_module\",\n", "        # _also_ in the `nbextension/` namespace\n", "        require=\"my_fancy_module/index\")]\n", "\n", "def load_jupyter_server_extension(nbapp):\n", "    nbapp.log.info(\"my module enabled!\")\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“### Install and enable the server extension and nbextensionn”, “n”, “The user can install and enable the extensions with the following set of commands:n”, “`\n", "jupyter nbextension install --py my_fancy_module [--sys-prefix|--user]\n", "jupyter nbextension enable --py my_fancy_module [--sys-prefix|--system]\n", "jupyter serverextension enable --py my_fancy_module [--sys-prefix|--system]\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“### Automatically enabling a server extension and nbextensionn”, “> New in Notebook 5.3n”, “n”, “Server extensions and nbextensions can be installed and enabled without any user intervention or post-install scripts beyond <package manager> install <extension package name>

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“In addition to the my_fancy_module file tree, assume:n”, “n”, “`\n", "jupyter-config/\n", "├── jupyter_notebook_config.d/\n", "│   └── my_fancy_module.json\n", "└── nbconfig/\n", "    └── notebook.d/\n", "        └── my_fancy_module.json\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“#### jupyter-config/jupyter_notebook_config.d/my_fancy_module.jsonn”, “`json\n", "{\n", "  \"NotebookApp\": {\n", "    \"nbserver_extensions\": {\n", "      \"my_fancy_module\": true\n", "    }\n", "  }\n", "}\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“#### jupyter-config/nbconfig/notebook.d/my_fancy_module.jsonn”, “`json\n", "{\n", "  \"load_extensions\": {\n", "    \"my_fancy_module/index\": true\n", "  }\n", "}\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“Put all of them in place via:n”, “n”, “#### setup.pyn”, “`python\n", "import setuptools\n", "\n", "setuptools.setup(\n", "    name=\"MyFancyModule\",\n", "    ...\n", "    include_package_data=True,\n", "    data_files=[\n", "        # like `jupyter nbextension install --sys-prefix`\n", "        (\"share/jupyter/nbextensions/my_fancy_module\", [\n", "            \"my_fancy_module/static/index.js\",\n", "        ]),\n", "        # like `jupyter nbextension enable --sys-prefix`\n", "        (\"etc/jupyter/nbconfig/notebook.d\", [\n", "            \"jupyter-config/nbconfig/notebook.d/my_fancy_module.json\"\n", "        ]),\n", "        # like `jupyter serverextension enable --sys-prefix`\n", "        (\"etc/jupyter/jupyter_notebook_config.d\", [\n", "            \"jupyter-config/jupyter_notebook_config.d/my_fancy_module.json\"\n", "        ])\n", "    ],\n", "    ...\n", "    zip_safe=False\n", ")\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“and last, but not least:n”, “n”, “#### MANIFEST.inn”, “`config\n", "recursive-include jupyter-config *.json\n", "recursive-include my_fancy_module/static *.js\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“As most package managers will only modify their environment, the eventual configuration will be as if the user had typed:n”, “`\n", "jupyter nbextension install --py my_fancy_module --sys-prefix\n", "jupyter nbextension enable --py my_fancy_module --sys-prefix\n", "jupyter serverextension enable --py my_fancy_module --sys-prefix\n", "`n”, “n”, “If a user manually `disable`s an extension, that configuration will override the bundled package configuration.”

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“#### When automagical install failsn”, “Note this can still fail in certain situations with pip, requiring manual use of install and enable commands.n”, “n”, “Non-python-specific package managers (e.g. conda, apt) may choose not to implement the above behavior at the setup.py level, having more ways to put data files in various places at build time.”

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“## Example - Bundler extension”

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“### Creating a Python package with a bundlerextensionn”, “n”, “Here is a bundler extension that adds a Download as -> Notebook Tarball (tar.gz) option to the notebook File menu. It assumes this directory structure:n”, “n”, “`\n", "- setup.py\n", "- MANIFEST.in\n", "- my_tarball_bundler/\n", "  - __init__.py\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“### Defining the bundler extensionn”, “n”, “This example shows that the bundler extension and its bundle function are defined in the __init__.py file.n”, “n”, “#### my_tarball_bundler/__init__.pyn”, “n”, “`python\n", "import tarfile\n", "import io\n", "import os\n", "import nbformat\n", "\n", "def _jupyter_bundlerextension_paths():\n", "    \"\"\"Declare bundler extensions provided by this package.\"\"\"\n", "    return [{\n", "        # unique bundler name\n", "        \"name\": \"tarball_bundler\",\n", "        # module containing bundle function\n", "        \"module_name\": \"my_tarball_bundler\",\n", "        # human-readable menu item label\n", "        \"label\" : \"Notebook Tarball (tar.gz)\",\n", "        # group under 'deploy' or 'download' menu\n", "        \"group\" : \"download\",\n", "    }]\n", "\n", "\n", "def bundle(handler, model):\n", "    \"\"\"Create a compressed tarball containing the notebook document.\n", "    \n", "    Parameters\n", "    ----------\n", "    handler : tornado.web.RequestHandler\n", "        Handler that serviced the bundle request\n", "    model : dict\n", "        Notebook model from the configured ContentManager\n", "    \"\"\"\n", "    notebook_filename = model['name']\n", "    notebook_content = nbformat.writes(model['content']).encode('utf-8')\n", "    notebook_name = os.path.splitext(notebook_filename)[0]\n", "    tar_filename = '{}.tar.gz'.format(notebook_name)\n", "    \n", "    info = tarfile.TarInfo(notebook_filename)\n", "    info.size = len(notebook_content)\n", "\n", "    with io.BytesIO() as tar_buffer:\n", "        with tarfile.open(tar_filename, \"w:gz\", fileobj=tar_buffer) as tar:\n", "            tar.addfile(info, io.BytesIO(notebook_content))\n", "        \n", "        # Set headers to trigger browser download\n", "        handler.set_header('Content-Disposition',\n", "                           'attachment; filename=\"{}\"'.format(tar_filename))\n", "        handler.set_header('Content-Type', 'application/gzip')\n", "                \n", "        # Return the buffer value as the response\n", "        handler.finish(tar_buffer.getvalue())\n", "`

]

}, {

“cell_type”: “markdown”, “metadata”: {}, “source”: [

“See [Extending the Notebook](../../extending/index.rst) for more documentation about writing nbextensions, server extensions, and bundler extensions.”

]

}

], “metadata”: {

“kernelspec”: {

“display_name”: “Python 3”, “language”: “python”, “name”: “python3”

}, “language_info”: {

“codemirror_mode”: {

“name”: “ipython”, “version”: 3

}, “file_extension”: “.py”, “mimetype”: “text/x-python”, “name”: “python”, “nbconvert_exporter”: “python”, “pygments_lexer”: “ipython3”, “version”: “3.7.2”

}

}, “nbformat”: 4, “nbformat_minor”: 1

}