Coverage for local/lib/python2.7/site-packages/sage/repl/interface_magic.py : 90%

""" 

Magics for each of the Sage interfaces 

This module defines magic functions for interpreters. As an example, 

consider the GAP interpreter which can evaluate a gap command given as 

a string:: 

sage: gap('SymmetricGroup(4)') # not tested 

SymmetricGroup( [ 1 .. 4 ] ) 

Magics are syntactic sugar to avoid writing the Python string. They 

are either called as line magics:: 

sage: %gap SymmetricGroup(4) # not tested 

or as cell magics, that is, spanning multiple lines:: 

sage: %%gap # not tested 

....: G := SymmetricGroup(4); 

....: Display(G); 

Note that the cell magic needs semicolons, this is required by the GAP 

language to separate multiple commands. 

""" 

# Note: no magics in doctests, hence # not tested 

#***************************************************************************** 

# Copyright (C) 2016 Volker Braun <vbraun.name@gmail.com> 

# 

# Distributed under the terms of the GNU General Public License (GPL) 

# as published by the Free Software Foundation; either version 2 of 

# the License, or (at your option) any later version. 

# http://www.gnu.org/licenses/ 

#***************************************************************************** 

from sage.repl.rich_output.display_manager import get_display_manager 

LINE_DOCSTRING = """ 

Interact with {name} 

The line magic %{name} sends a single line to the {name} interface. 

INPUT: 

Single {name} command 

OUTPUT: 

The result of the evaluated {name} command as an interface wrapper 

object. 

EXAMPLES:: 

sage: %{name} 1 + 2 + 3 # not tested 

""" 

CELL_DOCSTRING = """ 

Interact with {name} 

The cell magic %%{name} sends multiple lines to the {name} interface. 

INPUT: 

Multiple lines of valid {name}-commands 

OUTPUT: 

The result of the evaluated {name}-commands is printed. 

EXAMPLES:: 

sage: %%{name} # not tested 

....: 1 + 2 + 3; 

....: some_{name}_command(); 

""" 

class InterfaceMagic(object): 

@classmethod 

def all_iter(cls): 

""" 

Iterate over the available interfaces 

EXAMPLES:: 

sage: from sage.repl.interface_magic import InterfaceMagic 

sage: next(InterfaceMagic.all_iter()) 

<sage.repl.interface_magic.InterfaceMagic object at 0x...> 

""" 

import sage.interfaces.all 

for name, obj in sage.interfaces.all.__dict__.items(): 

if isinstance(obj, sage.interfaces.interface.Interface): 

yield cls(name, obj) 

@classmethod 

def register_all(cls, shell=None): 

""" 

Register all available interfaces 

EXAMPLES:: 

sage: class MockShell(): 

....: magics = set() 

....: def register_magic_function(self, fn, magic_name, magic_kind): 

....: self.magics.add(magic_name) 

....: print(magic_name, magic_kind) 

sage: from sage.repl.interface_magic import InterfaceMagic 

sage: InterfaceMagic.register_all(MockShell()) # random output 

('gp', 'line') 

('gp', 'cell') 

('mwrank', 'line') 

('mwrank', 'cell') 

... 

('maxima', 'line') 

('maxima', 'cell') 

sage: 'gap' in MockShell.magics 

True 

sage: 'maxima' in MockShell.magics 

True 

""" 

if shell is None: 

shell = get_ipython() 

for interface in cls.all_iter(): 

shell.register_magic_function( 

interface.line_magic_factory(), 

magic_name=interface._name, 

magic_kind='line' 

) 

shell.register_magic_function( 

interface.cell_magic_factory(), 

magic_name=interface._name, 

magic_kind='cell' 

) 

@classmethod 

def find(cls, name): 

