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
>>> 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[source]¶
- 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 - >>> 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[source]¶
- 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 - >>> 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)[source]¶
- 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 - RuntimeErroris raised if- backend_classis 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 - >>> 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)[source]¶
- 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 - >>> 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)[source]¶
- 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: from sage.repl.rich_output import get_display_manager sage: dm = get_display_manager() sage: dm.displayhook(1/2) 1/2 - >>> 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()[source]¶
- 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 - >>> 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)[source]¶
- 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: # 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' - >>> 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()[source]¶
- 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_inputor 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 - >>> 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()[source]¶
- 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'> - >>> 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)[source]¶
- 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 - >>> 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: dm.switch_backend(previous) is simple True - >>> from sage.all import * >>> dm.switch_backend(previous) is simple True 
 - threejs_scripts(online)[source]¶
- 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=Truecase 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) # 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 - >>> 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_catalogmodule.- 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'> - >>> 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[source]¶
- Bases: - DisplayException- Wrong Output container. - The output containers are the subclasses of - OutputBasethat 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 - >>> 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[source]¶
- 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- Noneto 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 - >>> 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)[source]¶
- 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...> - >>> 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...>