### Navigation

- index
- modules |
- next |
- previous |
- The Sage Command Line »

# Sage’s IPython Modifications

This module contains all of Sage’s customizations to the IPython interpreter. These changes consist of the following major components:

> - `SageTerminalApp`
> - `SageInteractiveShell`
> - `SageTerminalInteractiveShell`
> - `interface_shell_embed()`

## SageTerminalApp

This is the main application object. It is used by the `$SAGE_LOCAL/bin/sage-ipython` script to start the Sage command-line. It’s primary purpose is to

> - Initialize the `SageTerminalInteractiveShell`.
> - Provide default configuration options for the shell, and its subcomponents. These work with (and can be overridden by) IPython’s configuration system.
> - Load the Sage ipython extension (which does things like preparsing, add magics, etc.).
> - Provide a custom `SageCrashHandler` to give the user instructions on how to report the crash to the Sage support mailing list.

## SageInteractiveShell

The `SageInteractiveShell` object is the object responsible for accepting input from the user and evaluating it. From the command-line, this object can be retrieved by running:

    sage: shell = get_ipython()   # not tested

The `SageInteractiveShell` provides the following customizations:

> - Modify the libraries before calling system commands. See `system_raw()`.

## SageTerminalInteractiveShell

The `SageTerminalInteractiveShell` is a close relative of `SageInteractiveShell` that is specialized for running in a terminal. In particular, running commands like `!ls` will directly write to stdout. Technically, the `system` attribute will point to `system_raw` instead of `system_piped`.

## Interface Shell

The function `interface_shell_embed()` takes a `Interface` object and returns an embeddable IPython shell which can be used to directly interact with that shell. The bulk of this functionality is provided through `InterfaceShellTransformer`.

class `sage.repl.interpreter.``InterfaceShellTransformer`(*args, **kwds)

  Bases: `IPython.core.prefilter.PrefilterTransformer`

  Initialize this class. All of the arguments get passed to `PrefilterTransformer.__init__()`.

  `temporary_objects`

    a list of hold onto interface objects and keep them from being garbage collected

  See also

  `interface_shell_embed()`

  EXAMPLES:

      sage: from sage.repl.interpreter import interface_shell_embed
      sage: shell = interface_shell_embed(maxima)
      sage: ift = shell.prefilter_manager.transformers[0]
      sage: ift.temporary_objects
      set()
      sage: ift._sage_import_re.findall('sage(a) + maxima(b)')
      ['a', 'b']

  `preparse_imports_from_sage`(line)

    Finds occurrences of strings such as `sage(object)` in line, converts `object` to `shell.interface`, and replaces those strings with their identifier in the new system. This also works with strings such as `maxima(object)` if `shell.interface` is `maxima`.

    Parameters: | line (string) – the line to transform

    Warning

    This does not parse nested parentheses correctly. Thus, lines like `sage(a.foo())` will not work correctly. This can’t be done in generality with regular expressions.

    EXAMPLES:

        sage: from sage.repl.interpreter import interface_shell_embed, InterfaceShellTransformer
        sage: shell = interface_shell_embed(maxima)
        sage: ift = InterfaceShellTransformer(shell=shell, config=shell.config, prefilter_manager=shell.prefilter_manager)
        sage: ift.shell.ex('a = 3')
        sage: ift.preparse_imports_from_sage('2 + sage(a)')
        '2 + sage0 '
        sage: maxima.eval('sage0')
        '3'
        sage: ift.preparse_imports_from_sage('2 + maxima(a)')
        '2 +  sage1 '
        sage: ift.preparse_imports_from_sage('2 + gap(a)')
        '2 + gap(a)'

  `transform`(line, continue_prompt)

    Evaluates line in `shell.interface` and returns a string representing the result of that evaluation.

    Parameters: | line (string) – the line to be transformed and evaluated continue_prompt (bool) – is this line a continuation in a sequence of multiline input?

    EXAMPLES:

        sage: from sage.repl.interpreter import interface_shell_embed, InterfaceShellTransformer
        sage: shell = interface_shell_embed(maxima)
        sage: ift = InterfaceShellTransformer(shell=shell, config=shell.config, prefilter_manager=shell.prefilter_manager)
        sage: ift.transform('2+2', False)   # note: output contains triple quotation marks
        'sage.misc.all.logstr("""4""")'
        sage: ift.shell.ex('a = 4')
        sage: ift.transform(r'sage(a)+4', False)
        'sage.misc.all.logstr("""8""")'
        sage: ift.temporary_objects
        set()
        sage: shell = interface_shell_embed(gap)
        sage: ift = InterfaceShellTransformer(shell=shell, config=shell.config, prefilter_manager=shell.prefilter_manager)
        sage: ift.transform('2+2', False)
        'sage.misc.all.logstr("""4""")'

