Installing the SageMath Jupyter Kernel and Extensions#

Kernels have to register themselves with Jupyter so that they appear in the Jupyter notebook’s kernel drop-down. This is done by SageKernelSpec.

Note

The doctests in this module run in a temporary directory as the involved directories might be different during runs of the tests and actual installation and because we might be lacking write permission to places such as /usr/share.

class sage.repl.ipython_kernel.install.SageKernelSpec(prefix=None)#

Bases: object

Utility to manage SageMath kernels and extensions

INPUT:

  • prefix – (optional, default: sys.prefix) directory for the installation prefix

EXAMPLES:

sage: from sage.repl.ipython_kernel.install import SageKernelSpec
sage: prefix = tmp_dir()
sage: spec = SageKernelSpec(prefix=prefix)
sage: spec._display_name    # random output
'SageMath 6.9'
sage: spec.kernel_dir == SageKernelSpec(prefix=prefix).kernel_dir
True
classmethod check()#

Check that the SageMath kernel can be discovered by its name (sagemath).

This method issues a warning if it cannot – either because it is not installed, or it is shadowed by a different kernel of this name, or Jupyter is misconfigured in a different way.

EXAMPLES:

sage: from sage.repl.ipython_kernel.install import SageKernelSpec
sage: SageKernelSpec.check()  # random
classmethod identifier()#

Internal identifier for the SageMath kernel

OUTPUT: the string "sagemath".

EXAMPLES:

sage: from sage.repl.ipython_kernel.install import SageKernelSpec
sage: SageKernelSpec.identifier()
'sagemath'
kernel_spec()#

Return the kernel spec as Python dictionary

OUTPUT:

A dictionary. See the Jupyter documentation for details.

EXAMPLES:

sage: from sage.repl.ipython_kernel.install import SageKernelSpec
sage: spec = SageKernelSpec(prefix=tmp_dir())
sage: spec.kernel_spec()
{'argv': ..., 'display_name': 'SageMath ...', 'language': 'sage'}

Symlink src to dst

This is not an atomic operation.

Already-existing symlinks will be deleted, already existing non-empty directories will be kept.

EXAMPLES:

sage: from sage.repl.ipython_kernel.install import SageKernelSpec
sage: spec = SageKernelSpec(prefix=tmp_dir())
sage: path = tmp_dir()
sage: spec.symlink(os.path.join(path, 'a'), os.path.join(path, 'b'))
sage: os.listdir(path)
['b']
classmethod update(*args, **kwds)#

Configure the Jupyter notebook for the SageMath kernel

This method does everything necessary to use the SageMath kernel, you should never need to call any of the other methods directly.

EXAMPLES:

sage: from sage.repl.ipython_kernel.install import SageKernelSpec
sage: SageKernelSpec.update(prefix=tmp_dir())
use_local_threejs()#

Symlink threejs to the Jupyter notebook.

EXAMPLES:

sage: from sage.repl.ipython_kernel.install import SageKernelSpec
sage: spec = SageKernelSpec(prefix=tmp_dir())
sage: spec.use_local_threejs()
sage: threejs = os.path.join(spec.nbextensions_dir, 'threejs-sage')
sage: os.path.isdir(threejs)
True
sage.repl.ipython_kernel.install.have_prerequisites(debug=True)#

Check that we have all prerequisites to run the Jupyter notebook.

In particular, the Jupyter notebook requires OpenSSL whether or not you are using https. See github issue #17318.

INPUT:

debug – boolean (default: True). Whether to print debug information in case that prerequisites are missing.

OUTPUT:

Boolean.

EXAMPLES:

sage: from sage.repl.ipython_kernel.install import have_prerequisites
sage: have_prerequisites(debug=False) in [True, False]
True