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

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 SageInteractiveShell.
  • 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:

  • Cleanly deinitialize the Sage library before exiting. See ask_exit().
  • Modify the libraries before calling system commands. See system_raw().

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.misc.interpreter.InterfaceShellTransformer(*args, **kwds)

Bases: IPython.core.prefilter.PrefilterTransformer

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

lines_queue

a list of lines to be evaluated

temporary_objects

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

EXAMPLES:

sage: from sage.misc.interpreter import interface_shell_embed
sage: shell = interface_shell_embed(maxima)
sage: ift = shell.prefilter_manager.transformers[0]
sage: ift.lines_queue
[]
sage: ift.temporary_objects
[]
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.misc.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. If a line ends in backspace, then this method will store line in lines_queue until it receives a line not ending in backspace.

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.misc.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)+\', False)sage: 
ift.shell.prompt_manager.in_template
u'....: '
sage: ift.lines_queue
[' sage2 +']
sage: ift.temporary_objects
[4]
sage: ift.transform('4', False)
'sage.misc.all.logstr(...8...)'
sage: ift.lines_queue
[]
sage: ift.temporary_objects
[]

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.misc.interpreter.MagicTransformer

Handle input lines that start out like load ... or attach ....

Since there are objects in the Sage namespace named load and attach, IPython’s automagic will not transform these lines into %load ... and %attach ..., respectively. Thus, we have to do it manually.

class sage.misc.interpreter.SageCrashHandler(app)

Bases: IPython.frontend.terminal.ipapp.IPAppCrashHandler

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

EXAMPLES:

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

Bases: IPython.frontend.terminal.interactiveshell.TerminalInteractiveShell

ask_exit()

We need to run the sage.all.quit_sage() function when we exit the shell.

EXAMPLES:

We install a fake sage.all.quit_sage():

sage: import sage.all
sage: old_quit = sage.all.quit_sage
sage: def new_quit(): print "Quitter!!!"
sage: sage.all.quit_sage = new_quit

Now, we can check to see that this method works:

sage: from sage.misc.interpreter import get_test_shell
sage: shell = get_test_shell()
sage: shell.ask_exit()
Quitter!!!
sage: shell.exit_now
True

Clean up after ourselves:

sage: shell.exit_now = False
sage: sage.all.quit_sage = old_quit
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 #975 for a discussion of running system commands.

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

EXAMPLES:

sage: from sage.misc.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
class sage.misc.interpreter.SagePreparseTransformer

Preparse the line of code before it get evaluated by IPython.

class sage.misc.interpreter.SagePromptDedenter

Remove leading spaces from the input line.

class sage.misc.interpreter.SagePromptTransformer

Remove Sage prompts from the input line.

class sage.misc.interpreter.SageTerminalApp(**kwargs)

Bases: IPython.frontend.terminal.ipapp.TerminalIPythonApp

crash_handler_class

alias of SageCrashHandler

init_shell()

Initialize the SageInteractiveShell instance. Additionally, this also does the following:

  • Merges the default shell configuration with the user’s.

Note

This code is based on TermintalIPythonApp.init_shell().

EXAMPLES:

sage: from sage.misc.interpreter import SageTerminalApp, DEFAULT_SAGE_CONFIG
sage: app = SageTerminalApp(config=DEFAULT_SAGE_CONFIG)
sage: app.initialize(argv=[])  # indirect doctest
sage: app.shell
<sage.misc.interpreter.SageInteractiveShell object at 0x...>
load_config_file(*args, **kwds)

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

sage.misc.interpreter.embedded()

Returns True if Sage is being run from the notebook.

EXAMPLES:

sage: from sage.misc.interpreter import embedded
sage: embedded()
False
sage.misc.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.misc.interpreter import get_test_shell
sage: shell = get_test_shell(); shell
<sage.misc.interpreter.SageInteractiveShell object at 0x...>

TESTS:

Check that trac ticket #14070 has been resolved:

sage: from sage.tests.cmdline import test_executable
sage: cmd = 'from sage.misc.interpreter import get_test_shell; shell = get_test_shell()'
sage: (out, err, ret) = test_executable(["sage", "-c", cmd])
sage: out + err
''
sage.misc.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.misc.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.misc.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
sage.misc.interpreter.sage_prompt()

Returns the current Sage prompt.

EXAMPLES:

sage: from sage.misc.interpreter import get_test_shell
sage: shell = get_test_shell()
sage: shell.run_cell('sage_prompt()')
u'sage'
sage.misc.interpreter.set_sage_prompt(s)

Sets the Sage prompt to the string s.

Parameters:s (string) – the new prompt
Returns:None

EXAMPLES:

sage: from sage.misc.interpreter import get_test_shell
sage: shell = get_test_shell()
sage: shell.run_cell('from sage.misc.interpreter import set_sage_prompt')
sage: shell.run_cell('set_sage_prompt(u"new")')
sage: shell.prompt_manager.in_template
u'new: '
sage: shell.run_cell('set_sage_prompt(u"sage")')

Table Of Contents

Previous topic

The Sage Preparser

Next topic

Functional notation

This Page