passagemath-objects 10.6.47__cp311-cp311-macosx_13_0_x86_64.whl

sage/cpython/atexit.pyx

@@ -0,0 +1,269 @@
+# sage_setup: distribution = sagemath-objects
+
+"""Utilities for interfacing with the standard library's atexit module."""
+
+# ****************************************************************************
+#       Copyright (C) 2017 Erik M. Bray <erik.bray@lri.fr>
+#
+# 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/
+# ****************************************************************************
+
+import atexit
+
+
+__all__ = ['restore_atexit']
+
+
+cdef class restore_atexit:
+    r"""
+    Context manager that restores the state of the atexit module to its
+    previous state when exiting the context.
+
+    INPUT:
+
+    - ``run`` -- boolean (default: ``False``); if ``True``, when exiting the
+      context (but before restoring the old exit functions), run all
+      atexit functions which were added inside the context
+
+    - ``clear`` -- boolean (default: equal to ``run``); if ``True``, clear
+      already registered atexit handlers upon entering the context
+
+    .. WARNING::
+
+        The combination ``run=True`` and ``clear=False`` will cause
+        already-registered exit functions to be run twice: once when
+        exiting the context and again when exiting Python.
+
+    EXAMPLES:
+
+    For this example we will wrap the entire example with
+    ``restore_atexit(clear=True)`` so as to start with a fresh atexit
+    module state for the sake of the example.
+
+    Note that the function ``atexit._run_exitfuncs()`` runs all registered
+    handlers, and then clears the list of handlers, so we can use it to test
+    manipulation of the ``atexit`` state::
+
+        sage: import atexit
+        sage: from sage.cpython.atexit import restore_atexit
+        sage: def handler(*args, **kwargs):
+        ....:     import sys
+        ....:     # see https://github.com/sagemath/sage/issues/25270#comment:56
+        ....:     sys.stdout.write(str((args, kwargs)))
+        ....:     sys.stdout.write('\n')
+        sage: atexit.register(handler, 1, 2, c=3)
+        <function handler at 0x...>
+        sage: atexit.register(handler, 4, 5, d=6)
+        <function handler at 0x...>
+        sage: with restore_atexit(clear=True):
+        ....:     atexit._run_exitfuncs()  # Should be none registered
+        ....:     atexit.register(handler, 1, 2, c=3)
+        ....:     with restore_atexit():
+        ....:         atexit._run_exitfuncs()  # Run just registered handler
+        ....:     atexit._run_exitfuncs()  # Handler should be run again
+        <function handler at 0x...>
+        ((1, 2), {'c': 3})
+        ((1, 2), {'c': 3})
+
+    We test the ``run`` option::
+
+        sage: with restore_atexit(run=True):
+        ....:     # this handler is run when exiting the context
+        ....:     _ = atexit.register(handler, 7, 8, e=9)
+        ((7, 8), {'e': 9})
+        sage: with restore_atexit(clear=False, run=True):
+        ....:     # original handlers are run when exiting the context
+        ....:     pass
+        ((4, 5), {'d': 6})
+        ((1, 2), {'c': 3})
+
+    The original handlers are still in place::
+
+        sage: atexit._run_exitfuncs()
+        ((4, 5), {'d': 6})
+        ((1, 2), {'c': 3})
+
+    TESTS::
+
+        sage: from sage.cpython.atexit import (_get_exithandlers,
+        ....:                                  _clear_exithandlers)
+        sage: atexit.register(handler, 1, 2, c=3)
+        <function handler at 0x...>
+        sage: atexit.register(handler, 4, 5, d=6)
+        <function handler at 0x...>
+        sage: print("Initial exit handlers:\n{}".format(_get_exithandlers()))
+        Initial exit handlers:
+        [(<function handler at 0x...>, (1, 2), {'c': 3}),
+         (<function handler at 0x...>, (4, 5), {'d': 6})]
+
+        sage: with restore_atexit():
+        ....:     pass
+        sage: print("After restore_atexit:\n{}".format(_get_exithandlers()))
+        After restore_atexit:
+        [(<function handler at 0x...>, (1, 2), {'c': 3}),
+         (<function handler at 0x...>, (4, 5), {'d': 6})]
+
+        sage: with restore_atexit(clear=True):
+        ....:     print("Exit handlers in context manager: {}".format(
+        ....:           _get_exithandlers()))
+        Exit handlers in context manager: []
+
+        sage: print("After restore_atexit with clear=True:\n{}".format(
+        ....:       _get_exithandlers()))
+        After restore_atexit with clear=True:
+        [(<function handler at 0x...>, (1, 2), {'c': 3}),
+         (<function handler at 0x...>, (4, 5), {'d': 6})]
+        sage: _clear_exithandlers()
+        sage: _get_exithandlers()
+        []
+    """
+
+    cdef list _exithandlers
+    cdef bint _clear, _run
+
+    def __init__(self, *, run=False, clear=None):
+        self._clear = self._run = run
+        if clear is not None:
+            self._clear = clear
+        self._exithandlers = None
+
+    def __enter__(self):
+        self._exithandlers = _get_exithandlers()
+        if self._clear:
+            _clear_exithandlers()
+
+        return self
+
+    def __exit__(self, *exc):
+        if self._run:
+            atexit._run_exitfuncs()
+        _set_exithandlers(self._exithandlers)
+
+from cpython.ref cimport PyObject
+import sys
+
+# Implement a uniform interface for getting atexit callbacks
+cdef extern from *:
+    """
+    #ifndef Py_BUILD_CORE
+    #define Py_BUILD_CORE
+    #endif
+    #undef _PyGC_FINALIZED
+    #include "internal/pycore_interp.h"
+    #include "internal/pycore_pystate.h"
+    
+    // Always define this struct for Cython's use
+    typedef struct {
+        PyObject *func;
+        PyObject *args;
+        PyObject *kwargs;
+    } atexit_callback_struct;
+    
+    #if PY_VERSION_HEX >= 0x030e0000
+    // Python 3.14+: atexit uses a PyList stored in state->callbacks
+    // Note: In Python 3.14 the atexit_state struct changed - callbacks is now a PyObject* (PyList)
+    
+    static PyObject* get_atexit_callbacks_list(PyObject *self) {
+        PyInterpreterState *interp = _PyInterpreterState_GET();
+        // Access the callbacks list directly from the interpreter state
+        // We return a new reference because Cython expects an owned reference
+        PyObject *callbacks = interp->atexit.callbacks;
+        Py_XINCREF(callbacks);
+        return callbacks;
+    }
+    
+    // Dummy function for Python 3.14+ (never called)
+    static atexit_callback_struct** get_atexit_callbacks_array(PyObject *self) {
+        PyErr_SetString(PyExc_RuntimeError, "Python >= 3.14 has no atexit arrays");
+        return NULL;
+    }
+    #else
+    // Python < 3.14: atexit uses C array
+    static atexit_callback_struct** get_atexit_callbacks_array(PyObject *self) {
+        PyInterpreterState *interp = _PyInterpreterState_GET();
+        struct atexit_state state = interp->atexit;
+        // Cast from atexit_callback** to our struct type
+        return (atexit_callback_struct**)state.callbacks;
+    }
+    
+    // Dummy function for Python < 3.14 (never called)
+    static PyObject* get_atexit_callbacks_list(PyObject *self) {
+        PyErr_SetString(PyExc_RuntimeError, "Python < 3.14 has no atexit lists");
+        return NULL;
+    }
+    #endif
+    """
+    # Declare both functions - they exist in all Python versions (one is dummy)
+    object get_atexit_callbacks_list(object module)
+    
+    ctypedef struct atexit_callback_struct:
+        PyObject* func
+        PyObject* args
+        PyObject* kwargs
+    atexit_callback_struct** get_atexit_callbacks_array(object module) except NULL
+
+
+def _get_exithandlers():
+    """Return list of exit handlers registered with the atexit module."""
+    cdef list exithandlers = []
+    cdef atexit_callback_struct ** callbacks
+    cdef atexit_callback_struct callback
+    cdef int idx
+    cdef object kwargs
+    
+    # Python 3.14+ uses a PyList directly
+    if sys.version_info >= (3, 14):
+        callbacks_list = get_atexit_callbacks_list(atexit)
+        if callbacks_list is None:
+            return exithandlers
+        # callbacks is a list of tuples: [(func, args, kwargs), ...]
+        # Normalize kwargs to ensure it's always a dict (not None)
+        # Note: In Python 3.14+, atexit stores callbacks in LIFO order
+        # (most recently registered first), but we return them in FIFO
+        # order (registration order) for consistency with earlier versions
+        for item in reversed(callbacks_list):
+            func, args, kwargs = item
+            if kwargs is None:
+                kwargs = {}
+            exithandlers.append((func, args, kwargs))
+    else:
+        # Python < 3.14 uses C array
+        callbacks = get_atexit_callbacks_array(atexit)
+        for idx in range(atexit._ncallbacks()):
+            callback = callbacks[idx][0]
+            if callback.kwargs:
+                kwargs = <object>callback.kwargs
+            else:
+                kwargs = {}
+            exithandlers.append((<object>callback.func,
+                                 <object>callback.args,
+                                 kwargs))
+    return exithandlers
+
+
+def _set_exithandlers(exithandlers):
+    """
+    Replace the list of exit handlers registered with the atexit module
+    with a new list.
+    """
+
+    # Clear the existing list
+    atexit._clear()
+
+    # We could do this more efficiently by directly rebuilding the array
+    # of atexit_callbacks, but this is much simpler
+    # Note: exithandlers is in registration order (FIFO).
+    # In Python 3.14+, atexit.register prepends to the list (LIFO),
+    # so registering in forward order gives us the correct execution order.
+    for callback in exithandlers:
+        atexit.register(callback[0], *callback[1], **callback[2])
+
+
+def _clear_exithandlers():
+    """Clear the atexit module of all registered exit handlers."""
+
+    atexit._clear()

