passagemath-objects 10.6.41__cp314-cp314t-macosx_13_0_arm64.whl

sage/misc/fast_methods.pxd

@@ -0,0 +1,20 @@
+# sage_setup: distribution = sagemath-objects
+cdef extern from "Python.h":
+    cdef size_t SIZEOF_VOID_P
+
+cdef class FastHashable_class:
+    cdef Py_ssize_t _hash
+
+cdef inline long hash_by_id(void * p) noexcept:
+    r"""
+    This function is a copy paste from the default Python hash function.
+    """
+    cdef long x
+    cdef size_t y = <size_t>p
+    # bottom 3 or 4 bits are likely to be 0; rotate y by 4 to avoid
+    # excessive hash collisions for dicts and sets
+    y = (y >> 4) | (y << (8 * SIZEOF_VOID_P - 4))
+    x = <long>y
+    if x == -1:
+        x = -2
+    return x

sage/misc/fast_methods.pyx

@@ -0,0 +1,351 @@
+# sage_setup: distribution = sagemath-objects
+"""
+Fast methods via Cython
+
+This module provides extension classes with useful methods of cython speed,
+that python classes can inherit.
+
+.. NOTE::
+
+    This module provides a cython base class :class:`WithEqualityById`
+    implementing unique instance behaviour, and a cython base class
+    :class:`FastHashable_class`, which has a quite fast hash
+    whose value can be freely chosen at initialisation time.
+
+AUTHOR:
+
+- Simon King (2013-02): Original version
+- Simon King (2013-10): Add :class:`Singleton`
+"""
+
+# ****************************************************************************
+#       Copyright (C) 2013 Simon A. King <simon.king at uni-jena.de>
+#
+# 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/
+# ****************************************************************************
+
+from sage.misc.classcall_metaclass import ClasscallMetaclass, typecall
+from sage.misc.constant_function import ConstantFunction
+
+from cpython.object cimport Py_EQ, Py_NE
+
+
+cdef class WithEqualityById:
+    """
+    Provide hash and equality test based on identity.
+
+    .. NOTE::
+
+        This class provides the unique representation behaviour of
+        :class:`~sage.structure.unique_representation.UniqueRepresentation`,
+        together with :class:`~sage.structure.unique_representation.CachedRepresentation`.
+
+    EXAMPLES:
+
+    Any instance of :class:`~sage.structure.unique_representation.UniqueRepresentation`
+    inherits from :class:`WithEqualityById`.
+    ::
+
+        sage: class MyParent(Parent):
+        ....:   def __init__(self, x):
+        ....:       self.x = x
+        ....:   def __hash__(self):
+        ....:       return hash(self.x)
+        sage: class MyUniqueParent(UniqueRepresentation, MyParent): pass
+        sage: issubclass(MyUniqueParent, sage.misc.fast_methods.WithEqualityById)
+        True
+
+    Inheriting from :class:`WithEqualityById` provides unique representation
+    behaviour::
+
+        sage: a = MyUniqueParent(1)
+        sage: b = MyUniqueParent(2)
+        sage: c = MyUniqueParent(1)
+        sage: a is c
+        True
+        sage: d = MyUniqueParent(-1)
+        sage: a == d
+        False
+
+    The hash inherited from ``MyParent`` is replaced by a hash that coincides
+    with :class:`object`'s hash::
+
+        sage: hash(a) == hash(a.x)
+        False
+        sage: hash(a) == object.__hash__(a)
+        True
+
+    .. WARNING::
+
+        It is possible to inherit from
+        :class:`~sage.structure.unique_representation.UniqueRepresentation`
+        and then overload equality test in a way that destroys the unique
+        representation property. We strongly recommend against it!  You should
+        use :class:`~sage.structure.unique_representation.CachedRepresentation`
+        instead.
+
+    ::
+
+        sage: class MyNonUniqueParent(MyUniqueParent):
+        ....:   def __eq__(self, other):
+        ....:       return self.x^2 == other.x^2
+        sage: a = MyNonUniqueParent(1)
+        sage: d = MyNonUniqueParent(-1)
+        sage: a is MyNonUniqueParent(1)
+        True
+        sage: a == d
+        True
+        sage: a is d
+        False
+    """
+    def __hash__(self):
+        """
+        The hash provided by this class coincides with that of ``<class 'object'>``.
+
+        TESTS::
+
+            sage: class MyParent(Parent):
+            ....:   def __init__(self, x):
+            ....:       self.x = x
+            ....:   def __hash__(self):
+            ....:       return hash(self.x)
+            sage: class MyUniqueParent(UniqueRepresentation, MyParent): pass
+            sage: issubclass(MyUniqueParent, sage.misc.fast_methods.WithEqualityById)
+            True
+            sage: a = MyUniqueParent(1)
+            sage: hash(a) == hash(a.x)
+            False
+            sage: hash(a) == object.__hash__(a)
+            True
+
+            sage: from sage.misc.fast_methods import WithEqualityById
+            sage: o1 = WithEqualityById()
+            sage: o2 = WithEqualityById()
+            sage: hash(o1) == hash(o2)
+            False
+        """
+        # This is the default hash function in Python's object.c:
+        return hash_by_id(<void *>self)
+
+    def __richcmp__(self, other, int op):
+        """
+        Equality test provided by this class is by identity.
+
+        TESTS::
+
+            sage: class MyParent(Parent):
+            ....:   def __init__(self, x):
+            ....:       self.x = x
+            ....:   def __hash__(self):
+            ....:       return hash(self.x)
+            sage: class MyUniqueParent(UniqueRepresentation, MyParent): pass
+            sage: issubclass(MyUniqueParent, sage.misc.fast_methods.WithEqualityById)
+            True
+            sage: a = MyUniqueParent(1)
+            sage: b = MyUniqueParent(-1)
+
+        Equality test takes into account identity::
+
+            sage: a == b
+            False
+
+        When comparing with an object which is not an instance of
+        ``WithEqualityById``, the other object determines the
+        comparison::
+
+            sage: class AlwaysEqual:
+            ....:     def __eq__(self, other):
+            ....:         return True
+            sage: AlwaysEqual() == a
+            True
+            sage: a == AlwaysEqual()
+            True
+
+        Check that :issue:`19628` is fixed::
+
+            sage: from sage.misc.lazy_import import LazyImport
+            sage: lazyQQ = LazyImport('sage.rings.rational_field', 'QQ')
+            sage: PolynomialRing(lazyQQ, 'ijk') is PolynomialRing(QQ, 'ijk')
+            True
+            sage: PolynomialRing(QQ, 'ijkl') is PolynomialRing(lazyQQ, 'ijkl')
+            True
+        """
+        # This only makes sense if "other" is also of type WithEqualityById
+        if type(self) is not type(other):
+            if not isinstance(other, WithEqualityById):
+                return NotImplemented
+
+        if op == Py_EQ:
+            return self is other
+        elif op == Py_NE:
+            return self is not other
+        return NotImplemented
+
+
+cdef class FastHashable_class:
+    """
+    A class that has a fast hash method, returning a pre-assigned value.
+
+    .. NOTE::
+
+        This is for internal use only. The class has a cdef attribute
+        ``_hash``, that needs to be assigned (for example, by calling
+        the init method, or by a direct assignment using
+        cython). This is slower than using :func:`provide_hash_by_id`,
+        but has the advantage that the hash can be prescribed, by
+        assigning a cdef attribute ``_hash``.
+
+    TESTS::
+
+        sage: from sage.misc.fast_methods import FastHashable_class
+        sage: H = FastHashable_class(123)
+        sage: hash(H)
+        123
+    """
+    def __init__(self, h):
+        """
+        TESTS::
+
+            sage: from sage.misc.fast_methods import FastHashable_class
+            sage: H = FastHashable_class(123)
+            sage: hash(H)   # indirect doctest
+            123
+        """
+        self._hash = h
+
+    def __hash__(self):
+        """
+        TESTS::
+
+            sage: from sage.misc.fast_methods import FastHashable_class
+            sage: H = FastHashable_class(123)
+            sage: hash(H)   # indirect doctest
+            123
+        """
+        return self._hash
+
+
+class Singleton(WithEqualityById, metaclass=ClasscallMetaclass):
+    """
+    A base class for singletons.
+
+    A singleton is a class that allows to create not more than a
+    single instance. This instance can also belong to a subclass, but
+    it is not possible to have several subclasses of a singleton all
+    having distinct unique instances.
+
+    In order to create a singleton, just add :class:`Singleton`
+    to the list of base classes::
+
+        sage: from sage.misc.fast_methods import Singleton
+        sage: class C(Singleton, SageObject):
+        ....:     def __init__(self):
+        ....:         print("creating singleton")
+        sage: c = C()
+        creating singleton
+        sage: c2 = C()
+        sage: c is c2
+        True
+
+    The unique instance of a singleton stays in memory as long as the
+    singleton itself does.
+
+    Pickling, copying, hashing, and comparison are provided for by
+    :class:`Singleton` according to the singleton paradigm. Note
+    that pickling fails if the class is replaced by a sub-sub-class
+    after creation of the instance::
+
+        sage: class D(C):
+        ....:     pass
+        sage: import __main__      # This is only needed ...
+        sage: __main__.C = C       # ... in doctests
+        sage: __main__.D = D       # same here, only in doctests
+        sage: orig = type(c)
+        sage: c.__class__ = D
+        sage: orig == type(c)
+        False
+        sage: loads(dumps(c))
+        Traceback (most recent call last):
+        ...
+        AssertionError: <class '__main__.D'> is not a direct subclass of <class 'sage.misc.fast_methods.Singleton'>
+    """
+    @staticmethod
+    def __classcall__(cls):
+        """
+        Create an instance ``O`` of the given class ``cls``, and make it
+        so that in future both ``cls.__call__`` and ``O.__class__.__call__``
+        are constant functions returning ``O``.
+
+        EXAMPLES::
+
+            sage: from sage.misc.fast_methods import Singleton
+            sage: class C(Singleton, Parent):
+            ....:     def __init__(self):
+            ....:         print("creating singleton")
+            ....:         Parent.__init__(self, base=ZZ, category=Rings())
+            sage: c = C()
+            creating singleton
+            sage: import __main__      # This is only needed ...
+            sage: __main__.C = C       # ... in doctests
+            sage: loads(dumps(c)) is copy(c) is C()  # indirect doctest
+            True
+        """
+        assert cls.mro()[1] == Singleton, "{} is not a direct subclass of {}".format(cls, Singleton)
+        res = typecall(cls)
+        cf = ConstantFunction(res)
+        cls._set_classcall(cf)
+        res.__class__._set_classcall(cf)
+        return res
+
+    def __copy__(self):
+        """
+        There is a unique instance of a singleton, hence, copying
+        returns ``self``.
+
+        EXAMPLES::
+
+            sage: from sage.misc.fast_methods import Singleton
+            sage: class C(Singleton, Parent):
+            ....:     def __init__(self):
+            ....:         print("creating singleton")
+            ....:         Parent.__init__(self, base=ZZ, category=Rings())
+            sage: c = C()
+            creating singleton
+            sage: import __main__      # This is only needed ...
+            sage: __main__.C = C       # ... in doctests
+            sage: loads(dumps(c)) is copy(c) is C()  # indirect doctest
+            True
+        """
+        return self
+
+    def __reduce__(self):
+        """
+        There is a unique instance of a singleton, hence, pickling
+        returns ``self``.
+
+        EXAMPLES::
+
+            sage: from sage.misc.fast_methods import Singleton
+            sage: class C(Singleton, Parent):
+            ....:     def __init__(self):
+            ....:         print("creating singleton")
+            ....:         Parent.__init__(self, base=ZZ, category=Rings())
+            ....:
+            sage: c = C()
+            creating singleton
+            sage: import __main__      # This is only needed ...
+            sage: __main__.C = C       # ... in doctests
+            sage: loads(dumps(c)) is copy(c) is C()  # indirect doctest
+            True
+
+        The pickle data mainly consist of the class of the unique instance,
+        which may be a subclass of the original class used to create the
+        instance.If the class is replaced by a sub-sub-class after creation
+        of the instance, pickling fails. See the doctest
+        in :class:`Singleton`.
+        """
+        return self.__class__, ()

