passagemath-objects 10.6.41__cp312-cp312-win_amd64.whl

sage/structure/mutability.pyx

@@ -0,0 +1,348 @@
+# sage_setup: distribution = sagemath-objects
+"""
+Mutability Cython Implementation
+"""
+##########################################################################
+#
+#   Sage: Open Source Mathematical Software
+#
+#       Copyright (C) 2006 William Stein <wstein@gmail.com>
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#                  https://www.gnu.org/licenses/
+##########################################################################
+
+cimport cython
+from sage.misc.decorators import sage_wraps
+
+cdef class Mutability:
+    r"""
+    Class to mix in mutability feature.
+
+    EXAMPLES::
+
+        sage: class A(SageObject, Mutability):
+        ....:     def __init__(self, val):
+        ....:         self._val = val
+        ....:     def change(self, val):
+        ....:         self._require_mutable()
+        ....:         self._val = val
+        ....:     def __hash__(self):
+        ....:         self._require_immutable()
+        ....:         return hash(self._val)
+        sage: a = A(4)
+        sage: a._val
+        4
+        sage: a.change(6); a._val
+        6
+        sage: hash(a)
+        Traceback (most recent call last):
+        ...
+        ValueError: object is mutable; please make it immutable first
+        sage: a.set_immutable()
+        sage: a.change(4)
+        Traceback (most recent call last):
+        ...
+        ValueError: object is immutable; please change a copy instead
+        sage: hash(a)
+        6
+    """
+
+    def __init__(self, is_immutable=False):
+        r"""
+        TESTS::
+
+            sage: class A(SageObject, Mutability):
+            ....:     def __init__(self, val):
+            ....:         self._val = val
+            ....:     def change(self, val):
+            ....:         self._require_mutable()
+            ....:         self._val = val
+            ....:     def __hash__(self):
+            ....:         self._require_immutable()
+            ....:         return hash(self._val)
+            sage: a = A(4)
+            sage: TestSuite(a).run(skip ='_test_pickling')
+        """
+        self._is_immutable = is_immutable
+
+    cpdef _require_mutable(self):
+        r"""
+        Whenever mutability is required, this method can be called.
+
+        EXAMPLES::
+
+            sage: class A(SageObject, Mutability):
+            ....:     def __init__(self, val):
+            ....:         self._val = val
+            ....:     def change(self, val):
+            ....:         self._require_mutable()
+            ....:         self._val = val
+            ....:     def __hash__(self):
+            ....:         self._require_immutable()
+            ....:         return hash(self._val)
+            sage: a = A(4)
+            sage: a.set_immutable()
+            sage: a.change(6)
+            Traceback (most recent call last):
+            ...
+            ValueError: object is immutable; please change a copy instead
+        """
+        if self._is_immutable:
+            raise ValueError("object is immutable; please change a copy instead")
+
+    cpdef _require_immutable(self):
+        r"""
+        Whenever immutability is required, this method can be called.
+
+        EXAMPLES::
+
+            sage: class A(SageObject, Mutability):
+            ....:     def __init__(self, val):
+            ....:         self._val = val
+            ....:     def change(self, val):
+            ....:         self._require_mutable()
+            ....:         self._val = val
+            ....:     def __hash__(self):
+            ....:         self._require_immutable()
+            ....:         return hash(self._val)
+            sage: a = A(4)
+            sage: hash(a)
+            Traceback (most recent call last):
+            ...
+            ValueError: object is mutable; please make it immutable first
+        """
+        if not self._is_immutable:
+            raise ValueError("object is mutable; please make it immutable first")
+
+    def set_immutable(self):
+        """
+        Make this object immutable, so it can never again be changed.
+
+        EXAMPLES::
+
+            sage: v = Sequence([1,2,3,4/5])
+            sage: v[0] = 5
+            sage: v
+            [5, 2, 3, 4/5]
+            sage: v.set_immutable()
+            sage: v[3] = 7
+            Traceback (most recent call last):
+            ...
+            ValueError: object is immutable; please change a copy instead.
+        """
+        self._is_immutable = 1
+
+    cpdef bint is_immutable(self) noexcept:
+        """
+        Return ``True`` if this object is immutable (cannot be changed)
+        and ``False`` if it is not.
+
+        To make this object immutable use self.set_immutable().
+
+        EXAMPLES::
+
+            sage: v = Sequence([1,2,3,4/5])
+            sage: v[0] = 5
+            sage: v
+            [5, 2, 3, 4/5]
+            sage: v.is_immutable()
+            False
+            sage: v.set_immutable()
+            sage: v.is_immutable()
+            True
+        """
+        return self._is_immutable
+
+    cpdef bint is_mutable(self) noexcept:
+        """
+        Return ``True`` if this object is mutable (can be changed)
+        and ``False`` if it is not.
+
+        To make this object immutable use ``self.set_immutable()``.
+
+        EXAMPLES::
+
+            sage: v = Sequence([1,2,3,4/5])
+            sage: v[0] = 5
+            sage: v
+            [5, 2, 3, 4/5]
+            sage: v.is_mutable()
+            True
+            sage: v.set_immutable()
+            sage: v.is_mutable()
+            False
+        """
+        return not self._is_immutable
+
+    def __getstate__(self):
+        r"""
+        Get the current state of ``self`` including the mutability status.
+
+        TESTS::
+
+            sage: class A(SageObject, Mutability):
+            ....:     def __init__(self, val):
+            ....:         self._val = val
+            ....:     def change(self, val):
+            ....:         self._require_mutable()
+            ....:         self._val = val
+            ....:     def __hash__(self):
+            ....:         self._require_immutable()
+            ....:         return hash(self._val)
+            sage: a = A(4)
+            sage: a.__dict__
+            {'_val': 4}
+            sage: a.__getstate__()
+            {'_is_immutable': False, '_val': 4}
+            sage: a.__reduce__()  # indirect doctest
+            (<function _reconstructor at ...>,
+             (<class '__main__.A'>,
+              <class 'sage.structure.sage_object.SageObject'>,
+              <sage.structure.sage_object.SageObject object at ...>),
+             {'_is_immutable': False, '_val': 4})
+        """
+        state = getattr(self, '__dict__', {})
+        state['_is_immutable'] = self._is_immutable
+        return state
+
+    def __setstate__(self, state):
+        r"""
+        Set the state of ``self`` from the dictionary ``state`` including the
+        mutability status.
+
+        TESTS::
+
+            sage: class A(SageObject, Mutability):
+            ....:     def __init__(self, val):
+            ....:         self._val = val
+            ....:     def change(self, val):
+            ....:         self._require_mutable()
+            ....:         self._val = val
+            ....:     def __hash__(self):
+            ....:         self._require_immutable()
+            ....:         return hash(self._val)
+            sage: a = A(4)
+            sage: a.is_immutable()
+            False
+            sage: d = a.__getstate__(); d
+            {'_is_immutable': False, '_val': 4}
+            sage: d['_is_immutable'] = True
+            sage: a.__setstate__(d)
+            sage: a.is_immutable()
+            True
+            sage: a.__getstate__()
+            {'_is_immutable': True, '_val': 4}
+        """
+        if hasattr(self, '__dict__'):
+            self.__dict__ = state
+        self._is_immutable = state['_is_immutable']
+
+
+##########################################################################
+# Method decorators for mutating methods resp. methods that assume immutability
+
+def require_mutable(f):
+    """
+    A decorator that requires mutability for a method to be called.
+
+    .. NOTE::
+
+        Objects whose methods use this decorator should have an attribute
+        ``_is_immutable``. Otherwise, the object is assumed to be mutable.
+
+    EXAMPLES::
+
+        sage: from sage.structure.mutability import require_mutable, require_immutable
+        sage: class A():
+        ....:     def __init__(self, val):
+        ....:         self._m = val
+        ....:     @require_mutable
+        ....:     def change(self, new_val):
+        ....:         'change self'
+        ....:         self._m = new_val
+        ....:     @require_immutable
+        ....:     def __hash__(self):
+        ....:         'implement hash'
+        ....:         return hash(self._m)
+        sage: a = A(5)
+        sage: a.change(6)
+        sage: hash(a)
+        Traceback (most recent call last):
+        ...
+        ValueError: <class '__main__.A'> instance is mutable, <function ...__hash__ at ...> must not be called
+        sage: a._is_immutable = True
+        sage: hash(a)
+        6
+        sage: a.change(7)   # indirect doctest
+        Traceback (most recent call last):
+        ...
+        ValueError: <class '__main__.A'> instance is immutable, <function ...change at ...> must not be called
+        sage: from sage.misc.sageinspect import sage_getdoc
+        sage: print(sage_getdoc(a.change))
+        change self
+
+    AUTHORS:
+
+    - Simon King <simon.king@uni-jena.de>
+    """
+    @sage_wraps(f)
+    @cython.binding(True)
+    def new_f(self, *args, **kwds):
+        if getattr(self, '_is_immutable', False):
+            raise ValueError("{} instance is immutable, {} must not be called".format(type(self), repr(f)))
+        return f(self, *args, **kwds)
+    return new_f
+
+
+def require_immutable(f):
+    """
+    A decorator that requires immutability for a method to be called.
+
+    .. NOTE::
+
+        Objects whose methods use this decorator should have an attribute
+        ``_is_immutable``. Otherwise, the object is assumed to be mutable.
+
+    EXAMPLES::
+
+        sage: from sage.structure.mutability import require_mutable, require_immutable
+        sage: class A():
+        ....:  def __init__(self, val):
+        ....:      self._m = val
+        ....:  @require_mutable
+        ....:  def change(self, new_val):
+        ....:      'change self'
+        ....:      self._m = new_val
+        ....:  @require_immutable
+        ....:  def __hash__(self):
+        ....:      'implement hash'
+        ....:      return hash(self._m)
+        sage: a = A(5)
+        sage: a.change(6)
+        sage: hash(a)   # indirect doctest
+        Traceback (most recent call last):
+        ...
+        ValueError: <class '__main__.A'> instance is mutable, <function ...__hash__ at ...> must not be called
+        sage: a._is_immutable = True
+        sage: hash(a)
+        6
+        sage: a.change(7)
+        Traceback (most recent call last):
+        ...
+        ValueError: <class '__main__.A'> instance is immutable, <function ...change at ...> must not be called
+        sage: from sage.misc.sageinspect import sage_getdoc
+        sage: print(sage_getdoc(a.__hash__))
+        implement hash
+
+    AUTHORS:
+
+    - Simon King <simon.king@uni-jena.de>
+    """
+    @sage_wraps(f)
+    @cython.binding(True)
+    def new_f(self, *args, **kwds):
+        if not getattr(self,'_is_immutable',False):
+            raise ValueError("{} instance is mutable, {} must not be called".format(type(self), repr(f)))
+        return f(self, *args, **kwds)
+    return new_f

