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: from sage.repl.rich_output import get_display_manager
sage: 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: from sage.repl.rich_output.display_manager import DisplayException
sage: 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: from sage.repl.rich_output import get_display_manager
sage: 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: 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
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: from sage.repl.rich_output import get_display_manager
sage: dm = get_display_manager()
sage: dm.display_immediately(1/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:

Returns whatever the backend’s displayhook method returned.

EXAMPLES:

sage: from sage.repl.rich_output import get_display_manager
sage: dm = get_display_manager()
sage: dm.displayhook(1/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: from sage.repl.rich_output.display_manager import DisplayManager
sage: 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:

Return an instance of output_container.

EXAMPLES:

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

Restore the doctest backend:

sage: 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: from sage.repl.rich_output import get_display_manager
sage: get_display_manager().threejs_scripts(online=True)
'...<script src="https://cdn.jsdelivr.net/gh/sagemath/threejs-sage@...'
sage: get_display_manager().threejs_scripts(online=False)
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: 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'>
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: from sage.repl.rich_output.display_manager import OutputTypeException
sage: 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: from sage.repl.rich_output.display_manager import RichReprWarning
sage: 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: 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...>