Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
90 commits
Select commit Hold shift + click to select a range
142ae51
Adding prototype nbextensions argument to NotebookApp
ellisonbg Dec 17, 2015
49b7b8c
This part of things is working.
ellisonbg Dec 17, 2015
b208d29
More changes to the nbextensions.
ellisonbg Dec 18, 2015
7705bfd
New approach working, old approach gone.
ellisonbg Dec 18, 2015
de42e6d
Working on logging.
ellisonbg Dec 29, 2015
f437042
First iteration on serverextension CLI. List working OK. I have the c…
damianavila Feb 10, 2016
067e452
--py and --python should work
jdfreder Feb 24, 2016
a92244b
Format list command output nicely
jdfreder Feb 24, 2016
ea95f41
Add common, terminal, and edit extension points
jdfreder Feb 24, 2016
13905d5
Remove unused nbextensions_* variables
jdfreder Feb 24, 2016
049d00a
Remove json dependency
jdfreder Feb 24, 2016
9d6b048
Add uninstall command
jdfreder Feb 24, 2016
6cc8145
Simplify mappings
jdfreder Feb 24, 2016
fd2fda7
Address additional comments
jdfreder Feb 24, 2016
8d2f8c1
Some more updates to nbext and serverext
jdfreder Feb 26, 2016
e8dd95f
Address review comments
jdfreder Feb 26, 2016
24d95a5
Server extensions dict,
jdfreder Feb 26, 2016
a205169
Remove line that was causing the tests to fail
jdfreder Feb 26, 2016
54dd9c5
Squash some bugs and write unit tests
jdfreder Feb 26, 2016
b5c4e98
Get the serverextensions stuff to work and add unit tests for it
jdfreder Feb 26, 2016
29279e2
Fix typo
jdfreder Feb 26, 2016
fa39945
Fix poor logic in manager.py
jdfreder Feb 26, 2016
50d3452
Use better ansi codes
jdfreder Feb 26, 2016
166afb9
Clarify doc strings
jdfreder Feb 27, 2016
6288b7a
@carreau's comments
jdfreder Feb 29, 2016
d87d26b
Fix undefined variables
Carreau Feb 29, 2016
eb87e16
Minor style fixes
Carreau Feb 29, 2016
287e4a9
Combine logic
Carreau Feb 29, 2016
63d6dbd
remove redundant defaults
Carreau Feb 29, 2016
0b2b908
Fix dict.update does nto return a copy
Carreau Feb 29, 2016
976687e
remove unused import
Carreau Feb 29, 2016
13c20df
Merge pull request #6 from Carreau/fix-jon
jdfreder Feb 29, 2016
14b1224
unbreak API
Carreau Feb 29, 2016
5e49c50
revert space changes
Carreau Feb 29, 2016
67ff596
make the ENABLE/DISABLE markers ASCII
Carreau Feb 29, 2016
0ac9277
Add deprecation warning and unbreak API
Carreau Feb 29, 2016
4959581
fix some tests.
Carreau Feb 29, 2016
174d772
remove verbosity
Carreau Feb 29, 2016
4ce3f00
only log if loggable
Carreau Feb 29, 2016
32b5ba3
Log only if logger defined
Carreau Feb 29, 2016
b8e1e8d
Merge pull request #7 from Carreau/fix-jon
jdfreder Feb 29, 2016
89f1226
Remove extra junk from logging output
jdfreder Mar 1, 2016
6b4790b
Use +/- instead of O/X or T/F
jdfreder Mar 1, 2016
295e0a5
Use enabled/disabled
jdfreder Mar 1, 2016
2d30b4d
fixing log output... could be more verbose
Mar 7, 2016
ce4e3fc
cleaning up references to nbextensions in serverextensions
Mar 7, 2016
2fc9dbe
Merge pull request #8 from bollwyvl/nbext-pain-logger-args
jdfreder Mar 7, 2016
2b43653
actually, should be public
Mar 7, 2016
5b6eb13
Merge pull request #9 from bollwyvl/nbext-pain-ceci-nest-pas-une-nbex…
jdfreder Mar 7, 2016
540a143
Grammar cc @bollwyvl
jdfreder Mar 7, 2016
35f8889
s/require/module for serverextension cc @minrk
jdfreder Mar 7, 2016
071e926
adding initial post-install validation
Mar 9, 2016
f3074fd
logging, removing redundant implementations
bollwyvl Mar 9, 2016
9bef5c1
serverextension docstrings
bollwyvl Mar 10, 2016
7859e9d
adding more tests for validation, cleaning up validation return values
bollwyvl Mar 10, 2016
fe9c33d
add rudimentary documentation of server spec (in private function, bah)
bollwyvl Mar 10, 2016
7772598
adding test for non-python nbextension
bollwyvl Mar 10, 2016
16b5248
Merge pull request #10 from bollwyvl/nbext-pain-validation
jdfreder Mar 10, 2016
e39a702
documenting public members of nbextension
bollwyvl Mar 10, 2016
a17b702
docstrings for everyone :tada:
bollwyvl Mar 10, 2016
e48015e
Merge pull request #11 from bollwyvl/nbext-pain-validation
jdfreder Mar 10, 2016
d54ed56
initial crack at documentation for new-wave extension stuff
bollwyvl Mar 10, 2016
053c83c
Merge pull request #12 from bollwyvl/nbext-pain-ipynb-doc
jdfreder Mar 10, 2016
6f72d61
Normalize path to fix symlink creation
malev Mar 11, 2016
64c0e42
Merge pull request #13 from malev/fix-symlink
jdfreder Mar 14, 2016
8b20257
Edit documentation notebook
willingc Mar 10, 2016
33a58c8
Fix @nbollweg comments
willingc Mar 14, 2016
4db4691
Merge pull request #14 from willingc/update-nb
jdfreder Mar 14, 2016
915920a
Fix typo found by @minrk
willingc Mar 15, 2016
eec61bb
add message for install
Mar 15, 2016
bb18735
move logging to app for making better args
Mar 15, 2016
7538681
Update the table of contents
willingc Mar 16, 2016
4d515da
Merge pull request #16 from bollwyvl/nbext-pain-install-msg
jdfreder Mar 16, 2016
d6ac30e
Merge pull request #17 from willingc/update-contents
jdfreder Mar 16, 2016
6c28693
Merge pull request #15 from willingc/update-nb
jdfreder Mar 16, 2016
19c65b6
changing extension enable/disable configuration default to --user
Mar 17, 2016
a0fd730
fixing doc
Mar 17, 2016
d4cc42d
Merge pull request #18 from bollwyvl/nbext-pain-enable-user
jdfreder Mar 17, 2016
684fa5d
restoring --debug and --log-level
Mar 17, 2016
febb762
unicode everywhere for logging
Mar 17, 2016
e617cd2
Merge pull request #21 from bollwyvl/nbext-pain-validate-unicode
ellisonbg Mar 17, 2016
f3873f0
use import_item to allow any module to provide an nbextension
minrk Mar 17, 2016
75292d3
Merge pull request #19 from bollwyvl/nbext-pain-restore-debug
ellisonbg Mar 17, 2016
74ee26d
Merge pull request #22 from minrk/nbextension-command
jdfreder Mar 18, 2016
c72d93e
adding sys_prefix override of user
Mar 21, 2016
f26e0b1
Merge pull request #23 from bollwyvl/nbext-pain-enable-user-again
jdfreder Mar 21, 2016
d0e0ddf
use print for nbextension list output
minrk Mar 24, 2016
1287c86
Remove incorrect mention of `--user` in docs
minrk Mar 24, 2016
6371f8a
add `--system` flag for enable/disable
minrk Mar 24, 2016
53ce313
Merge pull request #24 from minrk/nbextensions
jdfreder Mar 24, 2016
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,280 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Distributing Jupyter Extensions as Python Packages"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Overview\n",
"### 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 extension\n",
" - a single JS file, or directory of JavaScript, Cascading StyleSheets, etc. that contain at\n",
" minimum a JavaScript module packaged as an\n",
" [AMD modules](https://en.wikipedia.org/wiki/Asynchronous_module_definition)\n",
" that exports a function `load_ipython_extension`\n",
"- server extension: an importable Python module\n",
" - that implements `load_jupyter_server_extension`"
]
},
{
"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. This makes installing the package of extensions easier and less error-prone for the user. "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Installation of Jupyter Extensions\n",
"### Install a Python package containing Jupyter Extensions\n",
"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": [
"### Enable a Server Extension\n",
"\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 assets\n",
"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 or server extension. 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",
"```"
]
},
{
"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](http://the-hitchhikers-guide-to-packaging.readthedocs.org/en/latest/quickstart.html)\n",
"- [Repository Structure and Python](http://www.kennethreitz.org/essays/repository-structure-and-python) by Kenneth Reitz\n",
"\n",
"> How you distribute them, too, is important:\n",
"- [Packaging and Distributing Projects](http://python-packaging-user-guide.readthedocs.org/en/latest/distributing/)\n",
"- [conda: Building packages](http://conda.pydata.org/docs/building/build.html)\n",
"\n",
"> Here are some tools to get you started:\n",
"- [generator-nbextension](https://github.com/Anaconda-Server/generator-nbextension)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Example - Server extension"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Creating a Python package with a server extension\n",
"\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 extension\n",
"This example shows that the server extension and its `load_jupyter_server_extension` function are defined in the `__init__.py` file.\n",
"#### `my_module/__init__.py`\n",
"\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 extension\n",
"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 nbextension\n",
"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 nbextension\n",
"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_path` for the nbextension.\n",
"\n",
"#### `my_fancy_module/__init__.py`\n",
"\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 nbextension\n",
"\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",
"```"
]
}
],
"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.5.1"
}
},
"nbformat": 4,
"nbformat_minor": 0
}
14 changes: 10 additions & 4 deletions docs/source/extending/frontend_extensions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -202,10 +202,12 @@ the prefix. For the action name, the following guidelines should be considered:
Installing and enabling extensions
----------------------------------