class `sage.repl.interpreter.``SageCrashHandler`(app)

  Bases: `IPython.terminal.ipapp.IPAppCrashHandler`

  A custom `CrashHandler` which gives the user instructions on how to post the problem to sage-support.

  EXAMPLES:

      sage: from sage.repl.interpreter import SageTerminalApp, SageCrashHandler
      sage: app = SageTerminalApp.instance()
      sage: sch = SageCrashHandler(app); sch
      <sage.repl.interpreter.SageCrashHandler object at 0x...>
      sage: sorted(sch.info.items())
      [('app_name', u'Sage'),
       ('bug_tracker', 'http://trac.sagemath.org'),
       ('contact_email', 'sage-support@googlegroups.com'),
       ('contact_name', 'sage-support'),
       ('crash_report_fname', u'Crash_report_Sage.txt')]

class `sage.repl.interpreter.``SageInteractiveShell`(ipython_dir=None, profile_dir=None, user_module=None, user_ns=None, custom_exceptions=((), None), **kwargs)

  Bases: `sage.repl.interpreter.SageNativeExecute`, `IPython.core.interactiveshell.InteractiveShell`

class `sage.repl.interpreter.``SageNativeExecute`

  Bases: `object`

  x.__init__(...) initializes x; see help(type(x)) for signature

  `system_raw`(cmd)

    Run a system command.

    If the command is not a sage-specific binary, adjust the library paths before calling system commands. See trac ticket #975 for a discussion of running system commands.

    This is equivalent to the sage-native-execute shell script.

    EXAMPLES:

        sage: from sage.repl.interpreter import get_test_shell
        sage: shell = get_test_shell()
        sage: shell.system_raw('false')
        sage: shell.user_ns['_exit_code'] > 0
        True
        sage: shell.system_raw('true')
        sage: shell.user_ns['_exit_code']
        0
        sage: shell.system_raw('env | grep "^LD_LIBRARY_PATH=" | grep $SAGE_LOCAL')
        sage: shell.user_ns['_exit_code']
        1
        sage: shell.system_raw('R --version')
        R version ...
        sage: shell.user_ns['_exit_code']
        0

`sage.repl.interpreter.``SagePreparseTransformer`(**kwargs)

  EXAMPLES:

      sage: from sage.repl.interpreter import SagePreparseTransformer
      sage: spt = SagePreparseTransformer()
      sage: spt.push('1+1r+2.3^2.3r')
      "Integer(1)+1+RealNumber('2.3')**2.3"
      sage: preparser(False)
      sage: spt.push('2.3^2')
      '2.3^2'

  TESTS:

  Check that syntax errors in the preparser do not crash IPython, see trac ticket #14961.

      sage: preparser(True)
      sage: bad_syntax = "R.<t> = QQ{]"
      sage: preparse(bad_syntax)
      Traceback (most recent call last):
      ...
      SyntaxError: Mismatched ']'
      sage: from sage.repl.interpreter import get_test_shell
      sage: shell = get_test_shell()
      sage: shell.run_cell(bad_syntax)
        File "<string>", line unknown
      SyntaxError: Mismatched ']'
      <BLANKLINE>

`sage.repl.interpreter.``SagePromptTransformer`(**kwargs)

  Strip the sage:/....: prompts of Sage.

  EXAMPLES:

      sage: from sage.repl.interpreter import SagePromptTransformer
      sage: spt = SagePromptTransformer()
      sage: spt.push("sage: 2 + 2")
      '2 + 2'
      sage: spt.push('')
      ''
      sage: spt.push("....: 2+2")
      '2+2'

  This should strip multiple prompts: see trac ticket #16297:

      sage: spt.push("sage:   sage: 2+2")
      '2+2'
      sage: spt.push("   sage: ....: 2+2")
      '2+2'

  The prompt contains a trailing space. Extra spaces between the last prompt and the remainder should not be stripped:

      sage: spt.push("   sage: ....:    2+2")
      '   2+2'

  We test that the input transformer is enabled on the Sage command line:

      sage: from sage.repl.interpreter import get_test_shell
      sage: shell = get_test_shell()
      sage: shell.run_cell('sage: a = 123')              # single line
      sage: shell.run_cell('sage: a = [\n... 123]')      # old-style multi-line
      sage: shell.run_cell('sage: a = [\n....: 123]')    # new-style multi-line

  We test that trac ticket #16196 is resolved:

      sage: shell.run_cell('    sage: 1+1')
      2

