Magics for each of the Sage interfaces - The Sage Command Line

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

# 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

    sage: gap('SymmetricGroup(4)')        # not tested
    SymmetricGroup( [ 1 .. 4 ] )

Python

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

    sage: %gap SymmetricGroup(4)          # not tested

[Python]

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

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

Sage

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

Python

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

  Bases: `object`

  Interface Magic.

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

  INPUT:

  - `name` – string; the interface name

  - `interface` – `sage.interfaces.expect.Expect`; the interface to wrap

  EXAMPLES:

  Sage

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

  Python

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

    Iterate over the available interfaces.

    EXAMPLES:

    Sage

        sage: from sage.repl.interface_magic import InterfaceMagic
        sage: next(InterfaceMagic.all_iter())
        <sage.repl.interface_magic.InterfaceMagic object at 0x...>

    Python

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

    Factory for cell magic.

    OUTPUT: a function suitable to be used as cell magic

    EXAMPLES:

    Sage

        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"

    Python

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

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

    [Python]

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

    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

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

    Python

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

    Factory for line magic.

    OUTPUT: a function suitable to be used as line magic

    EXAMPLES:

    Sage

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

    Python

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

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

    [Python]

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

    Register all available interfaces.

    EXAMPLES:

    Sage

        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

    Python

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