sage/cpython/builtin_types.pyx

@@ -0,0 +1,7 @@
+# sage_setup: distribution = sagemath-objects
+from cpython.object cimport PyTypeObject
+
+cdef extern from *:
+    PyTypeObject PyWrapperDescr_Type
+
+wrapper_descriptor = <type>(&PyWrapperDescr_Type)

sage/cpython/cython_metaclass.h

@@ -0,0 +1,117 @@
+/* sage_setup: distribution = sagemath-objects
+ */
+/*****************************************************************************
+*       Copyright (C) 2015 Jeroen Demeyer <jdemeyer@cage.ugent.be>
+*
+* 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/
+*****************************************************************************/
+
+/* Tuple (None, None, None), initialized as needed */
+static PyObject* NoneNoneNone;
+
+/* All args flags of a PyMethod */
+#define METH_ALLARGS (METH_VARARGS|METH_KEYWORDS|METH_NOARGS|METH_O)
+
+/* Given an unbound method "desc" (this is not checked!) with only a
+ * single "self" argument, call "desc(self)" without checking "self".
+ * This can in particular be used to call any method as class or
+ * static method. */
+static CYTHON_INLINE PyObject* PyMethodDescr_CallSelf(PyMethodDescrObject* desc, PyObject* self)
+{
+    PyMethodDef* meth = desc->d_method;
+
+    /* This must be a METH_NOARGS method */
+    if (meth == NULL || (meth->ml_flags & METH_ALLARGS) != METH_NOARGS)
+    {
+        PyErr_SetString(PyExc_TypeError,
+                "PyMethodDescr_CallSelf requires a method without arguments");
+        return NULL;
+    }
+
+    return meth->ml_meth(self, NULL);
+}
+
+/*
+ * This function calls PyType_Ready(t) and then calls
+ * t.__getmetaclass__(None) (if that method exists) which should
+ * return the metaclass for t. Then type(t) is set to this metaclass
+ * and metaclass.__init__(t, None, None, None) is called.
+ */
+static CYTHON_INLINE int Sage_PyType_Ready(PyTypeObject* t)
+{
+    int r = PyType_Ready(t);
+    if (r < 0)
+        return r;
+
+    // Cython 3 sets Py_TPFLAGS_HEAPTYPE before calling PyType_Ready,
+    // and resets just after the call. We need to reset it earlier,
+    // since otherwise the call to metaclass.__init__ below may have
+    // illegal memory accesses.
+    // See also:
+    // https://github.com/cython/cython/issues/3603
+    t->tp_flags &= ~Py_TPFLAGS_HEAPTYPE;
+
+    /* Set or get metaclass (the type of t) */
+    PyTypeObject* metaclass;
+
+    PyObject* getmetaclass;
+    getmetaclass = PyObject_GetAttrString((PyObject*)t, "__getmetaclass__");
+    if (getmetaclass)
+    {
+        /* Call getmetaclass with self=None */
+        metaclass = (PyTypeObject*)(PyMethodDescr_CallSelf((PyMethodDescrObject*)getmetaclass, Py_None));
+        Py_DECREF(getmetaclass);
+        if (!metaclass)
+            return -1;
+
+        if (!PyType_Check(metaclass))
+        {
+            PyErr_SetString(PyExc_TypeError,
+                    "__getmetaclass__ did not return a type");
+            return -1;
+        }
+
+        /* Now, set t.__class__ to metaclass */
+        Py_SET_TYPE(t, metaclass);
+        PyType_Modified(t);
+    }
+    else
+    {
+        /* No __getmetaclass__ method: read metaclass... */
+        PyErr_Clear();
+        metaclass = Py_TYPE(t);
+    }
+
+    /* Now call metaclass.__init__(t, None, None, None) unless
+     * we would be calling type.__init__ */
+    initproc init = metaclass->tp_init;
+    if (init == NULL || init == PyType_Type.tp_init)
+        return 0;
+
+    /* Safety check: since we didn't call tp_new of metaclass,
+     * we cannot safely call tp_init if the size of the structure
+     * differs. */
+    if (metaclass->tp_basicsize != PyType_Type.tp_basicsize)
+    {
+        PyErr_SetString(PyExc_TypeError,
+                "metaclass is not compatible with 'type' (you cannot use cdef attributes in Cython metaclasses)");
+        return -1;
+    }
+
+    /* Initialize a tuple (None, None, None) */
+    if (!NoneNoneNone)
+    {
+        NoneNoneNone = PyTuple_Pack(3, Py_None, Py_None, Py_None);
+        if (!NoneNoneNone) return -1;
+    }
+    return init((PyObject*)t, NoneNoneNone, NULL);
+}
+
+
+/* Use the above function in Cython code instead of the default
+ * PyType_Ready() function */
+#define PyType_Ready(t)  Sage_PyType_Ready(t)

