Copyright	(c) Andrew Gibiansky, 2016
License	MIT
Maintainer	andrew.gibiansky@gmail.com
Stability	stable
Portability	POSIX
Safe Haskell	None
Language	Haskell2010

Jupyter.Install.Internal

Description

This module exposes the internal implementation for Jupyter.Install. For user-facing documentation, please check out Jupyter.Install instead.

Synopsis

Documentation

data Kernelspec Source

A kernelspec is a description of a kernel which tells the Jupyter command-line application how to install the kernel and tells the frontends how to invoke the kernel (command line flags, environment, etc).

More documentation about kernelspecs is located in the official documentation.

Constructors

Kernelspec

Fields

kernelspecDisplayName :: Text

Name for the kernel to be shown in frontends, e.g. "Haskell".

kernelspecLanguage :: Text

Language name for the kernel, used to refer to this kernel (in command-line arguments, URLs, etc), e.g. "haskell".

kernelspecCommand :: FilePath -> FilePath -> [String]

How to invoke the kernel. Given the path to the currently running executable and connection file, this function should return the full command to invoke the kernel. For example:

\exe connectionFile -> [exe, "kernel", "--debug", "--connection-file", connectionFile]

kernelspecJsFile :: Maybe FilePath

(optional) path to a Javascript file (kernel.js) to provide to the Jupyter notebook. This file is loaded upon notebook startup.

kernelspecLogoFile :: Maybe FilePath

(optional) path to a 64x64 PNG file to display as the kernel logo in the notebook.

kernelspecEnv :: Map Text Text

Additional environment variables to set when invoking the kernel. If no additional environment variables are required, pass fromList [] or mempty.

data InstallResult Source

Whether the installation was successful.

Constructors

InstallSuccessful	Kernelspec installation was successful.
InstallFailed Text	Kernelspec installation failed, with the reason for failure provided.

Instances

Eq InstallResult Source
Ord InstallResult Source
Show InstallResult Source

data InstallUser Source

Whether to install the kernel globally or just for the current user.

This corresponds to the --user flag for jupyter kernelspec install.

Constructors

InstallLocal	Install this kernel just for this user.
InstallGlobal	Install this kernel globally.

Instances

Eq InstallUser Source
Ord InstallUser Source
Show InstallUser Source

newtype JupyterKernelspecException Source

An exception type for expected exceptions whenever the jupyter kernelspec command is used.

Constructors

JupyterKernelspecException Text

Instances

Eq JupyterKernelspecException Source
Ord JupyterKernelspecException Source
Show JupyterKernelspecException Source
Exception JupyterKernelspecException Source	`JupyterKernelspecException`s can be thrown when an expected failure occurs during `jupyter kernelspec` command invocation.

data JupyterVersion Source

Version of Jupyter currently running, detected by running jupyter --version.

When a version number is not present it is assumed to be zero, so 4.1 equivalent to 4.1.0.

Constructors

JupyterVersion
Fields versionMajor :: Int Major version number. versionMinor :: Int Minor version number. versionPatch :: Int Patch version number.

Instances

Eq JupyterVersion Source
Ord JupyterVersion Source
Show JupyterVersion Source

showVersion :: JupyterVersion -> String Source

Convert a JupyterVersion to its original displayed form.

>>> showVersion (JupyterVersion 4 1 1)
"4.1.1"

installKernel Source

Arguments

:: InstallUser	Whether the kernel should be installed for only the current user (with `--user`) or globally
-> Kernelspec	The kernelspec to install
-> IO InstallResult	Installation result, potentially with a friendly error message

Install a Kernelspec using jupyter kernelspec install.

This function expects the jupyter command to be on the user's PATH, and will fail if the jupyter command is either unavailable or is a version incompatible with this library.

More documentation about kernelspecs is located in the Jupyter documentation and by running jupyter kernelspec install --help.

installFailed :: String -> IO a Source

Throw a JupyterKernelspecException with a given error message.

which :: FilePath -> IO FilePath Source

Determine the absolute path to an executable on the PATH.

Throws a JupyterKernelspecException if the the executable cannot be found.

verifyJupyterCommand :: FilePath -> IO () Source

Verify that a proper version of Jupyter is installed.

Throws a JupyterKernelspecException if jupyter is not present, is an incompatible version, or otherwise cannot be used with this library.

runJupyterCommand :: FilePath -> [String] -> IO String Source

Run a jupyter subcommand with no standard input.

Throws a JupyterKernelspecException if the command cannot be run or returns a non-zero exit code.

jupyterVersionSupported :: JupyterVersion -> Bool Source

Is this Jupyter version supported?

prepareKernelspecDirectory :: Kernelspec -> FilePath -> IO () Source

Given a directory, populate it with all necessary files to run jupyter kernelspec install.

Currently created files include: * kernel.js: (optional) Javascript to include in the notebook frontend. * logo-64x64.png: (optional) Small logo PNG to include in the notebook frontend UI. * kernel.json: (required) JSON file containing kernel invocation command and other metadata.

The passed in directory is created and should not exist; if it already exists, it will be deleted.

installKernelspec Source

Arguments

:: InstallUser	Whether this kernel should be installed with or without `--user`
-> FilePath	Path to the `jupyter` executable
-> Kernelspec	Kernelspec to install
-> IO ()

Install a kernelspec using jupyter kernelspec install.

Throws a JupyterKernelspecException on failure.

parseVersion :: String -> Maybe JupyterVersion Source

Parse a Jupyter version string into a list of integers.

>>> parseVersion "4.1.3\n"
Just (JupyterVersion 4 1 3)

>>> parseVersion "XYZ"
Nothing

If minor or patch versions are unavailable, they are assumed to be zero:

>>> parseVersion "4.1"
Just (JupyterVersion 4 1 0)

>>> parseVersion "4"
Just (JupyterVersion 4 0 0)

findKernel :: Text -> IO (Maybe Kernelspec) Source

Find the kernelspec for a kernel with a given language name.

If no such kernel exists, then Nothing is returned. If an error occurs while searching for Jupyter kernels, a JupyterKernelspecException is thrown.

findKernels :: IO [Kernelspec] Source

Find all kernelspecs that the Jupyter installation is aware of, using the jupyter kernelspec list command.

If an error occurs while searching for Jupyter kernels, a JupyterKernelspecException is thrown.

findKernelsInternal :: IO Kernelspecs Source

Get all the installed kernelspecs using jupyter kernelspec list --json.

These kernelspecs must be passed through checkKernelspecFiles before being returned to the user.

checkKernelspecFiles :: Kernelspec -> IO Kernelspec Source

Kernelspecs can refer to files such as kernel.js and logo-64x64.png. Check whether the kernelspec refers to that file; if it does, check that the file exists. If the file doesn't exist, then remove it from the kernelspec.

newtype Kernelspecs Source

A list of kernelspecs, obtained by running jupyter kernelspec list --json.

The list contains the name of the kernelspec mapped to the kernelspec itself.

Constructors

Kernelspecs (Map Text Kernelspec)

Instances

FromJSON Kernelspecs Source

Parse the output of jupyter kernelspec list --json.

accumKernelspecs Source

Arguments

:: Map Text Kernelspec	Previously seen kernelspecs
-> (Text, Value)	Kernelspec name and JSON value for it
-> Parser (Map Text Kernelspec)	Map with old kernelspecs and parsed new one

Collect all kernelspecs from jupyter kernelspec list --json into a single map.

parseKernelspec :: Value -> Parser Kernelspec Source

Parse a JSON Value into a Kernelspec.