[PEP 558 - WIP] bpo-30744: Trace hooks no longer reset closure state

Doc/c-api/cell.rst

@@ -39,13 +39,14 @@ Cell objects are not likely to be useful elsewhere.
 
 .. c:function:: PyObject* PyCell_Get(PyObject *cell)
 
-   Return the contents of the cell *cell*.
+   Return a new reference to the contents of the cell *cell*.
 
 
 .. c:function:: PyObject* PyCell_GET(PyObject *cell)
 
-   Return the contents of the cell *cell*, but without checking that *cell* is
-   non-``NULL`` and a cell object.
+   Borrow a reference to the contents of the cell *cell*. No reference counts are
+   adjusted, and no checks are made for safety; *cell* must be non-``NULL`` and must
+   be a cell object.
 
 
 .. c:function:: int PyCell_Set(PyObject *cell, PyObject *value)
@@ -58,6 +59,6 @@ Cell objects are not likely to be useful elsewhere.
 
 .. c:function:: void PyCell_SET(PyObject *cell, PyObject *value)
 
-   Sets the value of the cell object *cell* to *value*.  No reference counts are
+   Sets the value of the cell object *cell* to *value*. No reference counts are
    adjusted, and no checks are made for safety; *cell* must be non-``NULL`` and must
    be a cell object.

Doc/c-api/reflection.rst

@@ -10,12 +10,21 @@ Reflection
    Return a dictionary of the builtins in the current execution frame,
    or the interpreter of the thread state if no frame is currently executing.
 
+.. c:function:: PyObject* PyLocals_Get(void)
+
+   Return a dictionary of the local variables in the current execution frame,
+   or ``NULL`` if no frame is currently executing.
+
+   Equivalent to calling the Python level ``locals()`` builtin.
+
+.. TODO: cover the rest of the PEP 558 API here
 
 .. c:function:: PyObject* PyEval_GetLocals(void)
 
    Return a dictionary of the local variables in the current execution frame,
    or ``NULL`` if no frame is currently executing.
 
+   TODO: Clarify just how this relates to PyLocals_Get().
 
 .. c:function:: PyObject* PyEval_GetGlobals(void)
 

Doc/data/stable_abi.dat

@@ -332,6 +332,10 @@ function,PyList_SetSlice,3.2,
 function,PyList_Size,3.2,
 function,PyList_Sort,3.2,
 var,PyList_Type,3.2,
+function,PyLocals_Get,3.11,
+function,PyLocals_GetCopy,3.11,
+function,PyLocals_Kind,3.11,
+function,PyLocals_GetView,3.11,
 type,PyLongObject,3.2,
 var,PyLongRangeIter_Type,3.2,
 function,PyLong_AsDouble,3.2,

Include/ceval.h

@@ -33,6 +33,36 @@ PyAPI_FUNC(PyObject *) PyEval_GetGlobals(void);
 PyAPI_FUNC(PyObject *) PyEval_GetLocals(void);
 PyAPI_FUNC(PyFrameObject *) PyEval_GetFrame(void);
 
+// TODO: Update PyEval_GetLocals() documentation as described in
+// https://discuss.python.org/t/pep-558-defined-semantics-for-locals/2936/11
+
+#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030B0000
+/* Access the frame locals mapping in an implementation independent way */
+
+/* PyLocals_Get() is equivalent to the Python locals() builtin.
+ * It returns a read/write reference or a shallow copy depending on the scope
+ * of the active frame.
+ */
+PyAPI_FUNC(PyObject *) PyLocals_Get(void);
+
+/* PyLocals_GetCopy() returns a fresh shallow copy of the active local namespace */
+PyAPI_FUNC(PyObject *) PyLocals_GetCopy(void);
+
+/* PyLocals_GetView() returns a read-only proxy for the active local namespace */
+PyAPI_FUNC(PyObject *) PyLocals_GetView(void);
+
+/* PyLocals_GetKind()reports the behaviour of PyLocals_Get() in the active scope */
+typedef enum {
+    PyLocals_UNDEFINED = -1,      // Indicates error (e.g. no thread state defined)
+    PyLocals_DIRECT_REFERENCE = 0,
+    PyLocals_SHALLOW_COPY = 1,
+    _PyLocals_ENSURE_32BIT_ENUM = 2147483647
+} PyLocals_Kind;
+
+PyAPI_FUNC(PyLocals_Kind) PyLocals_GetKind(void);
+#endif
+
+
 PyAPI_FUNC(int) Py_AddPendingCall(int (*func)(void *), void *arg);
 PyAPI_FUNC(int) Py_MakePendingCalls(void);
 

Include/cpython/frameobject.h