sage/cpython/cython_metaclass.pxd

@@ -0,0 +1,3 @@
+# sage_setup: distribution = sagemath-objects
+cdef extern from "cython_metaclass.h":
+    PyMethodDescr_CallSelf(desc, self)

sage/cpython/cython_metaclass.pyx

@@ -0,0 +1,130 @@
+# sage_setup: distribution = sagemath-objects
+"""
+Metaclasses for Cython extension types
+
+Cython does not support metaclasses, but this module can be used to
+implement metaclasses for extension types.
+
+.. WARNING::
+
+    This module has many caveats and you can easily get segfaults if you
+    make a mistake. It relies on undocumented Python and Cython
+    behaviour, so things might break in future versions.
+
+How to use
+==========
+
+To enable this metaclass mechanism, you need to put
+``cimport sage.cpython.cython_metaclass`` in your module (in the ``.pxd``
+file if you are using one).
+
+In the extension type (a.k.a. ``cdef class``) for which you want to
+define a metaclass, define a method ``__getmetaclass__`` with a single
+unused argument, and turn off the Cython directive
+``always_allow_keywords``. This method should return a type to be used as
+metaclass:
+
+.. code-block:: cython
+
+    cimport cython
+    cimport sage.cpython.cython_metaclass
+    cdef class MyCustomType():
+        @cython.always_allow_keywords(False)
+        def __getmetaclass__(_):
+            from foo import MyMetaclass
+            return MyMetaclass
+
+.. WARNING::
+
+    ``__getmetaclass__`` must be defined as an ordinary method taking a
+    single argument, but this argument should not be used in the
+    method (it will be ``None``).
+
+When a type ``cls`` is being constructed with metaclass ``meta``,
+then ``meta.__init__(cls, None, None, None)`` is called from Cython.
+In Python, this would be ``meta.__init__(cls, name, bases, dict)``.
+
+.. WARNING::
+
+    The ``__getmetaclass__`` method is called while the type is being
+    created during the import of the module. Therefore,
+    ``__getmetaclass__`` should not refer to any global objects,
+    including the type being created or other types defined or imported
+    in the module (unless you are very careful). Note that non-imported
+    ``cdef`` functions are not Python objects, so those are safe to call.
+
+    The same warning applies to the ``__init__`` method of the
+    metaclass.
+
+.. WARNING::
+
+    The ``__new__`` method of the metaclass (including the ``__cinit__``
+    method for Cython extension types) is never called if you're using
+    this from Cython. In particular, the metaclass cannot have any
+    attributes or virtual methods.
+
+EXAMPLES::
+
+    sage: cython(                                                                       # needs sage.misc.cython
+    ....: '''
+    ....: cimport cython
+    ....: cimport sage.cpython.cython_metaclass
+    ....: cdef class MyCustomType():
+    ....:     @cython.always_allow_keywords(False)
+    ....:     def __getmetaclass__(_):
+    ....:         class MyMetaclass(type):
+    ....:             def __init__(*args):
+    ....:                 print("Calling MyMetaclass.__init__{}".format(args))
+    ....:         return MyMetaclass
+    ....:
+    ....: cdef class MyDerivedType(MyCustomType):
+    ....:     pass
+    ....: ''')
+    Calling MyMetaclass.__init__(<class '...MyCustomType'>, None, None, None)
+    Calling MyMetaclass.__init__(<class '...MyDerivedType'>, None, None, None)
+    sage: MyCustomType.__class__                                                        # needs sage.misc.cython
+    <class '...MyMetaclass'>
+    sage: class MyPythonType(MyDerivedType):                                            # needs sage.misc.cython
+    ....:     pass
+    Calling MyMetaclass.__init__(<class '...MyPythonType'>, 'MyPythonType', (<class '...MyDerivedType'>,), {...})
+
+Implementation
+==============
+
+All this is implemented by defining
+
+.. code-block:: c
+
+    #define PyTypeReady(t)  Sage_PyType_Ready(t)
+
+and then implementing the function ``Sage_PyType_Ready(t)`` which first
+calls ``PyType_Ready(t)`` and then handles the metaclass stuff.
+
+TESTS:
+
+Check that a proper exception is raised if ``__getmetaclass__``
+returns a non-type::
+
+    sage: cython(                                                                       # needs sage.misc.cython
+    ....: '''
+    ....: cimport cython
+    ....: cimport sage.cpython.cython_metaclass
+    ....: cdef class MyCustomType():
+    ....:     @cython.always_allow_keywords(False)
+    ....:     def __getmetaclass__(_):
+    ....:         return 2
+    ....: ''')
+    Traceback (most recent call last):
+    ...
+    TypeError: __getmetaclass__ did not return a type
+"""
+
+# ****************************************************************************
+#       Copyright (C) 2015 Jeroen Demeyer <jdemeyer@cage.ugent.be>
+#
+# 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/
+# ****************************************************************************