Coverage for local/lib/python2.7/site-packages/sage/interfaces/interface.py : 61%

r""" 

Common Interface Functionality 

See the examples in the other sections for how to use specific 

interfaces. The interface classes all derive from the generic 

interface that is described in this section. 

AUTHORS: 

- William Stein (2005): initial version 

- William Stein (2006-03-01): got rid of infinite loop on startup if 

client system missing 

- Felix Lawrence (2009-08-21): edited ._sage_() to support lists and float exponents in foreign notation. 

- Simon King (2010-09-25): Expect._local_tmpfile() depends on 

Expect.pid() and is cached; Expect.quit() clears that cache, 

which is important for forking. 

- Jean-Pierre Flori (2010,2011): Split non Pexpect stuff into a parent class. 

- Simon King (2015): Improve pickling for InterfaceElement 

""" 

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

# Copyright (C) 2005 William Stein <wstein@gmail.com> 

# 

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

# 

# This code is distributed in the hope that it will be useful, 

# but WITHOUT ANY WARRANTY; without even the implied warranty of 

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 

# General Public License for more details. 

# 

# The full text of the GPL is available at: 

# 

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

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

from __future__ import print_function 

from six import iteritems, integer_types, string_types 

import operator 

from sage.structure.sage_object import SageObject 

from sage.structure.parent_base import ParentWithBase 

from sage.structure.element import Element, parent 

import sage.misc.sage_eval 

from sage.misc.fast_methods import WithEqualityById 

from sage.docs.instancedoc import instancedoc 

class AsciiArtString(str): 

def __repr__(self): 

return str(self) 

class Interface(WithEqualityById, ParentWithBase): 

""" 

Interface interface object. 

.. NOTE:: 

Two interfaces compare equal if and only if they are identical 

objects (this is a critical constraint so that caching of 

representations of objects in interfaces works 

correctly). Otherwise they are never equal. 

""" 

def __init__(self, name): 

""" 

Initialize ``self``. 

EXAMPLES:: 

sage: Maxima() == maxima 

False 

sage: maxima == maxima 

True 

sage: Maxima() != maxima 

True 

sage: maxima != maxima 

False 

""" 

self.__name = name 

self.__coerce_name = '_' + name.lower() + '_' 

self.__seq = -1 

self._available_vars = [] 

self._seed = None 

ParentWithBase.__init__(self, self) 

def _repr_(self): 

return self.__name.capitalize() 

def name(self, new_name=None): 

return self.__name 

def get_seed(self): 

""" 

Return the seed used to set the random number generator in 

this interface. 

The seed is initialized as ``None`` but should be set when the 

interface starts. 

EXAMPLES:: 

sage: s = Singular() 

sage: s.set_seed(107) 

107 

sage: s.get_seed() 

107 

""" 

return self._seed 

def rand_seed(self): 

""" 

Return a random seed that can be put into ``set_seed`` function 

for any interpreter. 

This should be overridden if the particular interface needs 

something other than a small positive integer. 

EXAMPLES:: 

sage: from sage.interfaces.interface import Interface 

sage: i = Interface("") 

sage: i.rand_seed() # random 

318491487L 

sage: s = Singular() 

sage: s.rand_seed() # random 

365260051L 

""" 

from sage.misc.randstate import randstate 

return randstate().seed()&0x1FFFFFFF 

def set_seed(self, seed=None): 

""" 

Set the random seed for the interpreter and return the new 

value of the seed. 

This is dependent on which interpreter so must be implemented 

in each separately. For examples see gap.py or singular.py. 

If seed is ``None`` then should generate a random seed. 

EXAMPLES:: 

sage: s = Singular() 

sage: s.set_seed(1) 

1 

sage: [s.random(1,10) for i in range(5)] 

[8, 10, 4, 9, 1] 

sage: from sage.interfaces.interface import Interface 

sage: i = Interface("") 

sage: i.set_seed() 

Traceback (most recent call last): 

... 

NotImplementedError: This interpreter did not implement a set_seed function 

""" 

raise NotImplementedError("This interpreter did not implement a set_seed function") 

def interact(self): 

