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

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

>>> from sage.all import *
>>> %gap SymmetricGroup(Integer(4))          # not tested

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

sage: %%gap                           # not tested
....: G := SymmetricGroup(4);
....: Display(G);

>>> from sage.all import *
>>> %%gap                           # not tested
... G := SymmetricGroup(Integer(4));
... Display(G);

Note that the cell magic needs semicolons, this is required by the GAP language to separate multiple commands.

class sage.repl.interface_magic.InterfaceMagic(name, interface)[source]

Bases: object

Interface Magic.

This class is a wrapper around interface objects to provide them with magics.

INPUT:

EXAMPLES:

sage: from sage.repl.interface_magic import InterfaceMagic
sage: InterfaceMagic.find('gap')                                            # needs sage.libs.gap
<sage.repl.interface_magic.InterfaceMagic object at 0x...>

>>> from sage.all import *
>>> from sage.repl.interface_magic import InterfaceMagic
>>> InterfaceMagic.find('gap')                                            # needs sage.libs.gap
<sage.repl.interface_magic.InterfaceMagic object at 0x...>
classmethod all_iter()[source]

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

>>> from sage.all import *
>>> from sage.repl.interface_magic import InterfaceMagic
>>> next(InterfaceMagic.all_iter())
<sage.repl.interface_magic.InterfaceMagic object at 0x...>
cell_magic_factory()[source]

Factory for cell magic.

OUTPUT: a function suitable to be used as cell magic

EXAMPLES:

sage: # needs sage.libs.gap
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"

>>> from sage.all import *
>>> # needs sage.libs.gap
>>> from sage.repl.interface_magic import InterfaceMagic
>>> cell_magic = InterfaceMagic.find('gap').cell_magic_factory()
>>> output = cell_magic('', '1+1;')
2
>>> output is None
True
>>> 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);')         # needs sage.libs.gap
Sym( [ 1 .. 5 ] )
2
120
sage: shell.run_cell('%%gap foo\n1+1;\n')                                   # needs sage.libs.gap
...File...<string>...
SyntaxError: Interface magics have no options, got "foo"

sage: shell.run_cell('%%gap?')                                              # needs sage.libs.gap
Docstring:
Interact with gap

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

>>> from sage.all import *
>>> from sage.repl.interpreter import get_test_shell
>>> shell = get_test_shell()
>>> shell.run_cell('%%gap\nG:=SymmetricGroup(5);\n1+1;Order(G);')         # needs sage.libs.gap
Sym( [ 1 .. 5 ] )
2
120
>>> shell.run_cell('%%gap foo\n1+1;\n')                                   # needs sage.libs.gap
...File...<string>...
SyntaxError: Interface magics have no options, got "foo"
<BLANKLINE>
>>> shell.run_cell('%%gap?')                                              # needs sage.libs.gap
Docstring:
Interact with gap
<BLANKLINE>
The cell magic %%gap sends multiple lines to the gap interface.
...
classmethod find(name)[source]

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

EXAMPLES:

sage: from sage.repl.interface_magic import InterfaceMagic
sage: InterfaceMagic.find('gap')                                            # needs sage.libs.gap
<sage.repl.interface_magic.InterfaceMagic object at 0x...>

>>> from sage.all import *
>>> from sage.repl.interface_magic import InterfaceMagic
>>> InterfaceMagic.find('gap')                                            # needs sage.libs.gap
<sage.repl.interface_magic.InterfaceMagic object at 0x...>
line_magic_factory()[source]

Factory for line magic.

OUTPUT: a function suitable to be used as line magic

EXAMPLES:

sage: # needs sage.libs.gap
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'>

>>> from sage.all import *
>>> # needs sage.libs.gap
>>> from sage.repl.interface_magic import InterfaceMagic
>>> line_magic = InterfaceMagic.find('gap').line_magic_factory()
>>> output = line_magic('1+1')
>>> output
2
>>> 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')                                            # needs sage.libs.gap
2
sage: shell.run_cell('%gap?')                                               # needs sage.libs.gap
Docstring:
Interact with gap

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

>>> from sage.all import *
>>> from sage.repl.interpreter import get_test_shell
>>> shell = get_test_shell()
>>> shell.run_cell('%gap 1+1')                                            # needs sage.libs.gap
2
>>> shell.run_cell('%gap?')                                               # needs sage.libs.gap
Docstring:
Interact with gap
<BLANKLINE>
The line magic %gap sends a single line to the gap interface.
...
classmethod register_all(shell=None)[source]

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                                             # needs sage.libs.gap
True
sage: 'maxima' in MockShell.magics                                          # needs sage.symbolic
True

>>> from sage.all import *
>>> class MockShell():
...     magics = set()
...     def register_magic_function(self, fn, magic_name, magic_kind):
...         self.magics.add(magic_name)
...         print(magic_name, magic_kind)
>>> from sage.repl.interface_magic import InterfaceMagic
>>> InterfaceMagic.register_all(MockShell())    # random output
('gp', 'line')
('gp', 'cell')
('mwrank', 'line')
('mwrank', 'cell')
...
('maxima', 'line')
('maxima', 'cell')
>>> 'gap' in MockShell.magics                                             # needs sage.libs.gap
True
>>> 'maxima' in MockShell.magics                                          # needs sage.symbolic
True