""" 

Find a particular magic by name 

This method is for doctesting purposes only. 

INPUT: 

- ``name`` -- string. The name of the interface magic to 

search for. 

OUTPUT: 

The corresponding :class:`InterfaceMagic` instance. 

EXAMPLES:: 

sage: from sage.repl.interface_magic import InterfaceMagic 

sage: InterfaceMagic.find('gap') 

<sage.repl.interface_magic.InterfaceMagic object at 0x...> 

""" 

for magic in cls.all_iter(): 

if magic._name == name: 

return magic 

def __init__(self, name, interface): 

""" 

Interface Magic 

This class is a wrapper around interface objects to provide 

them with magics. 

INPUT: 

- ``name`` -- string. The interface name 

- ``interface`` -- :class:`sage.interfaces.expect.Expect`. The 

interface to wrap. 

EXAMPLES:: 

sage: from sage.repl.interface_magic import InterfaceMagic 

sage: InterfaceMagic.find('gap') 

<sage.repl.interface_magic.InterfaceMagic object at 0x...> 

""" 

self._name = name 

self._interface = interface 

def line_magic_factory(self): 

""" 

Factory for line magic 

OUTPUT: 

A function suitable to be used as line magic. 

EXAMPLES:: 

sage: from sage.repl.interface_magic import InterfaceMagic 

sage: line_magic = InterfaceMagic.find('gap').line_magic_factory() 

sage: output = line_magic('1+1') 

sage: output  

2 

sage: type(output) 

<class 'sage.interfaces.gap.GapElement'> 

This is how the built line magic is used in practice:: 

sage: from sage.repl.interpreter import get_test_shell 

sage: shell = get_test_shell() 

sage: shell.run_cell('%gap 1+1') 

2 

sage: shell.run_cell('%gap?') 

Docstring: 

Interact with gap 

<BLANKLINE> 

The line magic %gap sends a single line to the gap interface. 

... 

""" 

terminal = get_display_manager().is_in_terminal() 

def line_magic(line): 

if line: 

return self._interface(line) 

else: 

if terminal: 

self._interface.interact() 

else: 

raise SyntaxError('{0} command required'.format(self._name)) 

line_magic.__doc__ = LINE_DOCSTRING.format(name=self._name) 

return line_magic 

def cell_magic_factory(self): 

r""" 

Factory for cell magic 

OUTPUT: 

A function suitable to be used as cell magic. 

EXAMPLES:: 

sage: from sage.repl.interface_magic import InterfaceMagic 

sage: cell_magic = InterfaceMagic.find('gap').cell_magic_factory() 

sage: output = cell_magic('', '1+1;') 

2 

sage: output is None 

True 

sage: cell_magic('foo', '1+1;') 

Traceback (most recent call last): 

... 

SyntaxError: Interface magics have no options, got "foo" 

This is how the built cell magic is used in practice:: 

sage: from sage.repl.interpreter import get_test_shell 

sage: shell = get_test_shell() 

sage: shell.run_cell('%%gap\nG:=SymmetricGroup(5);\n1+1;Order(G);') 

Sym( [ 1 .. 5 ] ) 

2 

120 

sage: shell.run_cell('%%gap foo\n1+1;\n') 

File "<string>", line unknown 

SyntaxError: Interface magics have no options, got "foo" 

<BLANKLINE> 

sage: shell.run_cell('%%gap?') 

Docstring: 

Interact with gap 

<BLANKLINE> 

The cell magic %%gap sends multiple lines to the gap interface. 

... 

""" 

def cell_magic(line, cell): 

""" 

Evaluate cell magic 

Docstring is overwritten in the instance 

INPUT: 

- ``line`` -- string. The option part of the cell magic. 

- ``cell`` -- string. The lines of the cell magic. 

OUTPUT: 

Prints the interface output. 

RAISES: 

``SyntaxError`` if a line is specified; Interfaces have no 

options. 

""" 

if line: 

raise SyntaxError('Interface magics have no options, got "{0}"'.format(line)) 

output = self._interface.eval(cell) 

print(output) 

cell_magic.__doc__ = CELL_DOCSTRING.format(name=self._name) 

return cell_magic