Move jup kernel spec from setup to xonfig; add doc.

Author: Bob Hyman

docs/appimage.rst

@@ -17,7 +17,7 @@ You can get the xonsh AppImage from GitHub and run it on your Linux machine with
 
 If you don't have Python on your host, you may want to get it from AppImage:
 
-.. code-block:: xonsh
+.. code-block:: xonshcon
 
     ./xonsh
     $PATH = [f'{$APPDIR}/usr/bin'] + $PATH

docs/installation.rst

@@ -21,6 +21,7 @@ Xonsh can be installed via package manager, via appimage or just run from a pre-
     appimage
     containers
     editors
+    jupyter
 
 Configuration and Customization
 ================================

docs/jupyter.rst

@@ -6,6 +6,42 @@ Xonsh provides a kernel for Jupyter Notebook and Lab so you can execute xonsh co
 Installation
 -------------
 
-[ed note: this is a stub and the topic is excluded from docs
-till I or someone can get a consistent install procedure to work!]
+Install Jupyter and Xonsh in the same environment, then configure the Xonsh kernel for Jupyter:
+
+.. code-block:: xonshcon
+
+    $ xonfig kernel
+    Installing Jupyter kernel spec:
+      root: None
+      prefix: <env_prefix>
+      as user: False
+
+_<Env_prefix>_ is the path prefix of the Jupyter and Xonsh environment.  ``xonfig kernel --help`` shows options 
+for installing the kernel spec in the user config folder or in a non-standard environment prefix.
+
+You can confirm the status of the installation:
+
+.. code-block:: xonshcon
+
+    $ xonfig info
+    +------------------+-----------------------------------------------------+
+    | xonsh            | 0.9.21                                              |
+    | Git SHA          | d42b4140                                            |
+    
+                   . . . . .
+
+    | on jupyter       | True                                                |
+    | jupyter kernel   | <env_prefix>\share\jupyter\kernels\xonsh            |
+    +------------------+-----------------------------------------------------+
+
+Or:
+
+.. code-block:: xonshcon
+
+    $ jupyter kernelspec list
+    Available kernels:
+      python3    <env_prefix>\share\jupyter\kernels\python3
+      xonsh      <env_prefix>\share\jupyter\kernels\xonsh
+     
+
 

docs/packages.rst

