diff --git a/src/sage/structure/element.pyx b/src/sage/structure/element.pyx index a0f662be39f..0fbece59d06 100644 --- a/src/sage/structure/element.pyx +++ b/src/sage/structure/element.pyx @@ -224,11 +224,11 @@ def py_scalar_to_element(py): elif PyComplex_Check(py): return CDF(py) else: - raise TypeError, "Not a scalar" + raise TypeError("Not a scalar") def is_Element(x): """ - Return True if x is of type Element. + Return ``True`` if x is of type Element. EXAMPLES:: @@ -319,7 +319,7 @@ cdef class Element(sage_object.SageObject): AttributeError: 'LeftZeroSemigroup_with_category.element_class' object has no attribute 'blah_blah' We test that "private" attributes are not requested from the element class - of the category (trac ticket #10467):: + of the category (:trac:`10467`):: sage: C = EuclideanDomains() sage: P. = QQ[] @@ -452,8 +452,8 @@ cdef class Element(sage_object.SageObject): def _im_gens_(self, codomain, im_gens): """ - Return the image of self in codomain under the map that sends - the images of the generators of the parent of self to the + Return the image of ``self`` in codomain under the map that sends + the images of the generators of the parent of ``self`` to the tuple of elements of im_gens. """ raise NotImplementedError @@ -475,6 +475,13 @@ cdef class Element(sage_object.SageObject): def base_ring(self): """ Returns the base ring of this element's parent (if that makes sense). + + TESTS:: + + sage: QQ.base_ring() + Rational Field + sage: identity_matrix(3).base_ring() + Integer Ring """ return self._parent.base_ring() @@ -642,9 +649,9 @@ cdef class Element(sage_object.SageObject): sage: (2/3).n() 0.666666666666667 - sage: pi.n(digits=10) + sage: pi.n(digits=10) # indirect doctest 3.141592654 - sage: pi.n(prec=20) # 20 bits + sage: pi.n(prec=20) # indirect doctest 3.1416 TESTS: @@ -654,12 +661,11 @@ cdef class Element(sage_object.SageObject): sage: (0).n(algorithm='foo') 0.000000000000000 """ - import sage.misc.functional - return sage.misc.functional.numerical_approx(self, prec=prec, - digits=digits, - algorithm=algorithm) - n = numerical_approx - N = n + from sage.misc.functional import numerical_approx + return numerical_approx(self, prec=prec, digits=digits, + algorithm=algorithm) + n = numerical_approx + N = n def _mpmath_(self, prec=53, rounding=None): """ @@ -720,7 +726,7 @@ cdef class Element(sage_object.SageObject): cpdef _act_on_(self, x, bint self_on_left): """ - Use this method to implement self acting on x. + Use this method to implement ``self`` acting on x. Return None or raise a CoercionException if no such action is defined here. @@ -729,7 +735,7 @@ cdef class Element(sage_object.SageObject): cpdef _acted_upon_(self, x, bint self_on_left): """ - Use this method to implement self acted on by x. + Use this method to implement ``self`` acted on by x. Return None or raise a CoercionException if no such action is defined here. @@ -738,8 +744,8 @@ cdef class Element(sage_object.SageObject): def __xor__(self, right): - raise RuntimeError, "Use ** for exponentiation, not '^', which means xor\n"+\ - "in Python, and has the wrong precedence." + raise RuntimeError("Use ** for exponentiation, not '^', which means xor\n"+\ + "in Python, and has the wrong precedence.") def __pos__(self): return self @@ -765,7 +771,7 @@ cdef class Element(sage_object.SageObject): def _is_atomic(self): """ - Return True if and only if parenthesis are not required when + Return ``True`` if and only if parenthesis are not required when *printing* out any of `x - s`, `x + s`, `x^s` and `x/s`. EXAMPLES:: @@ -782,7 +788,7 @@ cdef class Element(sage_object.SageObject): def __nonzero__(self): r""" - Return True if self does not equal self.parent()(0). + Return ``True`` if ``self`` does not equal self.parent()(0). Note that this is automatically called when converting to boolean, as in the conditional of an if or while statement. @@ -807,7 +813,7 @@ cdef class Element(sage_object.SageObject): def is_zero(self): """ - Return True if self equals self.parent()(0). The default + Return ``True`` if ``self`` equals self.parent()(0). The default implementation is to fall back to 'not self.__nonzero__'. .. warning:: @@ -951,7 +957,7 @@ cdef class Element(sage_object.SageObject): cdef int _cmp_c_impl(left, Element right) except -2: ### For derived Cython code, you *MUST* ALSO COPY the __richcmp__ above ### into your class!!! For Python code just use __cmp__. - raise NotImplementedError, "BUG: sort algorithm for elements of '%s' not implemented"%right.parent() + raise NotImplementedError("BUG: sort algorithm for elements of '%s' not implemented"%right.parent()) cdef inline bint _rich_to_bool(int op, int r): if op == Py_LT: #< @@ -970,7 +976,7 @@ cdef inline bint _rich_to_bool(int op, int r): def is_ModuleElement(x): """ - Return True if x is of type ModuleElement. + Return ``True`` if x is of type ModuleElement. This is even faster than using isinstance inline. @@ -994,7 +1000,7 @@ cdef class ElementWithCachedMethod(Element): The :class:`~sage.misc.cachefunc.cached_method` decorator provides a convenient way to automatically cache the result of a computation. - Since trac ticket #11115, the cached method decorator applied to a + Since :trac:`11115`, the cached method decorator applied to a method without optional arguments is faster than a hand-written cache in Python, and a cached method without any arguments (except ``self``) is actually faster than a Python method that does nothing more but @@ -1234,7 +1240,7 @@ cdef class ModuleElement(Element): return coercion_model.bin_op(left, right, add) cpdef ModuleElement _add_(left, ModuleElement right): - raise TypeError, arith_error_message(left, right, add) + raise TypeError(arith_error_message(left, right, add)) def __iadd__(ModuleElement self, right): if have_same_parent(self, right): @@ -1313,7 +1319,7 @@ cdef class ModuleElement(Element): if PyInt_CheckExact(left): return (right)._mul_long(PyInt_AS_LONG(left)) if have_same_parent(left, right): - raise TypeError, arith_error_message(left, right, mul) + raise TypeError(arith_error_message(left, right, mul)) # Always do this global coercion_model return coercion_model.bin_op(left, right, mul) @@ -1386,7 +1392,7 @@ cdef class ModuleElement(Element): def is_MonoidElement(x): """ - Return True if x is of type MonoidElement. + Return ``True`` if x is of type MonoidElement. """ return IS_INSTANCE(x, MonoidElement) @@ -1444,7 +1450,7 @@ cdef class MonoidElement(Element): Return the (integral) power of self. """ if dummy is not None: - raise RuntimeError, "__pow__ dummy argument not used" + raise RuntimeError("__pow__ dummy argument not used") return generic_power_c(self,n,None) def __nonzero__(self): @@ -1452,7 +1458,7 @@ cdef class MonoidElement(Element): def is_AdditiveGroupElement(x): """ - Return True if x is of type AdditiveGroupElement. + Return ``True`` if x is of type AdditiveGroupElement. """ return IS_INSTANCE(x, AdditiveGroupElement) @@ -1467,7 +1473,7 @@ cdef class AdditiveGroupElement(ModuleElement): return self.additive_order() def __invert__(self): - raise NotImplementedError, "multiplicative inverse not defined for additive group elements" + raise NotImplementedError("multiplicative inverse not defined for additive group elements") cpdef ModuleElement _rmul_(self, RingElement left): return self._lmul_(left) @@ -1484,7 +1490,7 @@ cdef class AdditiveGroupElement(ModuleElement): def is_MultiplicativeGroupElement(x): """ - Return True if x is of type MultiplicativeGroupElement. + Return ``True`` if x is of type MultiplicativeGroupElement. """ return IS_INSTANCE(x, MultiplicativeGroupElement) @@ -1499,7 +1505,7 @@ cdef class MultiplicativeGroupElement(MonoidElement): return self.multiplicative_order() def _add_(self, x): - raise ArithmeticError, "addition not defined in a multiplicative group" + raise ArithmeticError("addition not defined in a multiplicative group") def __div__(left, right): if have_same_parent(left, right): @@ -1522,7 +1528,7 @@ cdef class MultiplicativeGroupElement(MonoidElement): def is_RingElement(x): """ - Return True if x is of type RingElement. + Return ``True`` if x is of type RingElement. """ return IS_INSTANCE(x, RingElement) @@ -1719,7 +1725,7 @@ cdef class RingElement(ModuleElement): Cython classes should override this function to implement multiplication. See extensive documentation at the top of element.pyx. """ - raise TypeError, arith_error_message(self, right, mul) + raise TypeError(arith_error_message(self, right, mul)) def __imul__(left, right): if have_same_parent(left, right): @@ -1780,7 +1786,7 @@ cdef class RingElement(ModuleElement): sage: 2r^(1/2) sqrt(2) - Exponent overflow should throw an OverflowError (trac #2956):: + Exponent overflow should throw an OverflowError (:trac:`2956`):: sage: K. = AA[] sage: x^(2^64 + 12345) @@ -1788,7 +1794,7 @@ cdef class RingElement(ModuleElement): ... OverflowError: Exponent overflow (2147483648). - Another example from trac #2956; this should overflow on x32 + Another example from :trac:`2956`; this should overflow on x32 and succeed on x64:: sage: K. = ZZ[] @@ -1800,7 +1806,7 @@ cdef class RingElement(ModuleElement): """ if dummy is not None: - raise RuntimeError, "__pow__ dummy argument not used" + raise RuntimeError("__pow__ dummy argument not used") return generic_power_c(self,n,None) ################################## @@ -1835,9 +1841,9 @@ cdef class RingElement(ModuleElement): return self._parent.fraction_field()(self, right) except AttributeError: if not right: - raise ZeroDivisionError, "Cannot divide by zero" + raise ZeroDivisionError("Cannot divide by zero") else: - raise TypeError, arith_error_message(self, right, div) + raise TypeError(arith_error_message(self, right, div)) def __idiv__(self, right): """ @@ -1868,17 +1874,31 @@ cdef class RingElement(ModuleElement): def multiplicative_order(self): r""" - Return the multiplicative order of self, if self is a unit, or raise + Return the multiplicative order of self, if ``self`` is a unit, or raise ``ArithmeticError`` otherwise. """ if not self.is_unit(): - raise ArithmeticError, "self (=%s) must be a unit to have a multiplicative order." + raise ArithmeticError("self (=%s) must be a unit to have a multiplicative order.") raise NotImplementedError def is_nilpotent(self): """ - Return True if self is nilpotent, i.e., some power of self + Return ``True`` if ``self`` is nilpotent, i.e., some power of self is 0. + + TESTS:: + + sage: a=QQ(2) + sage: a.is_nilpotent() + False + sage: a=QQ(0) + sage: a.is_nilpotent() + True + sage: m=matrix(RR,3,[[3,2,3],[9,0,3],[-9,0,-3]]) + sage: m.is_nilpotent() + Traceback (most recent call last): + ... + NotImplementedError """ if self.is_unit(): return False @@ -1910,7 +1930,16 @@ cdef class RingElement(ModuleElement): def is_CommutativeRingElement(x): """ - Return True if x is of type CommutativeRingElement. + Return ``True`` if x is of type CommutativeRingElement. + + TESTS:: + + sage: from sage.rings.commutative_ring_element import is_CommutativeRingElement + sage: is_CommutativeRingElement(oo) + False + + sage: is_CommutativeRingElement(1) + True """ return IS_INSTANCE(x, CommutativeRingElement) @@ -1920,14 +1949,14 @@ cdef class CommutativeRingElement(RingElement): """ def inverse_mod(self, I): r""" - Return an inverse of self modulo the ideal `I`, if defined, - i.e., if `I` and self together generate the unit ideal. + Return an inverse of ``self`` modulo the ideal `I`, if defined, + i.e., if `I` and ``self`` together generate the unit ideal. """ raise NotImplementedError def divides(self, x): """ - Return True if self divides x. + Return ``True`` if ``self`` divides x. EXAMPLES:: @@ -1946,7 +1975,7 @@ cdef class CommutativeRingElement(RingElement): sage: (x^2+2).divides(x) False - Ticket \#5347 has been fixed:: + :trac:`5347` has been fixed:: sage: K = GF(7) sage: K(3).divides(1) @@ -1974,7 +2003,7 @@ cdef class CommutativeRingElement(RingElement): If x has different parent than `self`, they are first coerced to a common parent if possible. If this coercion fails, it returns a - TypeError. This fixes \#5759 + TypeError. This fixes :trac:`5759` :: sage: Zmod(2)(0).divides(Zmod(2)(0)) @@ -2029,7 +2058,7 @@ cdef class CommutativeRingElement(RingElement): def mod(self, I): r""" - Return a representative for self modulo the ideal I (or the ideal + Return a representative for ``self`` modulo the ideal I (or the ideal generated by the elements of I if I is not an ideal.) EXAMPLE: Integers @@ -2107,7 +2136,7 @@ cdef class CommutativeRingElement(RingElement): def is_square(self, root=False): """ Returns whether or not ring element is a square. If the optional - argument root is True, then also returns the square root (or None, + argument root is ``True``, then also returns the square root (or None, if the it is not a square). INPUT: @@ -2156,17 +2185,17 @@ cdef class CommutativeRingElement(RingElement): INPUT: - - ``extend`` - Whether to make a ring extension containing a square root if self is not a square (default: True) + - ``extend`` - Whether to make a ring extension containing a square root if ``self`` is not a square (default: ``True``) - ``all`` - Whether to return a list of all square roots or just a square root (default: False) - - ``name`` - Required when extend=True and self is not a square. This will be the name of the generator extension. + - ``name`` - Required when extend=``True`` and ``self`` is not a square. This will be the name of the generator extension. OUTPUT: - - if all=False it returns a square root. (throws an error if extend=False and self is not a square) + - if all=False it returns a square root. (throws an error if extend=False and ``self`` is not a square) - - if all=True it returns a list of all the square roots (could be empty if extend=False and self is not a square) + - if all=``True`` it returns a list of all the square roots (could be empty if extend=False and ``self`` is not a square) ALGORITHM: @@ -2261,10 +2290,10 @@ cdef class CommutativeRingElement(RingElement): #all square roots of a non-square should be an empty list if all: return [] - raise ValueError, 'trying to take square root of non-square %s with extend = False' % self + raise ValueError('trying to take square root of non-square %s with extend = False' % self) if name == None: - raise TypeError ("Polynomial is not a square. You must specify the name of the square root when using the default extend = True") + raise TypeError("Polynomial is not a square. You must specify the name of the square root when using the default extend = True") from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing PY = PolynomialRing(P,'y') y = PY.gen() @@ -2461,10 +2490,10 @@ cdef class Vector(ModuleElement): return coercion_model.bin_op(left, right, mul) cpdef Element _dot_product_(Vector left, Vector right): - raise TypeError, arith_error_message(left, right, mul) + raise TypeError(arith_error_message(left, right, mul)) cpdef Vector _pairwise_product_(Vector left, Vector right): - raise TypeError, "unsupported operation for '%s' and '%s'"%(parent_c(left), parent_c(right)) + raise TypeError("unsupported operation for '%s' and '%s'"%(parent_c(left), parent_c(right))) def __div__(self, right): if PY_IS_NUMERIC(right): @@ -2478,10 +2507,10 @@ cdef class Vector(ModuleElement): return W.coordinates(self)[0] / W.coordinates(right)[0] except ArithmeticError: if right.is_zero(): - raise ZeroDivisionError, "division by zero vector" + raise ZeroDivisionError("division by zero vector") else: - raise ArithmeticError, "vector is not in free module" - raise TypeError, arith_error_message(self, right, div) + raise ArithmeticError("vector is not in free module") + raise TypeError(arith_error_message(self, right, div)) def _magma_init_(self, magma): """ @@ -2761,7 +2790,7 @@ def is_Matrix(x): def is_IntegralDomainElement(x): """ - Return True if x is of type IntegralDomainElement. + Return ``True`` if x is of type IntegralDomainElement. """ return IS_INSTANCE(x, IntegralDomainElement) @@ -2772,7 +2801,7 @@ cdef class IntegralDomainElement(CommutativeRingElement): def is_DedekindDomainElement(x): """ - Return True if x is of type DedekindDomainElement. + Return ``True`` if x is of type DedekindDomainElement. """ return IS_INSTANCE(x, DedekindDomainElement) @@ -2781,19 +2810,20 @@ cdef class DedekindDomainElement(IntegralDomainElement): def is_PrincipalIdealDomainElement(x): """ - Return True if x is of type PrincipalIdealDomainElement. + Return ``True`` if x is of type PrincipalIdealDomainElement. """ return IS_INSTANCE(x, PrincipalIdealDomainElement) cdef class PrincipalIdealDomainElement(DedekindDomainElement): def lcm(self, right): """ - Returns the least common multiple of self and right. + Returns the least common multiple of ``self`` and right. """ if not PY_TYPE_CHECK(right, Element) or not ((right)._parent is self._parent): return coercion_model.bin_op(self, right, lcm) return self._lcm(right) + # This is pretty nasty low level stuff. The idea is to speed up construction # of EuclideanDomainElements (in particular Integers) by skipping some tp_new # calls up the inheritance tree. @@ -2801,7 +2831,7 @@ PY_SET_TP_NEW(EuclideanDomainElement, Element) def is_EuclideanDomainElement(x): """ - Return True if x is of type EuclideanDomainElement. + Return ``True`` if x is of type EuclideanDomainElement. """ return IS_INSTANCE(x, EuclideanDomainElement) @@ -2818,7 +2848,7 @@ cdef class EuclideanDomainElement(PrincipalIdealDomainElement): def __divmod__(self, other): """ - Return the quotient and remainder of self divided by other. + Return the quotient and remainder of ``self`` divided by other. EXAMPLES:: @@ -2838,14 +2868,14 @@ cdef class EuclideanDomainElement(PrincipalIdealDomainElement): def __floordiv__(self,right): """ - Quotient of division of self by other. This is denoted //. + Quotient of division of ``self`` by other. This is denoted //. """ Q, _ = self.quo_rem(right) return Q def __mod__(self, other): """ - Remainder of division of self by other. + Remainder of division of ``self`` by other. EXAMPLES:: @@ -2860,7 +2890,7 @@ cdef class EuclideanDomainElement(PrincipalIdealDomainElement): def is_FieldElement(x): """ - Return True if x is of type FieldElement. + Return ``True`` if x is of type FieldElement. """ return IS_INSTANCE(x, FieldElement) @@ -2871,7 +2901,7 @@ cdef class FieldElement(CommutativeRingElement): def is_unit(self): """ - Return True if self is a unit in its parent ring. + Return ``True`` if ``self`` is a unit in its parent ring. EXAMPLES:: @@ -2896,7 +2926,7 @@ cdef class FieldElement(CommutativeRingElement): def _lcm(self, FieldElement other): """ - Return the least common multiple of self and other. + Return the least common multiple of ``self`` and other. """ if self.is_zero() and other.is_zero(): return self @@ -2926,7 +2956,7 @@ cdef class FieldElement(CommutativeRingElement): def divides(self, FieldElement other): r""" - Check whether self divides other, for field elements. + Check whether ``self`` divides other, for field elements. Since this is a field, all values divide all other values, except that zero does not divide any non-zero values. @@ -2949,7 +2979,17 @@ cdef class FieldElement(CommutativeRingElement): def is_AlgebraElement(x): """ - Return True if x is of type AlgebraElement. + Return ``True`` if x is of type AlgebraElement. + + TESTS:: + + sage: from sage.structure.element import is_AlgebraElement + sage: R. = FreeAlgebra(QQ,2) + sage: is_AlgebraElement(x*y) + True + + sage: is_AlgebraElement(1) + False """ return IS_INSTANCE(x, AlgebraElement) @@ -2958,7 +2998,7 @@ cdef class AlgebraElement(RingElement): def is_CommutativeAlgebraElement(x): """ - Return True if x is of type CommutativeAlgebraElement. + Return ``True`` if x is of type CommutativeAlgebraElement. """ return IS_INSTANCE(x, CommutativeAlgebraElement) @@ -2967,7 +3007,16 @@ cdef class CommutativeAlgebraElement(CommutativeRingElement): def is_InfinityElement(x): """ - Return True if x is of type InfinityElement. + Return ``True`` if x is of type InfinityElement. + + TESTS:: + + sage: from sage.structure.element import is_InfinityElement + sage: is_InfinityElement(1) + False + + sage: is_InfinityElement(oo) + True """ return IS_INSTANCE(x, InfinityElement) @@ -3040,12 +3089,12 @@ cdef class CoercionModel: cpdef canonical_coercion(self, x, y): if parent_c(x) is parent_c(y): return x,y - raise TypeError, "no common canonical parent for objects with parents: '%s' and '%s'"%(parent_c(x), parent_c(y)) + raise TypeError("no common canonical parent for objects with parents: '%s' and '%s'"%(parent_c(x), parent_c(y))) cpdef bin_op(self, x, y, op): if parent_c(x) is parent_c(y): return op(x,y) - raise TypeError, arith_error_message(x,y,op) + raise TypeError(arith_error_message(x,y,op)) import coerce cdef CoercionModel coercion_model = coerce.CoercionModel_cache_maps() @@ -3267,19 +3316,36 @@ coerce_binop = NamedBinopMethod ############################################################################### -def lcm(x,y): +def lcm(x, y): + """ + TESTS:: + + sage: lcm(3,-4) + 12 + """ from sage.rings.arith import lcm - return lcm(x,y) + return lcm(x, y) -def gcd(x,y): - from sage.rings.arith import gcd - return gcd(x,y) +def gcd(x, y): + """ + TESTS:: -def xgcd(x,y): - from sage.rings.arith import xgcd - return xgcd(x,y) + sage: gcd(12,15) + 3 + """ + from sage.rings.arith import gcd + return gcd(x, y) +def xgcd(x, y): + """ + TESTS:: + sage: x = polygen(QQ) + sage: xgcd(x^3 - 1, x^2 - 1) + (x - 1, 1, -x) + """ + from sage.rings.arith import xgcd + return xgcd(x, y) ###################### @@ -3331,7 +3397,7 @@ cdef generic_power_c(a, nn, one): from sage.rings.integer import Integer n = int(Integer(nn)) except TypeError: - raise NotImplementedError, "non-integral exponents not supported" + raise NotImplementedError("non-integral exponents not supported") if not n: if one is None: