Display Manager - The Sage Command Line

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

# Display Manager

This is the heart of the rich output system, the display manager arbitrates between

- Backend capabilities: what can be displayed

- Backend preferences: what gives good quality on the backend

- Sage capabilities: every Sage object can only generate certain representations, and

- User preferences: typeset vs. plain text vs. ascii art, etc.

The display manager is a singleton class, Sage always has exactly one instance of it. Use `get_display_manager()` to obtain it.

EXAMPLES:

Sage

    sage: from sage.repl.rich_output import get_display_manager
    sage: dm = get_display_manager();  dm
    The Sage display manager using the doctest backend

Python

    >>> from sage.all import *
    >>> from sage.repl.rich_output import get_display_manager
    >>> dm = get_display_manager();  dm
    The Sage display manager using the doctest backend

exception sage.repl.rich_output.display_manager.DisplayException

  Bases: `Exception`

  Base exception for all rich output-related exceptions.

  EXAMPLES:

  Sage

      sage: from sage.repl.rich_output.display_manager import DisplayException
      sage: raise DisplayException('foo')
      Traceback (most recent call last):
      ...
      DisplayException: foo

  Python

      >>> from sage.all import *
      >>> from sage.repl.rich_output.display_manager import DisplayException
      >>> raise DisplayException('foo')
      Traceback (most recent call last):
      ...
      DisplayException: foo