@@ -86,7 +86,7 @@ use the Python ``readline`` module (which reads configuration  file ``.inputrc``
 To ensure xonsh uses ``readline`` even if ``prompt-toolkit`` is installed, configure this in your
 ``.xonshrc`` file:
 
-.. code-block:: xonsh
+.. code-block:: xonshcon
 
     $SHELL_TYPE = 'readline'
 

news/xonfig-kernel.rst

@@ -0,0 +1,27 @@
+**Added:**
+
+* ``xonfig kernel`` new subcommand to generate xonsh kernel spec for jupyter.
+
+**Changed:**
+
+* ``xonfig info`` displays whether jupyter detected in environment and 
+  also path of xonsh jupyter kernel spec, if any.
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* setup no longer (tries to) install jupyter kernel automatically, 
+  user must run ``xonfig kernel`` manually.
+
+**Fixed:**
+
+* Setup wasn't consistently detecting jupyter in environment; ``python setup.py install`` worked, but
+  ``pip install .`` wouldn't (because pip mucks with ``sys.path``), 
+  nor would install from wheel (because it doesn't run ``setup.py``).
+
+**Security:**
+
+* <news item>

setup.py

@@ -8,26 +8,13 @@
 import json
 import subprocess
 
-try:
-    from tempfile import TemporaryDirectory
-except ImportError:
-    pass
-
 from setuptools import setup, find_packages
 from setuptools.command.sdist import sdist
 from setuptools.command.install import install
 from setuptools.command.develop import develop
 from setuptools.command.build_py import build_py
 from setuptools.command.install_scripts import install_scripts
 
-try:
-    from jupyter_client.kernelspec import KernelSpecManager
-
-    HAVE_JUPYTER = True
-except ImportError:
-    HAVE_JUPYTER = False
-
-
 TABLES = [
     "xonsh/lexer_table.py",
     "xonsh/parser_table.py",
@@ -86,50 +73,6 @@ def build_tables():
     sys.path.pop(0)
 
 
-def install_jupyter_hook(prefix=None, root=None):
-    """Make xonsh available as a Jupyter kernel."""
-    if not HAVE_JUPYTER:
-        print(
-            "Could not install Jupyter kernel spec, please install " "Jupyter/IPython."
-        )
-        return
-    spec = {
-        "argv": [
-            sys.executable,
-            "-m",
-            "xonsh.jupyter_kernel",
-            "-f",
-            "{connection_file}",
-        ],
-        "display_name": "Xonsh",
-        "language": "xonsh",
-        "codemirror_mode": "shell",
-    }
-    with TemporaryDirectory() as d:
-        os.chmod(d, 0o755)  # Starts off as 700, not user readable
-        if sys.platform == "win32":
-            # Ensure that conda-build detects the hard coded prefix
-            spec["argv"][0] = spec["argv"][0].replace(os.sep, os.altsep)
-        with open(os.path.join(d, "kernel.json"), "w") as f:
-            json.dump(spec, f, sort_keys=True)
-        if "CONDA_BUILD" in os.environ:
-            prefix = sys.prefix
-            if sys.platform == "win32":
-                prefix = prefix.replace(os.sep, os.altsep)
-        user = "--user" in sys.argv
-        print("Installing Jupyter kernel spec:")
-        print("  root: {0!r}".format(root))
-        print("  prefix: {0!r}".format(prefix))
-        print("  as user: {0}".format(user))
-        if root and prefix:
-            # os.path.join isn't used since prefix is probably absolute
-            prefix = root + prefix
-            print("  combined prefix {0!r}".format(prefix))
-        KernelSpecManager().install_kernel_spec(
-            d, "xonsh", user=user, replace=True, prefix=prefix
-        )
-
-
 def dirty_version():
     """
     If install/sdist is run from a git directory (not a conda install), add
@@ -222,16 +165,6 @@ def run(self):
         amalgamate_source()
         # add dirty version number
         dirty = dirty_version()
-        # install Jupyter hook
-        root = self.root if self.root else None
-        prefix = self.prefix if self.prefix else None
-        try:
-            install_jupyter_hook(prefix=prefix, root=root)
-        except Exception:
-            import traceback
-
-            traceback.print_exc()
-            print("Installing Jupyter hook failed.")
 
         super().run()
         if dirty:
@@ -412,7 +345,7 @@ def main():
         "linux": ["distro"],
         "proctitle": ["setproctitle"],
         "zipapp": ['importlib_resources; python_version < "3.7"'],
-        "full" : ["ptk", "pygments", "distro"]
+        "full": ["ptk", "pygments", "distro"],
     }
     skw["python_requires"] = ">=3.6"
     setup(**skw)

xonsh/xonfig.py

@@ -15,6 +15,8 @@
 import contextlib
 import collections
 
+from tempfile import TemporaryDirectory
+
 from xonsh.ply import ply
 
 import xonsh.wizard as wiz
@@ -141,6 +143,8 @@
     lambda: "source-foreign", bash="source-bash", cmd="source-cmd", zsh="source-zsh"
 )
 
+XONSH_JUPYTER_KERNEL = "xonsh"
+
 
 def _dump_xonfig_foreign_shell(path, value):
     shell = value["shell"]
@@ -523,6 +527,21 @@ def _info(ns):
             ("encoding errors", env.get("XONSH_ENCODING_ERRORS")),
         ]
     )
+    jup_ksm = jup_kernel = None
+    try:
+        from jupyter_client.kernelspec import KernelSpecManager
+
+        jup_ksm = KernelSpecManager()
+        jup_kernel = jup_ksm.find_kernel_specs()[XONSH_JUPYTER_KERNEL]
+    except (ImportError, KeyError):
+        pass
+    data.extend(
+        [
+            ("on jupyter", jup_ksm is not None),
+            ("jupyter kernel", jup_kernel),
+        ]
+    )
+
     formatter = _xonfig_format_json if ns.json else _xonfig_format_human
     s = formatter(data)
     return s
@@ -623,6 +642,53 @@ def _web(args):
     subprocess.run([sys.executable, "-m", "xonsh.webconfig"] + args.orig_args[1:])
 
 
+def _kernel(args):
+    """Make xonsh available as a Jupyter kernel."""
+    try:
+        from jupyter_client.kernelspec import KernelSpecManager
+    except ImportError:
+        raise ImportError("Jupyter not found in current Python environment")
+
+    root = args.root
+    prefix = args.prefix
+    user = args.user
+    spec = {
+        "argv": [
+            sys.executable,
+            "-m",
+            "xonsh.jupyter_kernel",
+            "-f",
+            "{connection_file}",
+        ],
+        "display_name": "Xonsh",
+        "language": "xonsh",
+        "codemirror_mode": "shell",
+    }
+    with TemporaryDirectory() as d:
+        os.chmod(d, 0o755)  # Starts off as 700, not user readable
+        if sys.platform == "win32":
+            # Ensure that conda-build detects the hard coded prefix
+            spec["argv"][0] = spec["argv"][0].replace(os.sep, os.altsep)
+        with open(os.path.join(d, "kernel.json"), "w") as f:
+            json.dump(spec, f, sort_keys=True)
+        if "CONDA_BUILD" in os.environ or "VIRTUAL_ENV" in os.environ:
+            prefix = sys.prefix
+            if sys.platform == "win32":
+                prefix = prefix.replace(os.sep, os.altsep)
+        print("Installing Jupyter kernel spec:")
+        print("  root: {0!r}".format(root))
+        print("  prefix: {0!r}".format(prefix))
+        print("  as user: {0}".format(user))
+        if root and prefix:
+            # os.path.join isn't used since prefix is probably absolute
+            prefix = root + prefix
+            print("  combined prefix {0!r}".format(prefix))
+        KernelSpecManager().install_kernel_spec(
+            d, XONSH_JUPYTER_KERNEL, user=user, prefix=prefix
+        )
+        return 0
+
+
 @functools.lru_cache(1)
 def _xonfig_create_parser():
     p = argparse.ArgumentParser(
@@ -662,6 +728,22 @@ def _xonfig_create_parser():
         "style", nargs="?", default=None, help="style to preview, default: <current>"
     )
     subp.add_parser("tutorial", help="Launch tutorial in browser.")
+    kern = subp.add_parser("kernel", help="Generate xonsh kernel for jupyter.")
+    kern.add_argument(
+        "--user",
+        action="store_true",
+        default=False,
+        help="Install kernel in user config.",
+    )
+    kern.add_argument(
+        "--root",
+        default=None,
+        help="Install relative to this alternate root directory.",
+    )
+    kern.add_argument(
+        "--prefix", default=None, help="Installation prefix for bin, lib, etc."
+    )
+
     return p
 
 
@@ -672,6 +754,7 @@ def _xonfig_create_parser():
     "styles": _styles,
     "colors": _colors,
     "tutorial": _tutorial,
+    "kernel": _kernel,
 }