update installation to use jupyter-packaging

should install/enable all extensions at install time

no longer need `ipcluster nbextension` entrypoint, but it's still there

Author: minrk

CONTRIBUTING.md

@@ -1,3 +1,44 @@
 # Contributing
 
-We follow the [IPython Contributing Guide](https://github.com/ipython/ipython/blob/master/CONTRIBUTING.md).
+We follow the [Jupyter Contributing Guide](https://jupyter.readthedocs.io/en/latest/contributing/content-contributor.html).
+
+Make sure to follow the [Jupyter Code of Conduct](https://jupyter.org/conduct/).
+
+## Development install
+
+A basic development install of IPython parallel
+is the same as almost all Python packages:
+
+```bash
+pip install -e .
+```
+
+To enable the server extension from a development install:
+
+```bash
+# for jupyterlab
+jupyter server extension enable --sys-prefix ipyparallel
+# for classic notebook
+jupyter serverextension enable --sys-prefix ipyparallel
+```
+
+As described in the [JupyterLab documentation](https://jupyterlab.readthedocs.io/en/stable/extension/extension_dev.html#developing-a-prebuilt-extension)
+for a development install of the jupyterlab extension you can run the following in this directory:
+
+```bash
+jlpm  # Install npm package dependencies
+jlpm build  # Compile the TypeScript sources to Javascript
+jupyter labextension develop . --overwrite  # Install the current directory as an extension
+```
+
+If you are working on the lab extension,
+you can run jupyterlab in dev mode to always rebuild and reload your extensions.
+In two terminals, run:
+
+```bash
+[term 1] $ jlpm watch
+[term 2] $ jupyter lab --extensions-in-dev-mode
+```
+
+You should then be able to refresh the JupyterLab page
+and it will pick up the changes to the extension as you work.

MANIFEST.in

@@ -2,8 +2,18 @@ include COPYING.md
 include CONTRIBUTING.md
 include README.md
 
+# enable-at-install config
 graft etc
 
+# lab extension
+graft lab
+prune lab/lib
+include install.json
+include package*.json
+include tsconfig*.json
+graft ipyparallel/labextension
+
+
 # Documentation
 graft docs
 
@@ -19,3 +29,4 @@ global-exclude *.pyc
 global-exclude *.pyo
 global-exclude .git
 global-exclude .ipynb_checkpoints
+global-exclude .DS_Store

README.md

@@ -1,37 +1,21 @@
 # Interactive Parallel Computing with IPython
 
-ipyparallel is the new home of IPython.parallel. ipyparallel is a Python package and collection of CLI scripts for controlling clusters for Jupyter.
+IPython Parallel (`ipyparallel`) is a Python package and collection of CLI scripts for controlling clusters of IPython processes, built on the Jupyter protocol.
 
-ipyparallel contains the following CLI scripts:
+IPython Parallel provides the following commands:
 
-- ipcluster - start/stop a cluster
-- ipcontroller - start a scheduler
+- ipcluster - start/stop/list clusters
+- ipcontroller - start a controller
 - ipengine - start an engine
 
 ## Install
 
-Install ipyparallel:
+Install IPython Parallel:
 
     pip install ipyparallel
 
-To enable the `IPython Clusters` tab in Jupyter Notebook:
-
-    ipcluster nbextension enable
-
-To disable it again:
-
-    ipcluster nbextension disable
-
-See the [documentation on configuring the notebook server](https://jupyter-notebook.readthedocs.io/en/latest/public_server.html)
-to find your config or setup your initial `jupyter_notebook_config.py`.
-
-### JupyterHub Install
-
-To install for all users on JupyterHub, as root:
-
-    jupyter nbextension install --sys-prefix --py ipyparallel
-    jupyter nbextension enable --sys-prefix --py ipyparallel
-    jupyter serverextension enable --sys-prefix --py ipyparallel
+This will install and enable the IPython Parallel extensions
+for Jupyter Notebook and (as of 7.0) Jupyter Lab 3.0.
 
 ## Run
 
@@ -45,9 +29,10 @@ Use it from Python:
 import os
 import ipyparallel as ipp
 
-rc = ipp.Client()
-ar = rc[:].apply_async(os.getpid)
-pid_map = ar.get_dict()
+cluster = ipp.Cluster(n=4)
+with cluster as rc:
+    ar = rc[:].apply_async(os.getpid)
+    pid_map = ar.get_dict()
 ```
 
 See [the docs](https://ipyparallel.readthedocs.io) for more info.

etc/ipyparallel-serverextension.json

@@ -1,7 +1,7 @@
 {
   "NotebookApp": {
     "nbserver_extensions": {
-      "ipyparallel.nbextension": true
+      "ipyparallel": true
     }
   }
 }

jupyter-config/jupyter_notebook_config.d/ipyparallel.json renamed to etc/jupyter/jupyter_notebook_config.d/ipyparallel.json

@@ -1,7 +1,7 @@
 {
   "ServerApp": {
     "jpserver_extensions": {
-      "ipyparallel.nbextension": true
+      "ipyparallel": true
     }
   }
 }

jupyter-config/jupyter_server_config.d/ipyparallel.json renamed to etc/jupyter/jupyter_server_config.d/ipyparallel.json

@@ -50,7 +50,7 @@ def bind_kernel(**kwargs):
         else:
             return app.bind_kernel(**kwargs)
 
-    raise RuntimeError("bind_kernel be called from an IPEngine instance")
+    raise RuntimeError("bind_kernel must be called from an IPEngine instance")
 
 
 def register_joblib_backend(name='ipyparallel', make_default=False):
@@ -62,7 +62,7 @@ def register_joblib_backend(name='ipyparallel', make_default=False):
 
 # nbextension installation (requires notebook ≥ 4.2)
 def _jupyter_server_extension_paths():
-    return [{'module': 'ipyparallel.nbextension'}]
+    return [{'module': 'ipyparallel'}]
 
 
 def _jupyter_nbextension_paths():
@@ -83,3 +83,19 @@ def _jupyter_labextension_paths():
             "dest": "ipyparallel-labextension",
         }
     ]
+
+
+def _load_jupyter_server_extension(app):
+    """Load the server extension"""
+    # localte the appropriate APIHandler base class before importing our handler classes
+    from .nbextension.base import get_api_handler
+
+    get_api_handler(app)
+
+    from .nbextension.handlers import load_jupyter_server_extension
+
+    return load_jupyter_server_extension(app)
+
+
+# backward-compat
+load_jupyter_server_extension = _load_jupyter_server_extension

etc/ipyparallel-nbextension.json renamed to etc/jupyter/nbconfig/tree.d/ipyparallel.json

@@ -1 +1,12 @@
-from .handlers import load_jupyter_server_extension
+"""Jupyter server extension(s)"""
+import warnings
+
+
+def load_jupyter_server_extension(app):
+    warnings.warn(
+        "Using ipyparallel.nbextension as server extension is deprecated in IPython Parallel 7.0. Use top-level ipyparallel.",
+        DeprecationWarning,
+    )
+    from ipyparallel import _load_jupyter_server_extension
+
+    return _load_jupyter_server_extension(app)

ipyparallel/__init__.py

@@ -0,0 +1,48 @@
+"""Place to put the base Handler"""
+import warnings
+from functools import lru_cache
+
+_APIHandler = None
+
+
+@lru_cache()
+def _guess_api_handler():
+    """Fallback to guess API handler by availability"""
+    try:
+        from notebook.base.handlers import APIHandler
+    except ImportError:
+        from jupyter_server.base.handlers import APIHandler
+    global _APIHandler
+    _APIHandler = APIHandler
+    return _APIHandler
+
+
+def get_api_handler(app=None):
+    """Get the base APIHandler class to use
+
+    Inferred from app class (either jupyter_server or notebook app)
+    """
+    global _APIHandler
+    if _APIHandler is not None:
+        return _APIHandler
+    if app is None:
+        warnings.warn(
+            "Guessing base APIHandler class. Specify an app to ensure the right APIHandler is used.",
+            stacklevel=2,
+        )
+        return _guess_api_handler()
+
+    top_modules = {cls.__module__.split(".", 1)[0] for cls in app.__class__.mro()}
+    if "jupyter_server" in top_modules:
+        from jupyter_server.base.handlers import APIHandler
+
+        _APIHandler = APIHandler
+        return APIHandler
+    if "notebook" in top_modules:
+        from notebook.base.handlers import APIHandler
+
+        _APIHandler = APIHandler
+        return APIHandler
+
+    warnings.warn(f"Failed to detect base APIHandler class for {app}.", stacklevel=2)
+    return _guess_api_handler()