r""" 

This allows you to interactively interact with the child 

interpreter. Press Ctrl-D or type 'quit' or 'exit' to exit and 

return to Sage. 

.. note:: 

This is completely different than the console() member 

function. The console function opens a new copy of the 

child interpreter, whereas the interact function gives you 

interactive access to the interpreter that is being used by 

Sage. Use sage(xxx) or interpretername(xxx) to pull objects 

in from sage to the interpreter. 

""" 

from sage.repl.interpreter import interface_shell_embed 

shell = interface_shell_embed(self) 

try: 

ipython = get_ipython() 

except NameError: 

shell() 

else: 

shell(local_ns=dict(ipython.user_ns)) 

def _pre_interact(self): 

pass 

def _post_interact(self): 

pass 

def cputime(self): 

""" 

CPU time since this process started running. 

""" 

raise NotImplementedError 

def read(self, filename): 

r""" 

EXAMPLES:: 

sage: filename = tmp_filename() 

sage: f = open(filename, 'w') 

sage: _ = f.write('x = 2\n') 

sage: f.close() 

sage: octave.read(filename) # optional - octave 

sage: octave.get('x') # optional - octave 

' 2' 

sage: import os 

sage: os.unlink(filename) 

""" 

self.eval(self._read_in_file_command(filename)) 

def _read_in_file_command(self, filename): 

raise NotImplementedError 

def eval(self, code, **kwds): 

""" 

Evaluate code in an interface. 

This method needs to be implemented in sub-classes. 

Note that it is not always to be expected that 

it returns a non-empty string. In contrast, 

:meth:`get` is supposed to return the result of applying 

a print command to the object so that the output is easier 

to parse. 

Likewise, the method :meth:`_eval_line` for evaluation of a single 

line, often makes sense to be overridden. 

""" 

raise NotImplementedError 

_eval_line = eval 

def execute(self, *args, **kwds): 

return self.eval(*args, **kwds) 

def __call__(self, x, name=None): 

r""" 

Create a new object in self from x. 

The object X returned can be used like any Sage object, and 

wraps an object in self. The standard arithmetic operators 

work. Moreover if foo is a function then 

X.foo(y,z,...) 

calls foo(X, y, z, ...) and returns the corresponding object. 

EXAMPLES:: 

sage: gp(2) 

2 

sage: gp('2') 

2 

sage: a = gp(2); gp(a) is a 

True 

""" 

cls = self._object_class() 

#Handle the case when x is an object 

#in some interface. 

if isinstance(x, InterfaceElement): 

if x.parent() is self: 

return x 

#We convert x into an object in this 

#interface by first going through Sage. 

try: 

return self(x._sage_()) 

except (NotImplementedError, TypeError): 

pass 

if isinstance(x, string_types): 

return cls(self, x, name=name) 

try: 

return self._coerce_from_special_method(x) 

except TypeError: 

raise 

except AttributeError: 

pass 

try: 

return self._coerce_impl(x, use_special=False) 

except TypeError as msg: 

try: 

return cls(self, str(x), name=name) 

except TypeError: 

raise TypeError(msg) 

def _coerce_from_special_method(self, x): 

""" 

Tries to coerce to self by calling a special underscore method. 

If no such method is defined, raises an AttributeError instead of a 

TypeError. 

""" 

s = '_%s_'%self.name() 

if s == '_maxima_lib_': 

s = '_maxima_' 

if s == '_pari_': 

s = '_gp_' 

try: 

return (x.__getattribute__(s))(self) 

except AttributeError: 

return self(x._interface_init_()) 

def _coerce_impl(self, x, use_special=True): 

if isinstance(x, integer_types): 

import sage.rings.all 

return self(sage.rings.all.Integer(x)) 

elif isinstance(x, float): 

import sage.rings.all 

return self(sage.rings.all.RDF(x)) 

if use_special: 

try: 

return self._coerce_from_special_method(x) 

except AttributeError: 

pass 

if isinstance(x, (list, tuple)): 

A = [] 

z = [] 

cls = self._object_class() 

for v in x: 

if isinstance(v, cls): 

A.append(v.name()) 

z.append(v) 

else: 

w = self(v) 

