Basic Output Types - The Sage Command Line

Skip to content
Back to top
View this page
Edit this page

# 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

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

  Python

      >>> from sage.all import *
      >>> from sage.repl.rich_output.output_catalog import OutputAsciiArt
      >>> 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

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

    Python

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

  print_to_stdout()

    Write the data to stdout.

    This is just a convenience method to help with debugging.

    EXAMPLES:

    Sage

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

    Python

        >>> from sage.all import *
        >>> 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

  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

        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

    Python

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

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

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

  Python

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

  display_equation()

    Return the LaTeX code for a display equation.

    OUTPUT: string

    EXAMPLES:

    Sage

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

    Python

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

  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

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

    Python

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

  inline_equation()

    Return the LaTeX code for an inline equation.

    OUTPUT: string

    EXAMPLES:

    Sage

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

    Python

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

  print_to_stdout()

    Write the data to stdout.

    This is just a convenience method to help with debugging.

    EXAMPLES:

    Sage

        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}

    Python

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

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

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

  Python

      >>> from sage.all import *
      >>> from sage.repl.rich_output.output_catalog import OutputPlainText
      >>> 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

        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'

    Python

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

  print_to_stdout()

    Write the data to stdout.

    This is just a convenience method to help with debugging.

    EXAMPLES:

    Sage

        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

    Python

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

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

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

  Python

      >>> from sage.all import *
      >>> from sage.repl.rich_output.output_catalog import OutputUnicodeArt
      >>> 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

        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⎠

    Python

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

  print_to_stdout()

    Write the data to stdout.

    This is just a convenience method to help with debugging.

    EXAMPLES:

    Sage

        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⎠

    Python

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