You can install your nbextension with the command:
You can install your nbextension with the command::

jupyter nbextension install path/to/my_extension/
jupyter nbextension install path/to/my_extension/ [--user|--sys-prefix]

The default installation is system-wide. You can use ``--user`` to do a per-user installation,
or ``--sys-prefix`` to install to Python's prefix (e.g. in a virtual or conda environment).
Where my_extension is the directory containing the Javascript files.
This will copy it to a Jupyter data directory (the exact location is platform
dependent - see :ref:`jupyter_path`).
Expand All @@ -214,11 +216,15 @@ For development, you can use the ``--symlink`` flag to symlink your extension
rather than copying it, so there's no need to reinstall after changes.

To use your extension, you'll also need to **enable** it, which tells the
notebook interface to load it. You can do that with another command:
notebook interface to load it. You can do that with another command::

jupyter nbextension enable my_extension/main
jupyter nbextension enable my_extension/main [--sys-prefix]

The argument refers to the Javascript module containing your
``load_ipython_extension`` function, which is ``my_extension/main.js`` in this
example. There is a corresponding ``disable`` command to stop using an
extension without uninstalling it.

.. versionchanged:: 4.2

Added ``--sys-prefix`` argument
5 changes: 3 additions & 2 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,9 @@ The Jupyter notebook
public_server
security
frontend_config
extending/index

examples/Notebook/rstversions/Distributing Jupyter Extensions as Python Packages.rst
extending/index.rst

.. toctree::
:maxdepth: 1
:caption: Developer Documentation
Expand Down
Loading