Installing the SageMath Jupyter Kernel and Extensions - The Sage Command Line

Skip to content
Back to top
View this page
Edit this page

# 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` – (default: `sys.prefix`) directory for the installation prefix

  EXAMPLES:

  Sage

      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

  Python

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

    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

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

    Python

        >>> from sage.all import *
        >>> from sage.repl.ipython_kernel.install import SageKernelSpec
        >>> SageKernelSpec.check()  # random

  classmethod identifier()

    Internal identifier for the SageMath kernel.

    OUTPUT: the string `'sagemath'`

    EXAMPLES:

    Sage

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

    Python

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

  kernel_spec()

    Return the kernel spec as Python dictionary.

    OUTPUT: a dictionary; see the Jupyter documentation for details

    EXAMPLES:

    Sage

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

    Python

        >>> 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, dst)

    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

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

    Python

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

    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

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

    Python

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

  use_local_threejs()

    Symlink threejs to the Jupyter notebook.

    EXAMPLES:

    Sage

        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

    Python

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

  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

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

  Python

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