PyLocals_GetReturnsCopy -> PyLocals_GetKind()

python · ncoghlan · Sep 18, 2017 · Nov 5, 2017 · Nov 5, 2017 · Nov 5, 2017
commit 66d058c1eda1009c0590bcb0f36eafdba4df5dd5
diff --git a/Doc/data/stable_abi.dat b/Doc/data/stable_abi.dat
@@ -334,7 +334,7 @@ function,PyList_Sort,3.2,
 var,PyList_Type,3.2,
 function,PyLocals_Get,3.11,
 function,PyLocals_GetCopy,3.11,
-function,PyLocals_GetReturnsCopy,3.11,
+function,PyLocals_Kind,3.11,
 function,PyLocals_GetView,3.11,
 type,PyLongObject,3.2,
 var,PyLongRangeIter_Type,3.2,

diff --git a/Include/ceval.h b/Include/ceval.h
@@ -43,20 +43,22 @@ PyAPI_FUNC(PyFrameObject *) PyEval_GetFrame(void);
  * It returns a read/write reference or a shallow copy depending on the scope
  * of the active frame.
  */
-// TODO: Add API tests for this
 PyAPI_FUNC(PyObject *) PyLocals_Get(void);
 
 /* PyLocals_GetCopy() returns a fresh shallow copy of the active local namespace */
-// TODO: Implement this, and add API tests
 PyAPI_FUNC(PyObject *) PyLocals_GetCopy(void);
 
 /* PyLocals_GetView() returns a read-only proxy for the active local namespace */
-// TODO: Implement this, and add API tests
 PyAPI_FUNC(PyObject *) PyLocals_GetView(void);
 