class `sage.repl.interpreter.``SageTerminalApp`(**kwargs)

  Bases: `IPython.terminal.ipapp.TerminalIPythonApp`

  `crash_handler_class`

    alias of `SageCrashHandler`

  `init_shell`()

    Initialize the `SageInteractiveShell` instance.

    Note

    This code is based on `TerminalIPythonApp.init_shell()`.

    EXAMPLES:

        sage: from sage.repl.interpreter import SageTerminalApp, DEFAULT_SAGE_CONFIG
        sage: app = SageTerminalApp(config=DEFAULT_SAGE_CONFIG)
        sage: app.initialize(argv=[])  # indirect doctest
        sage: app.shell
        <sage.repl.interpreter.SageTerminalInteractiveShell object at 0x...>

  `load_config_file`(*args, **kwds)

    Merges a config file with the default sage config.

    Note

    This code is based on `Application.update_config()`.

    TESTS:

    Test that trac ticket #15972 has been fixed:

        sage: from sage.misc.temporary_file import tmp_dir
        sage: from sage.repl.interpreter import SageTerminalApp
        sage: d = tmp_dir()
        sage: IPYTHONDIR = os.environ['IPYTHONDIR']
        sage: os.environ['IPYTHONDIR'] = d
        sage: SageTerminalApp().load_config_file()
        sage: os.environ['IPYTHONDIR'] = IPYTHONDIR

class `sage.repl.interpreter.``SageTerminalInteractiveShell`(config=None, ipython_dir=None, profile_dir=None, user_ns=None, user_module=None, custom_exceptions=((), None), usage=None, banner1=None, banner2=None, display_banner=None, **kwargs)

  Bases: `sage.repl.interpreter.SageNativeExecute`, `IPython.terminal.interactiveshell.TerminalInteractiveShell`

`sage.repl.interpreter.``embedded`()

  Returns True if Sage is being run from the notebook.

  EXAMPLES:

      sage: from sage.repl.interpreter import embedded
      sage: embedded()
      False

`sage.repl.interpreter.``get_test_shell`()

  Returns a IPython shell that can be used in testing the functions in this module.

  Returns: | an IPython shell

  EXAMPLES:

      sage: from sage.repl.interpreter import get_test_shell
      sage: shell = get_test_shell(); shell
      <sage.repl.interpreter.SageTerminalInteractiveShell object at 0x...>

  TESTS:

  Check that trac ticket #14070 has been resolved:

      sage: from sage.tests.cmdline import test_executable
      sage: cmd = 'from sage.repl.interpreter import get_test_shell; shell = get_test_shell()'
      sage: (out, err, ret) = test_executable(["sage", "-c", cmd])
      sage: out + err
      ''

`sage.repl.interpreter.``interface_shell_embed`(interface)

  Returns an IPython shell which uses a Sage interface on the backend to perform the evaluations. It uses `InterfaceShellTransformer` to transform the input into the appropriate `interface.eval(...)` input.

  INPUT:

  - `interface` – A Sage `PExpect` interface instance.

  EXAMPLES:

      sage: from sage.repl.interpreter import interface_shell_embed
      sage: shell = interface_shell_embed(gap)
      sage: shell.run_cell('List( [1..10], IsPrime )')
      [ false, true, true, false, true, false, true, false, false, false ]

`sage.repl.interpreter.``preparser`(on=True)

  Turn on or off the Sage preparser.

  Parameters: | on (bool) – if True turn on preparsing; if False, turn it off.

  EXAMPLES:

      sage: 2/3
      2/3
      sage: preparser(False)
      sage: 2/3  # not tested since doctests are always preparsed
      0
      sage: preparser(True)
      sage: 2^3
      8

### Navigation

- index
- modules |
- next |
- previous |
- The Sage Command Line »