Basic Output Types#

The Sage rich representation system requires a special container class to hold the data for each type of rich output. They all inherit from OutputBase, though a more typical example is OutputPlainText. Some output classes consist of more than one data buffer, for example jmol or certain animation formats. The output class is independent of user preferences and of the display backend.

The display backends can define derived classes to attach backend-specific display functionality to, for example how to launch a viewer. But they must not change how the output container is created. To enforce this, the Sage _rich_repr_ magic method will only ever see the output class defined here. The display manager will promote it to a backend-specific subclass if necessary prior to displaying it.

To create new types of output, you must create your own subclass of OutputBase and register it in sage.repl.rich_output.output_catalog.

Warning

All rich output data in subclasses of OutputBase must be contained in OutputBuffer instances. You must never reference any files on the local file system, as there is no guarantee that the notebook server and the worker process are on the same computer. Or even share a common file system.

class sage.repl.rich_output.output_basic.OutputAsciiArt(ascii_art)#

Bases: OutputBase

ASCII Art Output

INPUT:

ascii_art – OutputBuffer. Alternatively, a string (bytes) can be passed directly which will then be converted into an OutputBuffer. Ascii art rendered into a string.

EXAMPLES:

sage: from sage.repl.rich_output.output_catalog import OutputAsciiArt
sage: OutputAsciiArt(':-}')
OutputAsciiArt container

classmethod example()#

Construct a sample ascii art output container

This static method is meant for doctests, so they can easily construct an example.

OUTPUT:

An instance of OutputAsciiArt.

EXAMPLES:

sage: from sage.repl.rich_output.output_catalog import OutputAsciiArt
sage: OutputAsciiArt.example()
OutputAsciiArt container
sage: OutputAsciiArt.example().ascii_art.get_str()
'[                        *   *   *    * ]\n[      **   **   *    *  *   *  *    *  ]\n[ ***, * , *  , **, ** , *, * , * , *   ]'

print_to_stdout()#

Write the data to stdout.

This is just a convenience method to help with debugging.

EXAMPLES:

sage: from sage.repl.rich_output.output_catalog import OutputAsciiArt
sage: ascii_art = OutputAsciiArt.example()
sage: ascii_art.print_to_stdout()
[                        *   *   *    * ]
[      **   **   *    *  *   *  *    *  ]
[ ***, * , *  , **, ** , *, * , * , *   ]

class sage.repl.rich_output.output_basic.OutputBase#

Bases: SageObject

Base class for all rich output containers.

classmethod example()#

Construct a sample instance

This static method is meant for doctests, so they can easily construct an example.

OUTPUT:

An instance of the OutputBase subclass.

EXAMPLES:

sage: from sage.repl.rich_output.output_basic import OutputBase
sage: OutputBase.example()
Traceback (most recent call last):
...
NotImplementedError: derived classes must implement this class method

class sage.repl.rich_output.output_basic.OutputLatex(latex)#

Bases: OutputBase

LaTeX Output

Note

The LaTeX commands will only use a subset of LaTeX that can be displayed by MathJax.

INPUT:

latex – OutputBuffer. Alternatively, a string (bytes) can be passed directly which will then be converted into an OutputBuffer. String containing the latex equation code. Excludes the surrounding dollar signs / LaTeX equation environment.

EXAMPLES:

sage: from sage.repl.rich_output.output_catalog import OutputLatex
sage: OutputLatex(latex(sqrt(x)))                                           # needs sage.symbolic
OutputLatex container

display_equation()#

Return the LaTeX code for a display equation

OUTPUT:

String.

EXAMPLES:

sage: from sage.repl.rich_output.output_catalog import OutputLatex
sage: rich_output = OutputLatex('1')
sage: rich_output.latex
buffer containing 1 bytes
sage: rich_output.latex.get_str()
'1'
sage: rich_output.display_equation()
'\\begin{equation}\n1\n\\end{equation}'

classmethod example()#

Construct a sample LaTeX output container

This static method is meant for doctests, so they can easily construct an example.

