passagemath-repl 10.4.62__py3-none-any.whl

sage/repl/interface_magic.py

@@ -0,0 +1,298 @@
+# sage_setup: distribution = sagemath-repl
+"""
+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.
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+
+from sage.misc.lazy_import import lazy_import, LazyImport
+from sage.repl.rich_output.display_manager import get_display_manager
+
+lazy_import('sage.interfaces.interface', 'Interface')
+
+
+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:
+
+    @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...>
+        """
+        try:
+            import sage.interfaces.all
+        except ImportError:
+            return
+        for name, obj in sage.interfaces.all.__dict__.items():
+            if isinstance(obj, (Interface, LazyImport)):
+                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                                             # needs sage.libs.gap
+            True
+            sage: 'maxima' in MockShell.magics                                          # needs sage.symbolic
+            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')                                            # needs sage.libs.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')                                            # needs sage.libs.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: # 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'>
+
+        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
+            <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: # 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"
+
+        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"
+            <BLANKLINE>
+            sage: shell.run_cell('%%gap?')                                              # needs sage.libs.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:
+
+            :exc:`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