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)[source]

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

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

from sage.repl.rich_output.output_catalog import OutputAsciiArt
OutputAsciiArt(':-}')
classmethod example()[source]

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[ ***, * , *  , **, ** , *, * , * , *   ]'

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

from sage.repl.rich_output.output_catalog import OutputAsciiArt
OutputAsciiArt.example()
OutputAsciiArt.example().ascii_art.get_str()
print_to_stdout()[source]

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()
[                        *   *   *    * ]
[      **   **   *    *  *   *  *    *  ]
[ ***, * , *  , **, ** , *, * , * , *   ]

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

from sage.repl.rich_output.output_catalog import OutputAsciiArt
ascii_art = OutputAsciiArt.example()
ascii_art.print_to_stdout()
class sage.repl.rich_output.output_basic.OutputBase[source]

Bases: SageObject

Base class for all rich output containers.

classmethod example()[source]

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

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

from sage.repl.rich_output.output_basic import OutputBase
OutputBase.example()
class sage.repl.rich_output.output_basic.OutputLatex(latex)[source]

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

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

from sage.repl.rich_output.output_catalog import OutputLatex
OutputLatex(latex(sqrt(x)))                                           # needs sage.symbolic
display_equation()[source]

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

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

from sage.repl.rich_output.output_catalog import OutputLatex
rich_output = OutputLatex('1')
rich_output.latex
rich_output.latex.get_str()
rich_output.display_equation()
classmethod example()[source]

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

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

from sage.repl.rich_output.output_catalog import OutputLatex
OutputLatex.example()
OutputLatex.example().latex.get_str()
inline_equation()[source]

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

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

from sage.repl.rich_output.output_catalog import OutputLatex
rich_output = OutputLatex('1')
rich_output.latex
rich_output.latex.get_str()
rich_output.inline_equation()
print_to_stdout()[source]

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}

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

from sage.repl.rich_output.output_catalog import OutputLatex
rich_output = OutputLatex.example()
rich_output.print_to_stdout()
class sage.repl.rich_output.output_basic.OutputPlainText(plain_text)[source]

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

>>> from sage.all import *
>>> from sage.repl.rich_output.output_catalog import OutputPlainText
>>> OutputPlainText('foo')
OutputPlainText container

from sage.repl.rich_output.output_catalog import OutputPlainText
OutputPlainText('foo')
classmethod example()[source]

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'

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

from sage.repl.rich_output.output_catalog import OutputPlainText
OutputPlainText.example()
OutputPlainText.example().text.get_str()
print_to_stdout()[source]

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

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

from sage.repl.rich_output.output_catalog import OutputPlainText
plain_text = OutputPlainText.example()
plain_text.print_to_stdout()
class sage.repl.rich_output.output_basic.OutputUnicodeArt(unicode_art)[source]

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

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

from sage.repl.rich_output.output_catalog import OutputUnicodeArt
OutputUnicodeArt(u':-}')
classmethod example()[source]

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⎠

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

from sage.repl.rich_output.output_catalog import OutputUnicodeArt
OutputUnicodeArt.example()
print(OutputUnicodeArt.example().unicode_art.get_unicode())
print_to_stdout()[source]

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⎠

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

from sage.repl.rich_output.output_catalog import OutputUnicodeArt
unicode_art = OutputUnicodeArt.example()
unicode_art.print_to_stdout()