OUTPUT:

An instance of OutputLatex.

EXAMPLES:

sage: from sage.repl.rich_output.output_catalog import OutputLatex
sage: OutputLatex.example()
OutputLatex container
sage: OutputLatex.example().latex.get_str()
'\\newcommand{\\Bold}[1]{\\mathbf{#1}}\\int \\sin\\left(x\\right)\\,{d x}'

inline_equation()#

Return the LaTeX code for an inline equation

OUTPUT:

String.

EXAMPLES:

sage: from sage.repl.rich_output.output_catalog import OutputLatex
sage: rich_output = OutputLatex('1')
sage: rich_output.latex
buffer containing 1 bytes
sage: rich_output.latex.get_str()
'1'
sage: rich_output.inline_equation()
'\\begin{math}\n1\n\\end{math}'

print_to_stdout()#

Write the data to stdout.

This is just a convenience method to help with debugging.

EXAMPLES:

sage: from sage.repl.rich_output.output_catalog import OutputLatex
sage: rich_output = OutputLatex.example()
sage: rich_output.print_to_stdout()
\newcommand{\Bold}[1]{\mathbf{#1}}\int \sin\left(x\right)\,{d x}

class sage.repl.rich_output.output_basic.OutputPlainText(plain_text)#

Bases: OutputBase

Plain Text Output

INPUT:

plain_text – OutputBuffer. Alternatively, a bytes (string in Python 2.x) or string (unicode in Python 2.x) can be passed directly which will then be converted into an OutputBuffer. The plain text output.

This should always be exactly the same as the (non-rich) output from the _repr_ method. Every backend object must support plain text output as fallback.

EXAMPLES:

sage: from sage.repl.rich_output.output_catalog import OutputPlainText
sage: OutputPlainText('foo')
OutputPlainText container

classmethod example()#

Construct a sample plain text output container

This static method is meant for doctests, so they can easily construct an example.

OUTPUT:

An instance of OutputPlainText.

EXAMPLES:

sage: from sage.repl.rich_output.output_catalog import OutputPlainText
sage: OutputPlainText.example()
OutputPlainText container
sage: OutputPlainText.example().text.get_str()
'Example plain text output'

print_to_stdout()#

Write the data to stdout.

This is just a convenience method to help with debugging.

EXAMPLES:

sage: from sage.repl.rich_output.output_catalog import OutputPlainText
sage: plain_text = OutputPlainText.example()
sage: plain_text.print_to_stdout()
Example plain text output

class sage.repl.rich_output.output_basic.OutputUnicodeArt(unicode_art)#

Bases: OutputBase

Unicode Art Output

Similar to OutputAsciiArt but using the entire unicode range.

INPUT:

unicode_art – OutputBuffer. Alternatively, a string (unicode in Python 2.x) can be passed directly which will then be converted into an OutputBuffer. Unicode art rendered into a string.

EXAMPLES:

sage: from sage.repl.rich_output.output_catalog import OutputUnicodeArt
sage: OutputUnicodeArt(u':-}')
OutputUnicodeArt container

classmethod example()#

Construct a sample unicode art output container

This static method is meant for doctests, so they can easily construct an example.

OUTPUT:

An instance of OutputUnicodeArt.

EXAMPLES:

sage: from sage.repl.rich_output.output_catalog import OutputUnicodeArt
sage: OutputUnicodeArt.example()
OutputUnicodeArt container
sage: print(OutputUnicodeArt.example().unicode_art.get_unicode())
⎛-11   0   1⎞
⎜  3  -1   0⎟
⎝ -1  -1   0⎠

print_to_stdout()#

Write the data to stdout.

This is just a convenience method to help with debugging.

EXAMPLES:

sage: from sage.repl.rich_output.output_catalog import OutputUnicodeArt
sage: unicode_art = OutputUnicodeArt.example()
sage: unicode_art.print_to_stdout()
⎛-11   0   1⎞
⎜  3  -1   0⎟
⎝ -1  -1   0⎠