sage/structure/nonexact.py

@@ -0,0 +1,69 @@
+# sage_setup: distribution = sagemath-objects
+r"""
+Precision management for non-exact objects
+
+Manage the default precision for non-exact objects such as power series rings
+or Laurent series rings.
+
+EXAMPLES::
+
+    sage: R.<x> = PowerSeriesRing(QQ)
+    sage: R.default_prec()
+    20
+    sage: cos(x)
+    1 - 1/2*x^2 + 1/24*x^4 - 1/720*x^6 + 1/40320*x^8 - 1/3628800*x^10 +
+     1/479001600*x^12 - 1/87178291200*x^14 + 1/20922789888000*x^16 -
+     1/6402373705728000*x^18 + O(x^20)
+
+::
+
+    sage: R.<x> = PowerSeriesRing(QQ, default_prec=10)
+    sage: R.default_prec()
+    10
+    sage: cos(x)
+    1 - 1/2*x^2 + 1/24*x^4 - 1/720*x^6 + 1/40320*x^8 + O(x^10)
+
+.. NOTE::
+
+    Subclasses of :class:`Nonexact` which require to change the default
+    precision should implement a method ``set_default_prec``.
+"""
+from sage.rings.integer import Integer
+
+
+class Nonexact:
+    r"""
+    A non-exact object with default precision.
+
+    INPUT:
+
+    - ``prec`` -- nonnegative integer representing the default precision of
+      ``self`` (default: 20)
+    """
+    def __init__(self, prec=20):
+        if prec < 0:
+            raise ValueError(f"prec (= {prec}) must be nonnegative")
+        self._default_prec = Integer(prec)
+
+    def default_prec(self):
+        r"""
+        Return the default precision for ``self``.
+
+        EXAMPLES::
+
+            sage: x = polygen(ZZ, 'x')
+            sage: R = QQ[[x]]
+            sage: R.default_prec()
+            20
+
+        ::
+
+            sage: R.<x> = PowerSeriesRing(QQ, default_prec=10)
+            sage: R.default_prec()
+            10
+        """
+        try:
+            return self._default_prec
+        except AttributeError:
+            self._default_prec = 20
+            return self._default_prec