class sage.repl.rich_output.display_manager.DisplayManager

  Bases: `SageObject`

  The Display Manager.

  Used to decide what kind of rich output is best.

  EXAMPLES:

  Sage

      sage: from sage.repl.rich_output import get_display_manager
      sage: get_display_manager()
      The Sage display manager using the doctest backend

  Python

      >>> from sage.all import *
      >>> from sage.repl.rich_output import get_display_manager
      >>> get_display_manager()
      The Sage display manager using the doctest backend

  check_backend_class(backend_class)

    Check that the current backend is an instance of `backend_class`.

    This is, for example, used by the Sage IPython display formatter to ensure that the IPython backend is in use.

    INPUT:

    - `backend_class` – type of a backend class

    OUTPUT:

    This method returns nothing. A `RuntimeError` is raised if `backend_class` is not the type of the current backend.

    EXAMPLES:

    Sage

        sage: from sage.repl.rich_output.backend_base import BackendSimple
        sage: from sage.repl.rich_output import get_display_manager
        sage: dm = get_display_manager()
        sage: dm.check_backend_class(BackendSimple)
        Traceback (most recent call last):
        ...
        RuntimeError: check failed: current backend is invalid

    Python

        >>> from sage.all import *
        >>> from sage.repl.rich_output.backend_base import BackendSimple
        >>> from sage.repl.rich_output import get_display_manager
        >>> dm = get_display_manager()
        >>> dm.check_backend_class(BackendSimple)
        Traceback (most recent call last):
        ...
        RuntimeError: check failed: current backend is invalid

  display_immediately(obj, **rich_repr_kwds)

    Show output without going back to the command line prompt.

    This method must be called to create rich output from an object when we are not returning to the command line prompt, for example during program execution. Typically, it is being called by `sage.plot.graphics.Graphics.show()`.

    INPUT:

    - `obj` – anything; the object to be shown

    - `rich_repr_kwds` – optional keyword arguments that are passed through to `obj._rich_repr_`

    EXAMPLES:

    Sage

        sage: from sage.repl.rich_output import get_display_manager
        sage: dm = get_display_manager()
        sage: dm.display_immediately(1/2)
        1/2

    Python

        >>> from sage.all import *
        >>> from sage.repl.rich_output import get_display_manager
        >>> dm = get_display_manager()
        >>> dm.display_immediately(Integer(1)/Integer(2))
        1/2

  displayhook(obj)

    Implementation of the displayhook.

    Every backend must pass the value of the last statement of a line / cell to this method. See also `display_immediately()` if you want do display rich output while a program is running.

    INPUT:

    - `obj` – anything; the object to be shown

    OUTPUT: whatever the backend’s displayhook method returned

    EXAMPLES:

    Sage

        sage: from sage.repl.rich_output import get_display_manager
        sage: dm = get_display_manager()
        sage: dm.displayhook(1/2)
        1/2

    Python

        >>> from sage.all import *
        >>> from sage.repl.rich_output import get_display_manager
        >>> dm = get_display_manager()
        >>> dm.displayhook(Integer(1)/Integer(2))
        1/2

  classmethod get_instance()

    Get the singleton instance.

    This class method is equivalent to `get_display_manager()`.

    OUTPUT: the display manager singleton

    EXAMPLES:

    Sage

        sage: from sage.repl.rich_output.display_manager import DisplayManager
        sage: DisplayManager.get_instance()
        The Sage display manager using the doctest backend

    Python

        >>> from sage.all import *
        >>> from sage.repl.rich_output.display_manager import DisplayManager
        >>> DisplayManager.get_instance()
        The Sage display manager using the doctest backend

  graphics_from_save(save_function, save_kwds, file_extension, output_container, figsize=None, dpi=None)

    Helper to construct graphics.

    This method can be used to simplify the implementation of a `_rich_repr_` method of a graphics object if there is already a function to save graphics to a file.

    INPUT:

    - `save_function` – callable that can save graphics to a file and accepts options like `sage.plot.graphics.Graphics.save()`

    - `save_kwds` – dictionary; keyword arguments that are passed to the save function

    - `file_extension` – string starting with `'.'`; the file extension of the graphics file

    - `output_container` – subclass of `sage.repl.rich_output.output_basic.OutputBase`. The output container to use. Must be one of the types in `supported_output()`.

    - `figsize` – pair of integers (optional). The desired graphics size in pixels. Suggested, but need not be respected by the output.

    - `dpi` – integer (optional). The desired resolution in dots per inch. Suggested, but need not be respected by the output.

    OUTPUT: an instance of `output_container`

    EXAMPLES:

    Sage

        sage: # needs sage.plot sage.symbolic
        sage: from sage.repl.rich_output import get_display_manager
        sage: dm = get_display_manager()
        sage: plt = plot(sin)
        sage: out = dm.graphics_from_save(plt.save, dict(), '.png',
        ....:                             dm.types.OutputImagePng)
        sage: out
        OutputImagePng container
        sage: out.png.get().startswith(b'\x89PNG')
        True
        sage: out.png.filename()   # random
        '/home/user/.sage/temp/localhost.localdomain/23903/tmp_pu5woK.png'

    Python

        >>> from sage.all import *
        >>> # needs sage.plot sage.symbolic
        >>> from sage.repl.rich_output import get_display_manager
        >>> dm = get_display_manager()
        >>> plt = plot(sin)
        >>> out = dm.graphics_from_save(plt.save, dict(), '.png',
        ...                             dm.types.OutputImagePng)
        >>> out
        OutputImagePng container
        >>> out.png.get().startswith(b'\x89PNG')
        True
        >>> out.png.filename()   # random
        '/home/user/.sage/temp/localhost.localdomain/23903/tmp_pu5woK.png'

  is_in_terminal()

    Test whether the UI is meant to run in a terminal.

    When this method returns `True`, you can assume that it is possible to use `raw_input` or launch external programs that take over the input.

    Otherwise, you should assume that the backend runs remotely or in a pty controlled by another program. Then you should not launch external programs with a (text or graphical) UI.

    This is used to enable/disable interpreter consoles.

    OUTPUT:

    Boolean.

  property preferences

    Return the preferences.

    OUTPUT:

    The display preferences as instance of `DisplayPreferences`.

    EXAMPLES:

    Sage

        sage: from sage.repl.rich_output import get_display_manager
        sage: dm = get_display_manager()
        sage: dm.preferences
        Display preferences:
        * align_latex is not specified
        * graphics is not specified
        * supplemental_plot = never
        * text is not specified

    Python

        >>> from sage.all import *
        >>> from sage.repl.rich_output import get_display_manager
        >>> dm = get_display_manager()
        >>> dm.preferences
        Display preferences:
        * align_latex is not specified
        * graphics is not specified
        * supplemental_plot = never
        * text is not specified

  supported_output()

    Return the output container classes that can be used.

    OUTPUT:

    Frozen set of subclasses of `OutputBase`. If the backend defines derived container classes, this method will always return their base classes.

    EXAMPLES:

    Sage

        sage: from sage.repl.rich_output import get_display_manager
        sage: dm = get_display_manager()
        sage: dm.types.OutputPlainText in dm.supported_output()
        True
        sage: type(dm.supported_output())
        <... 'frozenset'>

    Python

        >>> from sage.all import *
        >>> from sage.repl.rich_output import get_display_manager
        >>> dm = get_display_manager()
        >>> dm.types.OutputPlainText in dm.supported_output()
        True
        >>> type(dm.supported_output())
        <... 'frozenset'>

  switch_backend(backend, **kwds)

    Switch to a new backend.

    INPUT:

    - `backend` – instance of `BackendBase`

    - `kwds` – optional keyword arguments that are passed on to the `install()` method

    OUTPUT: the previous backend

    EXAMPLES:

    Sage

        sage: from sage.repl.rich_output.backend_base import BackendSimple
        sage: simple = BackendSimple()
        sage: from sage.repl.rich_output import get_display_manager
        sage: dm = get_display_manager();  dm
        The Sage display manager using the doctest backend

        sage: previous = dm.switch_backend(simple)
        sage: dm
        The Sage display manager using the simple backend

    Python

        >>> from sage.all import *
        >>> from sage.repl.rich_output.backend_base import BackendSimple
        >>> simple = BackendSimple()
        >>> from sage.repl.rich_output import get_display_manager
        >>> dm = get_display_manager();  dm
        The Sage display manager using the doctest backend

        >>> previous = dm.switch_backend(simple)
        >>> dm
        The Sage display manager using the simple backend

    Restore the doctest backend:

    Sage

        sage: dm.switch_backend(previous) is simple
        True

    [Python]

        >>> from sage.all import *
        >>> dm.switch_backend(previous) is simple
        True

  threejs_scripts(online)

    Return Three.js script tag for the current backend.

    INPUT:

    - `online` – boolean determining script usage context

    OUTPUT: string containing script tag

    Note

    This base method handles `online=True` case only, serving CDN script tag. Location of script for offline usage is backend-specific.

    EXAMPLES:

    Sage

        sage: from sage.repl.rich_output import get_display_manager
        sage: get_display_manager().threejs_scripts(online=True)                    # needs sage.plot
        '...<script src="https://cdn.jsdelivr.net/gh/sagemath/threejs-sage@...'
        sage: get_display_manager().threejs_scripts(online=False)                   # needs sage.plot
        Traceback (most recent call last):
        ...
        ValueError: current backend does not support
        offline threejs graphics

    Python

        >>> from sage.all import *
        >>> from sage.repl.rich_output import get_display_manager
        >>> get_display_manager().threejs_scripts(online=True)                    # needs sage.plot
        '...<script src="https://cdn.jsdelivr.net/gh/sagemath/threejs-sage@...'
        >>> get_display_manager().threejs_scripts(online=False)                   # needs sage.plot
        Traceback (most recent call last):
        ...
        ValueError: current backend does not support
        offline threejs graphics

  property types

    Catalog of all output container types.

    Note that every output type must be registered in `sage.repl.rich_output.output_catalog`.

    OUTPUT:

    Returns the `sage.repl.rich_output.output_catalog` module.

    EXAMPLES:

    Sage

        sage: from sage.repl.rich_output import get_display_manager
        sage: dm = get_display_manager()
        sage: dm.types.OutputPlainText
        <class 'sage.repl.rich_output.output_basic.OutputPlainText'>

    Python

        >>> from sage.all import *
        >>> from sage.repl.rich_output import get_display_manager
        >>> dm = get_display_manager()
        >>> dm.types.OutputPlainText
        <class 'sage.repl.rich_output.output_basic.OutputPlainText'>