@@ -24,6 +24,7 @@ struct _frame {
     struct _frame *f_back;      /* previous frame, or NULL */
     PyObject **f_valuestack;    /* points after the last local */
     PyObject *f_trace;          /* Trace function */
+    PyObject *f_fast_refs;      /* Name -> index-or-cell lookup for fast locals */
     /* Borrowed reference to a generator, or NULL */
     PyObject *f_gen;
     int f_stackdepth;           /* Depth of value stack */
@@ -64,13 +65,39 @@ _PyFrame_New_NoTrack(PyThreadState *, PyFrameConstructor *, PyObject *, PyObject
 
 /* The rest of the interface is specific for frame objects */
 
-/* Conversions between "fast locals" and locals in dictionary */
-
-PyAPI_FUNC(void) PyFrame_LocalsToFast(PyFrameObject *, int);
-
+/* Legacy conversions between "fast locals" and locals in dictionary */
 PyAPI_FUNC(int) PyFrame_FastToLocalsWithError(PyFrameObject *f);
 PyAPI_FUNC(void) PyFrame_FastToLocals(PyFrameObject *);
 
+/* This always raises RuntimeError now (use the PyLocals_* API instead) */
+PyAPI_FUNC(void) PyFrame_LocalsToFast(PyFrameObject *, int);
+
+/* Frame object memory management */
+PyAPI_FUNC(int) PyFrame_ClearFreeList(void);
 PyAPI_FUNC(void) _PyFrame_DebugMallocStats(FILE *out);
 
 PyAPI_FUNC(PyFrameObject *) PyFrame_GetBack(PyFrameObject *frame);
+
+/* Fast locals proxy allows for reliable write-through from trace functions */
+// TODO: Perhaps this should be hidden, and API users told to query for
+//       PyFrame_GetLocalsKind() instead. Having this available
+//       seems like a nice way to let folks write some useful debug assertions,
+//       though.
+PyAPI_DATA(PyTypeObject) _PyFastLocalsProxy_Type;
+#define _PyFastLocalsProxy_CheckExact(op) Py_IS_TYPE(op, &_PyFastLocalsProxy_Type)
+
+
+// Underlying implementation API supporting the stable PyLocals_*() APIs
+// TODO: Add specific test cases for these (as any PyLocals_* tests won't cover
+//       checking the status of a frame other than the currently active one)
+PyAPI_FUNC(PyObject *) PyFrame_GetLocals(PyFrameObject *);
+PyAPI_FUNC(PyObject *) PyFrame_GetLocalsCopy(PyFrameObject *);
+PyAPI_FUNC(PyObject *) PyFrame_GetLocalsView(PyFrameObject *);
+PyAPI_FUNC(PyLocals_Kind) PyFrame_GetLocalsKind(PyFrameObject *);
+
+// Underlying API supporting PyEval_GetLocals()
+PyAPI_FUNC(PyObject *) _PyFrame_BorrowLocals(PyFrameObject *);
+
+#ifdef __cplusplus
+}
+#endif

Include/descrobject.h

@@ -96,7 +96,14 @@ PyAPI_FUNC(PyObject *) PyDescr_NewWrapper(PyTypeObject *,
 PyAPI_FUNC(int) PyDescr_IsData(PyObject *);
 #endif
 
+/* PyDictProxy should really have its own header/impl pair, but keeping
+ * it here for now... */
+
 PyAPI_FUNC(PyObject *) PyDictProxy_New(PyObject *);
+#ifdef Py_BUILD_CORE
+PyAPI_DATA(PyTypeObject) PyDictProxy_Type;
+#endif
+
 PyAPI_FUNC(PyObject *) PyWrapper_New(PyObject *, PyObject *);
 
 

Include/internal/pycore_code.h

@@ -164,19 +164,19 @@ extern Py_ssize_t _Py_QuickenedCount;
 #define CO_FAST_CELL    0x40
 #define CO_FAST_FREE    0x80
 
-typedef unsigned char _PyLocals_Kind;
+typedef unsigned char _PyLocal_VarKind;
 
-static inline _PyLocals_Kind
-_PyLocals_GetKind(PyObject *kinds, int i)
+static inline _PyLocal_VarKind
+_PyLocal_GetVarKind(PyObject *kinds, int i)
 {
     assert(PyBytes_Check(kinds));
     assert(0 <= i && i < PyBytes_GET_SIZE(kinds));
     char *ptr = PyBytes_AS_STRING(kinds);
-    return (_PyLocals_Kind)(ptr[i]);
+    return (_PyLocal_VarKind)(ptr[i]);
 }
 
 static inline void
-_PyLocals_SetKind(PyObject *kinds, int i, _PyLocals_Kind kind)
+_PyLocal_SetVarKind(PyObject *kinds, int i, _PyLocal_VarKind kind)
 {
     assert(PyBytes_Check(kinds));
     assert(0 <= i && i < PyBytes_GET_SIZE(kinds));

Include/internal/pycore_frameobject.h

@@ -0,0 +1,17 @@
+#ifndef Py_INTERNAL_FRAMEOBJECT_H
+#define Py_INTERNAL_FRAMEOBJECT_H
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef Py_BUILD_CORE
+#  error "this header requires Py_BUILD_CORE define"
+#endif
+
+struct _frame;
+typedef struct _frame PyFrameObject;
+
+#ifdef __cplusplus
+}
+#endif
+#endif /* !Py_INTERNAL_FRAMEOBJECT_H */