sage/structure/parent.pxd

@@ -0,0 +1,112 @@
+# sage_setup: distribution = sagemath-objects
+# ***************************************************************************
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License 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/
+# ***************************************************************************
+
+cimport sage.structure.category_object
+from sage.structure.coerce_dict cimport MonoDict, TripleDict
+
+cdef class Parent(sage.structure.category_object.CategoryObject):
+    cdef _element_constructor
+    cdef bint _element_init_pass_parent
+    cdef public _convert_method_name
+    cdef public _initial_coerce_list
+    cdef public _initial_action_list
+    cdef public _initial_convert_list
+    cdef readonly bint _coercions_used
+
+    # Flags, see below
+    cdef int flags
+    cdef inline bint get_flag(self, int flag) noexcept:
+        return self.flags & flag
+
+    cpdef register_coercion(self, mor)
+    cpdef register_action(self, action)
+    cpdef register_conversion(self, mor)
+    cpdef register_embedding(self, embedding)
+
+    cpdef bint is_exact(self) except -2
+
+    # Called from the __init__ method to set up coercion.
+    cdef int init_coerce(self, bint warn=*) except -1
+
+    # returns whether or not there is a Morphism from S to self
+    cpdef bint has_coerce_map_from(self, S) except -2
+
+    # returns a Morphism from S to self, or None
+    cpdef coerce_map_from(self, S)
+    cpdef _internal_coerce_map_from(self, S)
+    cpdef _coerce_map_from_(self, S)
+
+    # returns a Map from S to self, or None
+    cpdef convert_map_from(self, S)
+    cpdef _internal_convert_map_from(self, S)
+    cpdef _convert_map_from_(self, S)
+    cdef convert_method_map(self, S, method_name)
+
+    # returns the Action by/on self on/by S
+    # corresponding to op and self_on_left
+    cpdef get_action(self, S, op=*, bint self_on_left=*, self_el=*, S_el=*)
+    cpdef _get_action_(self, S, op, bint self_on_left)
+
+    # coerce x into self
+    cpdef coerce(self, x)
+
+    cpdef an_element(self)
+    cdef public object _cache_an_element
+
+    # For internal use
+    cpdef _generic_convert_map(self, S, category=*)
+    cpdef _generic_coerce_map(self, S)
+    cdef discover_coerce_map_from(self, S)
+    cdef discover_convert_map_from(self, S)
+    cdef discover_action(self, S, op, bint self_on_left, self_el=*, S_el=*)
+
+    # List consisting of Morphisms (from anything to self)
+    # and Parents for which the __call__ method of self
+    # results in natural coercion.
+    # Initialized at ring creation.
+    cdef list _coerce_from_list
+    # List of the domains of the registered coercions, to make
+    # sure that the maps in _coerce_from_list remain valid.
+    # This is important, since they are fundamental for discovering
+    # new coercions by backtracking.
+    cdef list _registered_domains
+    # Hashtable of everything we've (possibly recursively) discovered so far.
+    cdef MonoDict _coerce_from_hash
+
+    # List consisting of Actions (either by or on self)
+    # and Parents for which self._rmul_ and/or self._lmul_
+    # do the correct thing.
+    # Initialized at ring creation.
+    cdef list _action_list
+
+    # List consisting of Morphisms (from anything to self)
+    # and Parents for which the __call__ method of self
+    # does not result in type errors
+    # Initialized at ring creation.
+    cdef list _convert_from_list
+    # Hashtable of everything we've (possibly recursively) discovered so far.
+    cdef MonoDict _convert_from_hash
+    # An optional single Morphism that describes a canonical coercion out of self
+    cdef _embedding
+
+    # Write-only hashtable of all actions discovered using this parent.
+    # This is only needed to keep a strong reference to actions, to
+    # prevent them being garbage collected prematurely.
+    cdef TripleDict _action_hash
+
+
+cdef class Set_generic(Parent):
+    pass
+
+
+# Flags for Parent.flags
+cdef enum:
+    # If this flag is set, call __richcmp__ on elements without
+    # coercion. This allows a completely custom comparison function.
+    Parent_richcmp_element_without_coercion = 1