-/* Returns true if PyLocals_Get() returns a shallow copy in the active scope */
-// TODO: Implement this, and add API tests
-PyAPI_FUNC(int) PyLocals_GetReturnsCopy(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_Kind;
+
+PyAPI_FUNC(PyLocals_Kind) PyLocals_GetKind(void);
 #endif
 
 

diff --git a/Include/cpython/frameobject.h b/Include/cpython/frameobject.h
@@ -79,7 +79,7 @@ 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_GetLocalsReturnsCopy() instead. Having this available
+//       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;
@@ -93,7 +93,7 @@ PyAPI_DATA(PyTypeObject) _PyFastLocalsProxy_Type;
 PyAPI_FUNC(PyObject *) PyFrame_GetLocals(PyFrameObject *);
 PyAPI_FUNC(PyObject *) PyFrame_GetLocalsCopy(PyFrameObject *);
 PyAPI_FUNC(PyObject *) PyFrame_GetLocalsView(PyFrameObject *);
-PyAPI_FUNC(int) PyFrame_GetLocalsReturnsCopy(PyFrameObject *);
+PyAPI_FUNC(PyLocals_Kind) PyFrame_GetLocalsKind(PyFrameObject *);
 
 // Underlying API supporting PyEval_GetLocals()
 PyAPI_FUNC(PyObject *) _PyFrame_BorrowLocals(PyFrameObject *);

diff --git a/Lib/test/test_frame.py b/Lib/test/test_frame.py
@@ -234,7 +234,7 @@ def test_active_frame_c_apis(self):
         Py_IncRef = ctypes.pythonapi.Py_IncRef
         PyEval_GetLocals = ctypes.pythonapi.PyEval_GetLocals
         PyLocals_Get = ctypes.pythonapi.PyLocals_Get
-        PyLocals_GetReturnsCopy = ctypes.pythonapi.PyLocals_GetReturnsCopy
+        PyLocals_GetKind = ctypes.pythonapi.PyLocals_GetKind
         PyLocals_GetCopy = ctypes.pythonapi.PyLocals_GetCopy
         PyLocals_GetView = ctypes.pythonapi.PyLocals_GetView
         for capi_func in (Py_IncRef,):
@@ -255,7 +255,7 @@ def test_active_frame_c_apis(self):
         Py_IncRef(c_locals_cache) # Make the borrowed reference a real one
         Py_IncRef(c_locals_cache) # Account for next check's borrowed reference
         self.assertIs(PyEval_GetLocals(), c_locals_cache)
-        self.assertTrue(PyLocals_GetReturnsCopy())
+        self.assertEqual(PyLocals_GetKind(), 1) # PyLocals_SHALLOW_COPY
         locals_get = PyLocals_Get()
         self.assertIsInstance(locals_get, dict)
         self.assertIsNot(locals_get, c_locals_cache)
@@ -271,7 +271,7 @@ class ExecFrame:
             Py_IncRef(c_locals_cache) # Make the borrowed reference a real one
             Py_IncRef(c_locals_cache) # Account for next check's borrowed reference
             self.assertIs(PyEval_GetLocals(), c_locals_cache)
-            self.assertFalse(PyLocals_GetReturnsCopy())
+            self.assertEqual(PyLocals_GetKind(), 0) # PyLocals_DIRECT_REFERENCE
             locals_get = PyLocals_Get()
             self.assertIs(locals_get, c_locals_cache)
             locals_copy = PyLocals_GetCopy()
@@ -286,11 +286,11 @@ def test_arbitrary_frame_c_apis(self):
         Py_IncRef = ctypes.pythonapi.Py_IncRef
         _PyFrame_BorrowLocals = ctypes.pythonapi._PyFrame_BorrowLocals
         PyFrame_GetLocals = ctypes.pythonapi.PyFrame_GetLocals
-        PyFrame_GetLocalsReturnsCopy = ctypes.pythonapi.PyFrame_GetLocalsReturnsCopy
+        PyFrame_GetLocalsKind = ctypes.pythonapi.PyFrame_GetLocalsKind
         PyFrame_GetLocalsCopy = ctypes.pythonapi.PyFrame_GetLocalsCopy
         PyFrame_GetLocalsView = ctypes.pythonapi.PyFrame_GetLocalsView
         for capi_func in (Py_IncRef, _PyFrame_BorrowLocals,
-                          PyFrame_GetLocals, PyFrame_GetLocalsReturnsCopy,
+                          PyFrame_GetLocals, PyFrame_GetLocalsKind,
                           PyFrame_GetLocalsCopy, PyFrame_GetLocalsView):
             capi_func.argtypes = (ctypes.py_object,)
         for capi_func in (_PyFrame_BorrowLocals, PyFrame_GetLocals,
@@ -314,7 +314,7 @@ def set_cls_frame(f):
         class ExecFrame:
             c_locals_cache = get_c_locals(func_frame)
             self.assertIs(get_c_locals(func_frame), c_locals_cache)
-            self.assertTrue(PyFrame_GetLocalsReturnsCopy(func_frame))
+            self.assertEqual(PyFrame_GetLocalsKind(func_frame), 1) # PyLocals_SHALLOW_COPY
             locals_get = PyFrame_GetLocals(func_frame)
             self.assertIsInstance(locals_get, dict)
             self.assertIsNot(locals_get, c_locals_cache)
@@ -330,7 +330,7 @@ class ExecFrame:
         # Test querying an unoptimised frame from an optimised scope
         c_locals_cache = get_c_locals(cls_frame)
         self.assertIs(get_c_locals(cls_frame), c_locals_cache)
-        self.assertFalse(PyFrame_GetLocalsReturnsCopy(cls_frame))
+        self.assertEqual(PyFrame_GetLocalsKind(cls_frame), 0) # PyLocals_DIRECT_REFERENCE
         locals_get = PyFrame_GetLocals(cls_frame)
         self.assertIs(locals_get, c_locals_cache)
         locals_copy = PyFrame_GetLocalsCopy(cls_frame)

diff --git a/Misc/stable_abi.txt b/Misc/stable_abi.txt
@@ -2143,7 +2143,7 @@ function PyLocals_Get
     added 3.11
 function PyLocals_GetCopy
     added 3.11
-function PyLocals_GetReturnsCopy
+function PyLocals_GetKind
     added 3.11
 function PyLocals_GetView
        added 3.11
@@ -81,13 +81,16 @@ PyFrame_GetLocals(PyFrameObject *f)
     return updated_locals;
 }
 
-int
-PyFrame_GetLocalsReturnsCopy(PyFrameObject *f)
+PyLocals_Kind
+PyFrame_GetLocalsKind(PyFrameObject *f)
 {
-    // This frame API supports the stable PyLocals_GetReturnsCopy() API
+    // This frame API supports the stable PyLocals_GetKind() API
     PyCodeObject *co = _PyFrame_GetCode(f);
     assert(co);
-    return (co->co_flags & CO_OPTIMIZED);
+    if (co->co_flags & CO_OPTIMIZED) {
+        return PyLocals_SHALLOW_COPY;
+    }
+    return PyLocals_DIRECT_REFERENCE;
 }
 
 PyObject *

@@ -315,7 +315,7 @@ EXPORT_FUNC(PyList_Size)
 EXPORT_FUNC(PyList_Sort)
 EXPORT_FUNC(PyLocals_Get)
 EXPORT_FUNC(PyLocals_GetCopy)
-EXPORT_FUNC(PyLocals_GetReturnsCopy)
+EXPORT_FUNC(PyLocals_GetKind)
 EXPORT_FUNC(PyLocals_GetView)
 EXPORT_FUNC(PyLong_AsDouble)
 EXPORT_FUNC(PyLong_AsLong)

@@ -5803,17 +5803,17 @@ PyLocals_Get(void)
     return PyFrame_GetLocals(current_frame);
 }
 
-int
-PyLocals_GetReturnsCopy(void)
+PyLocals_Kind
+PyLocals_GetKind(void)
 {
     PyThreadState *tstate = _PyThreadState_GET();
     PyFrameObject *current_frame = tstate->frame;
     if (current_frame == NULL) {
         _PyErr_SetString(tstate, PyExc_SystemError, "frame does not exist");
-        return NULL;
+        return PyLocals_UNDEFINED;
     }
 
-    return PyFrame_GetLocalsReturnsCopy(current_frame);
+    return PyFrame_GetLocalsKind(current_frame);
 }
 
 PyObject *