A.append(w.name()) 

z.append(w) 

X = ','.join(A) 

r = self.new('%s%s%s'%(self._left_list_delim(), X, self._right_list_delim())) 

r.__sage_list = z # do this to avoid having the entries of the list be garbage collected 

return r 

raise TypeError("unable to coerce element into %s"%self.name()) 

def new(self, code): 

return self(code) 

################################################################### 

# these should all be appropriately overloaded by the derived class 

################################################################### 

def _left_list_delim(self): 

return "[" 

def _right_list_delim(self): 

return "]" 

def _left_func_delim(self): 

return "(" 

def _right_func_delim(self): 

return ")" 

def _assign_symbol(self): 

return "=" 

def _equality_symbol(self): 

raise NotImplementedError 

# For efficiency purposes, you should definitely override these 

# in your derived class. 

def _true_symbol(self): 

try: 

return self.__true_symbol 

except AttributeError: 

self.__true_symbol = self.get('1 %s 1'%self._equality_symbol()) 

return self.__true_symbol 

def _false_symbol(self): 

try: 

return self.__false_symbol 

except AttributeError: 

self.__false_symbol = self.get('1 %s 2'%self._equality_symbol()) 

return self.__false_symbol 

def _lessthan_symbol(self): 

return '<' 

def _greaterthan_symbol(self): 

return '>' 

def _inequality_symbol(self): 

return '!=' 

def _relation_symbols(self): 

""" 

Returns a dictionary with operators as the keys and their 

string representation as the values. 

EXAMPLES:: 

sage: import operator 

sage: symbols = mathematica._relation_symbols() 

sage: symbols[operator.eq] 

'==' 

""" 

return dict([(operator.eq, self._equality_symbol()), (operator.ne, self._inequality_symbol()), 

(operator.lt, self._lessthan_symbol()), (operator.le, "<="), 

(operator.gt, self._greaterthan_symbol()), (operator.ge, ">=")]) 

def _exponent_symbol(self): 

""" 

Return the symbol used to denote *10^ in floats, e.g 'e' in 1.5e6 

EXAMPLES:: 

sage: from sage.interfaces.expect import Expect 

sage: Expect('nonexistent_interface', 'fake')._exponent_symbol() 

'e' 

""" 

return 'e' 

############################################################ 

# Functions for working with variables. 

# The first three must be overloaded by derived classes, 

# and the definition depends a lot on the class. But 

# the functionality one gets from this is very nice. 

############################################################ 

def set(self, var, value): 

""" 

Set the variable var to the given value. 

""" 

cmd = '%s%s%s;'%(var,self._assign_symbol(), value) 

self.eval(cmd) 

def get(self, var): 

""" 

Get the value of the variable var. 

Note that this needs to be overridden in some interfaces, 

namely when getting the string representation of an object 

requires an explicit print command. 

""" 

return self.eval(var) 

def get_using_file(self, var): 

r""" 

Return the string representation of the variable var in self, 

possibly using a file. Use this if var has a huge string 

representation, since it may be way faster. 

.. warning:: 

In fact unless a special derived class implements this, it 

will *not* be any faster. This is the case for this class 

if you're reading it through introspection and seeing this. 

""" 

return self.get(var) 

def clear(self, var): 

""" 

Clear the variable named var. 

""" 

self._available_vars.append(var) 

def _next_var_name(self): 

if len(self._available_vars) != 0: 

v = self._available_vars[0] 

del self._available_vars[0] 

return v 

self.__seq += 1 

return "sage%s"%self.__seq 

def _create(self, value, name=None): 

name = self._next_var_name() if name is None else name 

self.set(name, value) 

return name 

def _object_class(self): 

""" 

EXAMPLES:: 

sage: from sage.interfaces.expect import Expect 

sage: Expect._object_class(maxima) 

<class 'sage.interfaces.expect.ExpectElement'> 

""" 

return InterfaceElement 

def _function_class(self): 

""" 

EXAMPLES:: 

sage: from sage.interfaces.interface import Interface 

sage: Interface._function_class(maxima) 

<class 'sage.interfaces.interface.InterfaceFunction'> 

""" 

