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)[source]

Bases: object

Utility to manage SageMath kernels and extensions.

INPUT:

  • prefix – (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

>>> from sage.all import *
>>> from sage.repl.ipython_kernel.install import SageKernelSpec
>>> prefix = tmp_dir()
>>> spec = SageKernelSpec(prefix=prefix)
>>> spec._display_name    # random output
'SageMath 6.9'
>>> spec.kernel_dir == SageKernelSpec(prefix=prefix).kernel_dir
True
classmethod check()[source]

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

>>> from sage.all import *
>>> from sage.repl.ipython_kernel.install import SageKernelSpec
>>> SageKernelSpec.check()  # random
classmethod identifier()[source]

Internal identifier for the SageMath kernel.

OUTPUT: the string 'sagemath'

EXAMPLES:

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

>>> from sage.all import *
>>> from sage.repl.ipython_kernel.install import SageKernelSpec
>>> SageKernelSpec.identifier()
'sagemath'
kernel_spec()[source]

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'}

>>> from sage.all import *
>>> from sage.repl.ipython_kernel.install import SageKernelSpec
>>> spec = SageKernelSpec(prefix=tmp_dir())
>>> 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']

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

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())

>>> from sage.all import *
>>> from sage.repl.ipython_kernel.install import SageKernelSpec
>>> SageKernelSpec.update(prefix=tmp_dir())
use_local_threejs()[source]

Symlink threejs to the Jupyter notebook.

EXAMPLES:

sage: # needs threejs
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

>>> from sage.all import *
>>> # needs threejs
>>> from sage.repl.ipython_kernel.install import SageKernelSpec
>>> spec = SageKernelSpec(prefix=tmp_dir())
>>> spec.use_local_threejs()
>>> threejs = os.path.join(spec.nbextensions_dir, 'threejs-sage')
>>> os.path.isdir(threejs)
True
sage.repl.ipython_kernel.install.have_prerequisites(debug=True)[source]

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 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

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