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: exceptions.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: sage.structure.sage_object.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('\x89PNG')
True
sage: out.png.filename()   # random
'/home/user/.sage/temp/localhost.localdomain/23903/tmp_pu5woK.png'

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:
* graphics is not specified
* 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())
<type '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

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: sage.repl.rich_output.display_manager.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: exceptions.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

sage.repl.rich_output.display_manager.get_display_manager

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

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

Bases: object

Context manager to temporarily restrict the accepted output types

INPUT:

• display_manager – the display manager.
• output_classes – iterable of

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