return InterfaceFunction 

def _function_element_class(self): 

""" 

EXAMPLES:: 

sage: from sage.interfaces.interface import Interface 

sage: Interface._function_element_class(maxima) 

<class 'sage.interfaces.interface.InterfaceFunctionElement'> 

""" 

return InterfaceFunctionElement 

def _convert_args_kwds(self, args=None, kwds=None): 

""" 

Converts all of the args and kwds to be elements of this 

interface. 

EXAMPLES:: 

sage: args = [5] 

sage: kwds = {'x': 6} 

sage: args, kwds = gap._convert_args_kwds(args, kwds) 

sage: args 

[5] 

sage: list(map(type, args)) 

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

sage: type(kwds['x']) 

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

""" 

args = [] if args is None else args 

kwds = {} if kwds is None else kwds 

if not isinstance(args, list): 

args = [args] 

for i, arg in enumerate(args): 

if not isinstance(arg, InterfaceElement) or arg.parent() is not self: 

args[i] = self(arg) 

for key, value in iteritems(kwds): 

if not isinstance(value, InterfaceElement) or value.parent() is not self: 

kwds[key] = self(value) 

return args, kwds 

def _check_valid_function_name(self, function): 

""" 

Checks to see if function is a valid function name in this 

interface. If it is not, an exception is raised. Otherwise, nothing 

is done. 

EXAMPLES:: 

sage: gap._check_valid_function_name('SymmetricGroup') 

sage: gap._check_valid_function_name('') 

Traceback (most recent call last): 

... 

ValueError: function name must be nonempty 

sage: gap._check_valid_function_name('__foo') 

Traceback (most recent call last): 

... 

AttributeError 

""" 

if function == '': 

raise ValueError("function name must be nonempty") 

if function[:2] == "__": 

raise AttributeError 

def function_call(self, function, args=None, kwds=None): 

""" 

EXAMPLES:: 

sage: maxima.quad_qags(x, x, 0, 1, epsrel=1e-4) 

[0.5,0.55511151231257...e-14,21,0] 

sage: maxima.function_call('quad_qags', [x, x, 0, 1], {'epsrel':'1e-4'}) 

[0.5,0.55511151231257...e-14,21,0] 

""" 

args, kwds = self._convert_args_kwds(args, kwds) 

self._check_valid_function_name(function) 

s = self._function_call_string(function, 

[s.name() for s in args], 

['%s=%s'%(key,value.name()) for key, value in kwds.items()]) 

return self.new(s) 

def _function_call_string(self, function, args, kwds): 

""" 

Returns the string used to make function calls. 

EXAMPLES:: 

sage: maxima._function_call_string('diff', ['f(x)', 'x'], []) 

'diff(f(x),x)' 

""" 

return "%s(%s)"%(function, ",".join(list(args) + list(kwds))) 

def call(self, function_name, *args, **kwds): 

return self.function_call(function_name, args, kwds) 

def _contains(self, v1, v2): 

raise NotImplementedError 

def __getattr__(self, attrname): 

""" 

TESTS:: 

sage: ParentWithBase.__getattribute__(singular, '_coerce_map_from_') 

<bound method Singular._coerce_map_from_ of Singular> 

""" 

try: 

return ParentWithBase.__getattribute__(self, attrname) 

except AttributeError: 

if attrname[:1] == "_": 

raise 

return self._function_class()(self, attrname) 

def console(self): 

raise NotImplementedError 

def help(self, s): 

return AsciiArtString('No help on %s available'%s) 

@instancedoc 

class InterfaceFunction(SageObject): 

""" 

Interface function. 

""" 

def __init__(self, parent, name): 

self._parent = parent 

self._name = name 

def _repr_(self): 

return "%s"%self._name 

def __call__(self, *args, **kwds): 

return self._parent.function_call(self._name, list(args), kwds) 

def _instancedoc_(self): 

""" 

EXAMPLES:: 

sage: gp.gcd.__doc__ 

'gcd(x,{y}): greatest common divisor of x and y.' 

""" 

M = self._parent 

return M.help(self._name) 

@instancedoc 

class InterfaceFunctionElement(SageObject): 