sage/misc/flatten.py

@@ -0,0 +1,90 @@
+# sage_setup: distribution = sagemath-objects
+"Flatten nested lists"
+
+import sys
+
+
+def flatten(in_list, ltypes=(list, tuple), max_level=sys.maxsize):
+    """
+    Flatten a nested list.
+
+    INPUT:
+
+    - ``in_list`` -- list or tuple
+    - ``ltypes`` -- (optional) list of particular types to flatten
+    - ``max_level`` -- the maximum level to flatten
+
+    OUTPUT: a flat list of the entries of ``in_list``
+
+    EXAMPLES::
+
+       sage: flatten([[1,1],[1],2])
+       [1, 1, 1, 2]
+       sage: flatten([[1,2,3], (4,5), [[[1],[2]]]])
+       [1, 2, 3, 4, 5, 1, 2]
+       sage: flatten([[1,2,3], (4,5), [[[1],[2]]]], max_level=1)
+       [1, 2, 3, 4, 5, [[1], [2]]]
+       sage: flatten([[[3],[]]],max_level=0)
+       [[[3], []]]
+       sage: flatten([[[3],[]]],max_level=1)
+       [[3], []]
+       sage: flatten([[[3],[]]],max_level=2)
+       [3]
+
+    In the following example, the vector is not flattened because
+    it is not given in the ``ltypes`` input. ::
+
+       sage: flatten((['Hi', 2, vector(QQ, [1,2,3])], (4,5,6)))                         # needs sage.modules
+       ['Hi', 2, (1, 2, 3), 4, 5, 6]
+
+    We give the vector type and then even the vector gets flattened::
+
+       sage: tV = sage.modules.vector_rational_dense.Vector_rational_dense              # needs sage.modules
+       sage: flatten((['Hi', 2, vector(QQ, [1,2,3])], (4,5,6)),                         # needs sage.modules
+       ....:         ltypes=(list, tuple, tV))
+       ['Hi', 2, 1, 2, 3, 4, 5, 6]
+
+    We flatten a finite field. ::
+
+       sage: flatten(GF(5))
+       [0, 1, 2, 3, 4]
+       sage: flatten([GF(5)])
+       [Finite Field of size 5]
+       sage: tGF = type(GF(5))
+       sage: flatten([GF(5)], ltypes=(list, tuple, tGF))
+       [0, 1, 2, 3, 4]
+
+    Degenerate cases::
+
+        sage: flatten([[],[]])
+        []
+        sage: flatten([[[]]])
+        []
+    """
+    index = 0
+    current_level = 0
+    new_list = list(in_list)
+    level_list = [0] * len(in_list)
+
+    while index < len(new_list):
+        len_v = True
+        while isinstance(new_list[index], ltypes) and current_level < max_level:
+            v = list(new_list[index])
+            len_v = len(v)
+            new_list[index: index + 1] = v
+            old_level = level_list[index]
+            level_list[index: index + 1] = [0] * len_v
+            if len_v:
+                current_level += 1
+                level_list[index + len_v - 1] = old_level + 1
+            else:
+                current_level -= old_level
+                index -= 1
+                break
+
+        # If len_v == 0, then index points to a previous element, so we
+        # do not need to do anything.
+        if len_v:
+            current_level -= level_list[index]
+        index += 1
+    return new_list

