gh-136492: Add FrameLocalsProxyType to types (GH-136546)

ZeroIntensity · JelleZijlstra · AA-Turner · web-flow · commit 8f59fbb082a4 · 2025-07-20T20:49:00.000+02:00
Co-authored-by: Jelle Zijlstra &lt;jelle.zijlstra@gmail.com&gt;
Co-authored-by: Adam Turner &lt;9087854+AA-Turner@users.noreply.github.com&gt;
diff --git a/Doc/library/types.rst b/Doc/library/types.rst
@@ -333,6 +333,16 @@ Standard names are defined for the following types:
    :attr:`tb.tb_frame <traceback.tb_frame>` if ``tb`` is a traceback object.
 
 
+.. data:: FrameLocalsProxyType
+
+   The type of frame locals proxy objects, as found on the
+   :attr:`frame.f_locals` attribute.
+
+   .. versionadded:: next
+
+   .. seealso:: :pep:`667`
+
+
 .. data:: GetSetDescriptorType
 
    The type of objects defined in extension modules with ``PyGetSetDef``, such
diff --git a/Doc/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst
@@ -312,6 +312,15 @@ tarfile
   and :cve:`2025-4435`.)
 
 
+types
+------
+
+* Expose the write-through :func:`locals` proxy type
+  as :data:`types.FrameLocalsProxyType`.
+  This represents the type of the :attr:`frame.f_locals` attribute,
+  as described in :pep:`667`.
+
+
 unittest
 --------
 
diff --git a/Lib/test/test_inspect/test_inspect.py b/Lib/test/test_inspect/test_inspect.py
@@ -5786,6 +5786,7 @@ def test_types_module_has_signatures(self):
             'AsyncGeneratorType': {'athrow'},
             'CoroutineType': {'throw'},
             'GeneratorType': {'throw'},
+            'FrameLocalsProxyType': {'setdefault', 'pop', 'get'},
         }
         self._test_module_has_signatures(types,
                 unsupported_signature=unsupported_signature,
diff --git a/Lib/test/test_types.py b/Lib/test/test_types.py
@@ -53,6 +53,7 @@ def test_names(self):
             'AsyncGeneratorType', 'BuiltinFunctionType', 'BuiltinMethodType',
             'CapsuleType', 'CellType', 'ClassMethodDescriptorType', 'CodeType',
             'CoroutineType', 'EllipsisType', 'FrameType', 'FunctionType',
+            'FrameLocalsProxyType',
             'GeneratorType', 'GenericAlias', 'GetSetDescriptorType',
             'LambdaType', 'MappingProxyType', 'MemberDescriptorType',
             'MethodDescriptorType', 'MethodType', 'MethodWrapperType',
@@ -711,6 +712,16 @@ def call(part):
         """
         assert_python_ok("-c", code)
 
+    def test_frame_locals_proxy_type(self):
+        self.assertIsInstance(types.FrameLocalsProxyType, type)
+        self.assertIsInstance(types.FrameLocalsProxyType.__doc__, str)
+        self.assertEqual(types.FrameLocalsProxyType.__module__, 'builtins')
+        self.assertEqual(types.FrameLocalsProxyType.__name__, 'FrameLocalsProxy')
+
+        frame = inspect.currentframe()
+        self.assertIsNotNone(frame)
+        self.assertIsInstance(frame.f_locals, types.FrameLocalsProxyType)
+
 
 class UnionTests(unittest.TestCase):
 
diff --git a/Lib/types.py b/Lib/types.py
@@ -58,7 +58,10 @@ def _m(self): pass
         raise TypeError
     except TypeError as exc:
         TracebackType = type(exc.__traceback__)
-        FrameType = type(exc.__traceback__.tb_frame)
+
+    _f = (lambda: sys._getframe())()
+    FrameType = type(_f)
+    FrameLocalsProxyType = type(_f.f_locals)
 
     GetSetDescriptorType = type(FunctionType.__code__)
     MemberDescriptorType = type(FunctionType.__globals__)
diff --git a/Misc/NEWS.d/next/Library/2025-07-11-10-23-44.gh-issue-136492.BVi5h0.rst b/Misc/NEWS.d/next/Library/2025-07-11-10-23-44.gh-issue-136492.BVi5h0.rst
@@ -0,0 +1 @@
+Expose :pep:`667`'s :data:`~types.FrameLocalsProxyType` in the :mod:`types` module.
diff --git a/Modules/_typesmodule.c b/Modules/_typesmodule.c
@@ -28,6 +28,7 @@ _types_exec(PyObject *m)
     EXPORT_STATIC_TYPE("CoroutineType", PyCoro_Type);
     EXPORT_STATIC_TYPE("EllipsisType", PyEllipsis_Type);
     EXPORT_STATIC_TYPE("FrameType", PyFrame_Type);
+    EXPORT_STATIC_TYPE("FrameLocalsProxyType", PyFrameLocalsProxy_Type);
     EXPORT_STATIC_TYPE("FunctionType", PyFunction_Type);
     EXPORT_STATIC_TYPE("GeneratorType", PyGen_Type);
     EXPORT_STATIC_TYPE("GenericAlias", Py_GenericAliasType);
diff --git a/Objects/frameobject.c b/Objects/frameobject.c
@@ -913,6 +913,15 @@ static PyMethodDef framelocalsproxy_methods[] = {
     {NULL, NULL}   /* sentinel */
 };
 
+PyDoc_STRVAR(framelocalsproxy_doc,
+"FrameLocalsProxy($frame)\n"
+"--\n"
+"\n"
+"Create a write-through view of the locals dictionary for a frame.\n"
+"\n"
+"  frame\n"
+"    the frame object to wrap.");
+
 PyTypeObject PyFrameLocalsProxy_Type = {
     PyVarObject_HEAD_INIT(&PyType_Type, 0)
     .tp_name = "FrameLocalsProxy",
@@ -933,6 +942,7 @@ PyTypeObject PyFrameLocalsProxy_Type = {
     .tp_alloc = PyType_GenericAlloc,
     .tp_new = framelocalsproxy_new,
     .tp_free = PyObject_GC_Del,
+    .tp_doc = framelocalsproxy_doc,
 };
 
 PyObject *

Original file line number	Diff line number	Diff line change
`@@ -5786,6 +5786,7 @@ def test_types_module_has_signatures(self):`
`5786`	`5786`	`'AsyncGeneratorType': {'athrow'},`
`5787`	`5787`	`'CoroutineType': {'throw'},`
`5788`	`5788`	`'GeneratorType': {'throw'},`
	`5789`	`+ 'FrameLocalsProxyType': {'setdefault', 'pop', 'get'},`
`5789`	`5790`	`}`
`5790`	`5791`	`self._test_module_has_signatures(types,`
`5791`	`5792`	`unsupported_signature=unsupported_signature,`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Expose :pep:`667`'s :data:`~types.FrameLocalsProxyType` in the :mod:`types` module.