""" 

Interface function element. 

""" 

def __init__(self, obj, name): 

self._obj = obj 

self._name = name 

def _repr_(self): 

return "%s" % self._name 

def __call__(self, *args, **kwds): 

return self._obj.parent().function_call(self._name, [self._obj] + list(args), kwds) 

def help(self): 

print(self.__doc__) 

def _instancedoc_(self): 

""" 

EXAMPLES:: 

sage: gp(2).gcd.__doc__ 

'gcd(x,{y}): greatest common divisor of x and y.' 

""" 

M = self._obj.parent() 

return M.help(self._name) 

def is_InterfaceElement(x): 

return isinstance(x, InterfaceElement) 

@instancedoc 

class InterfaceElement(Element): 

""" 

Interface element. 

""" 

def __init__(self, parent, value, is_name=False, name=None): 

Element.__init__(self, parent) 

self._create = value 

if parent is None: return # means "invalid element" 

# idea: Joe Wetherell -- try to find out if the output 

# is too long and if so get it using file, otherwise 

# don't. 

if is_name: 

self._name = value 

else: 

try: 

self._name = parent._create(value, name=name) 

except (TypeError, RuntimeError, ValueError) as x: 

raise TypeError(x) 

def _latex_(self): 

# return "\\begin{verbatim}%s\\end{verbatim}"%self 

string = str(self) 

if not '|' in string: 

delim = '|' 

elif not '#' in string: 

delim = '#' 

elif not '@' in string: 

delim = '@' 

elif not '~' in string: 

delim = '~' 

return "\\verb%s%s%s"%(delim, string, delim) 

def __iter__(self): 

for i in range(1, len(self)+1): 

yield self[i] 

def __len__(self): 

""" 

Call self.sage() and return the length of that sage object. 

This approach is inefficient - each interface should override 

this method with one that calls the external program's length 

function. 

EXAMPLES:: 

sage: len(gp([1,2,3])) 

3 

AUTHORS: 

- Felix Lawrence (2009-08-21) 

""" 

return len(self.sage()) 

def __reduce__(self): 

""" 

The default linearisation is to return self's parent, 

which will then get the items returned by :meth:`_reduce` 

as arguments to reconstruct the element. 

EXAMPLES:: 

sage: G = gap.SymmetricGroup(6) 

sage: loads(dumps(G)) == G # indirect doctest 

True 

sage: y = gap(34) 

sage: loads(dumps(y)) 

34 

sage: type(_) 

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

sage: y = singular(34) 

sage: loads(dumps(y)) 

34 

sage: type(_) 

<class 'sage.interfaces.singular.SingularElement'> 

sage: G = gap.PolynomialRing(QQ, ['x']) 

sage: loads(dumps(G)) 

PolynomialRing( Rationals, ["x"] ) 

sage: S = singular.ring(0, ('x')) 

sage: loads(dumps(S)) 

polynomial ring, over a field, global ordering 

// coefficients: QQ 

// number of vars : 1 

// block 1 : ordering lp 

// : names x 

// block 2 : ordering C 

Here are further examples of pickling of interface elements:: 

sage: loads(dumps(gp('"abc"'))) 

abc 

sage: loads(dumps(gp([1,2,3]))) 

[1, 2, 3] 

sage: loads(dumps(pari('"abc"'))) 

"abc" 

sage: loads(dumps(pari([1,2,3]))) 

[1, 2, 3] 

sage: loads(dumps(r('"abc"'))) 

[1] "abc" 

sage: loads(dumps(r([1,2,3]))) 

[1] 1 2 3 

sage: loads(dumps(maxima([1,2,3]))) 

[1,2,3] 

Unfortunately, strings in maxima can't be pickled yet:: 

sage: loads(dumps(maxima('"abc"'))) 

Traceback (most recent call last): 

... 

TypeError: unable to make sense of Maxima expression '"abc"' in Sage 

""" 

return self.parent(), (self._reduce(),) 

def _reduce(self): 