sage/misc/fpickle.pyx

@@ -0,0 +1,177 @@
+# sage_setup: distribution = sagemath-objects
+# cython: old_style_globals=True
+# cython: binding=True
+"""
+Function pickling
+
+REFERENCE: The python cookbook.
+"""
+import copyreg
+import pickle
+import sys
+import types
+
+
+def code_ctor(*args):
+    """
+    EXAMPLES:
+
+    This indirectly tests this function. ::
+
+        sage: def foo(a, b, c=10): return a+b+c
+        sage: sage.misc.fpickle.reduce_code(foo.__code__)
+        (<cyfunction code_ctor at ...>, ...)
+        sage: unpickle_function(pickle_function(foo))
+        <function foo at ...>
+    """
+    return types.CodeType(*args)
+
+
+def reduce_code(co):
+    """
+    EXAMPLES::
+
+        sage: def foo(N): return N+1
+        sage: sage.misc.fpickle.reduce_code(foo.__code__)
+        (<cyfunction code_ctor at ...>, ...)
+
+    Test that the constructed code matches the original code::
+
+        sage: ctor, args = sage.misc.fpickle.reduce_code(foo.__code__)
+        sage: ctor(*args) == foo.__code__
+        True
+    """
+    if co.co_freevars or co.co_cellvars:
+        raise ValueError("Cannot pickle code objects from closures")
+
+    co_args = (co.co_argcount,)
+    co_args += (co.co_posonlyargcount,)
+    co_args += (co.co_kwonlyargcount, co.co_nlocals,
+                co.co_stacksize, co.co_flags, co.co_code,
+                co.co_consts, co.co_names, co.co_varnames, co.co_filename,
+                co.co_name)
+    if sys.version_info.minor >= 11:
+        co_args += (co.co_qualname, co.co_firstlineno,
+                    co.co_linetable, co.co_exceptiontable)
+    else:
+        co_args += (co.co_firstlineno, co.co_lnotab)
+
+    return (code_ctor, co_args)
+
+
+copyreg.pickle(types.CodeType, reduce_code)
+
+
+def pickle_function(func):
+    """
+    Pickle the Python function func.  This is not a normal pickle; you
+    must use the unpickle_function method to unpickle the pickled
+    function.
+
+    NOTE: This does not work on all functions, but does work on
+    'surprisingly' many functions.  In particular, it does not
+    work on functions that includes nested functions.
+
+    INPUT:
+
+    - ``func`` -- a Python function
+
+    OUTPUT: string
+
+    EXAMPLES::
+
+        sage: def f(N): return N+1
+        ...
+        sage: g = pickle_function(f)
+        sage: h = unpickle_function(g)
+        sage: h(10)
+        11
+    """
+    return pickle.dumps(func.__code__)
+
+
+def unpickle_function(pickled):
+    """
+    Unpickle a pickled function.
+
+    EXAMPLES::
+
+        sage: def f(N, M): return N*M
+        ...
+        sage: unpickle_function(pickle_function(f))(3,5)
+        15
+    """
+    recovered = pickle.loads(pickled)
+    return types.FunctionType(recovered, globals())
+
+
+def call_pickled_function(fpargs):
+    try:
+        import sage.all as toplevel
+    except ImportError:
+        import sage.all__sagemath_categories as toplevel
+    (fp, (args, kwds)) = fpargs
+    f = eval("unpickle_function(fp)", toplevel.__dict__, {'fp': fp})
+    res = eval("f(*args, **kwds)", toplevel.__dict__,
+               {'args': args, 'kwds': kwds, 'f': f})
+    return ((args, kwds), res)
+
+
+# The following four methods are taken from twisted.persisted.styles - the
+# import of twisted.persisted.styles takes a long time and we do not use
+# most functionality it provides
+def pickleMethod(method):
+    'support function for copyreg to pickle method refs'
+
+    if isinstance(method.__self__, type):
+        # This is a class method, so get it from the type directly
+        return (getattr, (method.__self__, method.__func__.__name__))
+    else:
+        cls = method.__self__.__class__
+        return (unpickleMethod, (method.__func__.__name__, method.__self__, cls))
+
+
+def unpickleMethod(im_name,
+                   __self__,
+                   im_class):
+    'support function for copyreg to unpickle method refs'
+    try:
+        unbound = getattr(im_class, im_name)
+        if __self__ is None:
+            return unbound
+
+        bound = types.MethodType(unbound, __self__)
+        return bound
+    except AttributeError:
+        assert __self__ is not None, "No recourse: no instance to guess from."
+        # Attempt a common fix before bailing -- if classes have
+        # changed around since we pickled this method, we may still be
+        # able to get it by looking on the instance's current class.
+        unbound = getattr(__self__.__class__, im_name)
+
+        bound = types.MethodType(unbound, __self__)
+        return bound
+
+
+copyreg.pickle(types.MethodType,
+               pickleMethod,
+               unpickleMethod)
+
+oldModules = {}
+
+
+def pickleModule(module):
+    'support function for copyreg to pickle module refs'
+    return unpickleModule, (module.__name__,)
+
+
+def unpickleModule(name):
+    'support function for copyreg to unpickle module refs'
+    if name in oldModules:
+        name = oldModules[name]
+    return __import__(name, {}, {}, 'x')
+
+
+copyreg.pickle(types.ModuleType,
+               pickleModule,
+               unpickleModule)

sage/misc/function_mangling.pxd

@@ -0,0 +1,11 @@
+# sage_setup: distribution = sagemath-objects
+cdef class ArgumentFixer:
+    cdef public object f
+    cdef public int _ndefault
+    cdef public int _nargs
+    cdef tuple _arg_names
+    cdef bint _classmethod
+    cdef dict _defaults
+    cdef public tuple _default_tuple
+
+    cdef fix_to_pos_args_kwds(self, tuple args, dict kwargs)