exception sage.repl.rich_output.display_manager.OutputTypeException

  Bases: `DisplayException`

  Wrong Output container.

  The output containers are the subclasses of `OutputBase` that contain the entire output. The display backends must create output containers of a suitable type depending on the displayed Python object. This exception indicates that there is a mistake in the backend and it returned the wrong type of output container.

  EXAMPLES:

  Sage

      sage: from sage.repl.rich_output.display_manager import OutputTypeException
      sage: raise OutputTypeException('foo')
      Traceback (most recent call last):
      ...
      OutputTypeException: foo

  Python

      >>> from sage.all import *
      >>> from sage.repl.rich_output.display_manager import OutputTypeException
      >>> raise OutputTypeException('foo')
      Traceback (most recent call last):
      ...
      OutputTypeException: foo

exception sage.repl.rich_output.display_manager.RichReprWarning

  Bases: `UserWarning`

  Warning that is throws if a call to `_rich_repr_` fails.

  If an object implements `_rich_repr_` then it must return a value, possibly `None` to indicate that no rich output can be generated. But it may not raise an exception as it is very confusing for the user if the displayhook fails.

  EXAMPLES:

  Sage

      sage: from sage.repl.rich_output.display_manager import RichReprWarning
      sage: raise RichReprWarning('foo')
      Traceback (most recent call last):
      ...
      RichReprWarning: foo

  Python

      >>> from sage.all import *
      >>> from sage.repl.rich_output.display_manager import RichReprWarning
      >>> raise RichReprWarning('foo')
      Traceback (most recent call last):
      ...
      RichReprWarning: foo

class sage.repl.rich_output.display_manager.restricted_output(display_manager, output_classes)

  Bases: `object`

  Context manager to temporarily restrict the accepted output types.

  In the context, the output is restricted to the output container types listed in `output_classes`. Additionally, display preferences are changed not to show graphics.

  INPUT:

  - `display_manager` – the display manager

  - `output_classes` – iterable of output container types

  EXAMPLES:

  Sage

      sage: from sage.repl.rich_output.display_manager import (
      ....:     get_display_manager, restricted_output)
      sage: dm = get_display_manager()
      sage: restricted_output(dm, [dm.types.OutputPlainText])
      <sage.repl.rich_output.display_manager.restricted_output object at 0x...>

  Python

      >>> from sage.all import *
      >>> from sage.repl.rich_output.display_manager import (
      ...     get_display_manager, restricted_output)
      >>> dm = get_display_manager()
      >>> restricted_output(dm, [dm.types.OutputPlainText])
      <sage.repl.rich_output.display_manager.restricted_output object at 0x...>