""" 

Helper for pickling. 

By default, if self is a string, then the representation of 

that string is returned (not the string itself). Otherwise, 

it is attempted to return the corresponding Sage object. 

If this fails with a NotImplementedError, the string 

representation of self is returned instead. 

EXAMPLES:: 

sage: S = singular.ring(0, ('x')) 

sage: S._reduce() 

Univariate Polynomial Ring in x over Rational Field 

sage: G = gap.PolynomialRing(QQ, ['x']) 

sage: G._reduce() 

'PolynomialRing( Rationals, ["x"] )' 

sage: G.sage() 

Traceback (most recent call last): 

... 

NotImplementedError: Unable to parse output: PolynomialRing( Rationals, ["x"] ) 

sage: singular('"abc"')._reduce() 

"'abc'" 

sage: singular('1')._reduce() 

1 

""" 

if self.is_string(): 

return repr(self.sage()) 

try: 

return self.sage() 

except NotImplementedError: 

return repr(self) 

def __call__(self, *args): 

self._check_valid() 

P = self.parent() 

return getattr(P, self.name())(*args) 

def __contains__(self, x): 

P = self._check_valid() 

if not isinstance(x, InterfaceElement) or x.parent() is not self.parent(): 

x = P.new(x) 

return P._contains(x.name(), self.name()) 

def _instancedoc_(self): 

""" 

EXAMPLES:: 

sage: gp(2).__doc__ 

'2' 

""" 

return str(self) 

def __hash__(self): 

""" 

Returns the hash of self. This is a default implementation of hash 

which just takes the hash of the string of self. 

""" 

return hash('%s'%(self)) 

def __cmp__(self, other): 

""" 

Comparison of interface elements. 

NOTE: 

GAP has a special role here. It may in some cases raise an error 

when comparing objects, which is unwanted in Python. We catch 

these errors. Moreover, GAP does not recognise certain objects as 

equal even if there definitions are identical. 

NOTE: 

This methods need to be overridden if the subprocess would 

not return a string representation of a boolean value unless 

an explicit print command is used. 

TESTS: 

Here are examples in which GAP succeeds with a comparison:: 

sage: gap('SymmetricGroup(8)')==gap('SymmetricGroup(8)') 

True 

sage: gap('SymmetricGroup(8)')>gap('AlternatingGroup(8)') 

False 

sage: gap('SymmetricGroup(8)')<gap('AlternatingGroup(8)') 

True 

Here, GAP fails to compare, and so ``False`` is returned. 

In previous Sage versions, this example actually resulted 

in an error; compare :trac:`5962`. 

:: 

sage: gap('DihedralGroup(8)')==gap('DihedralGroup(8)') 

False 

""" 

P = self._check_valid() 

try: 

if P.eval("%s %s %s"%(self.name(), P._equality_symbol(), 

other.name())) == P._true_symbol(): 

return 0 

except RuntimeError: 

pass 

try: 

if P.eval("%s %s %s"%(self.name(), P._lessthan_symbol(), other.name())) == P._true_symbol(): 

return -1 

except RuntimeError: 

pass 

try: 

if P.eval("%s %s %s"%(self.name(), P._greaterthan_symbol(), other.name())) == P._true_symbol(): 

return 1 

except Exception: 

pass 

# everything is supposed to be comparable in Python, so we define 

# the comparison thus when no comparison is available in interfaced system. 

if (hash(self) < hash(other)): 

return -1 

else: 

return 1 

def is_string(self): 

""" 

Tell whether this element is a string. 

By default, the answer is negative. 

""" 

return False 

def _matrix_(self, R): 

raise NotImplementedError 

def _vector_(self, R): 

raise NotImplementedError 

def _check_valid(self): 

""" 

Check that this object is valid, i.e., the session in which this 

object is defined is still running. This is relevant for 

interpreters that can't be interrupted via ctrl-C, hence get 

restarted. 

""" 

try: 

P = self.parent() 

if P is None: 

raise ValueError("The %s session in which this object was defined is no longer running."%P.name()) 

except AttributeError: 

raise ValueError("The session in which this object was defined is no longer running.") 

return P 

def __del__(self): 

try: 

self._check_valid() 

except ValueError: 

return 

if hasattr(self,'_name'): 

P = self.parent() 

if not (P is None):