gh-136492: Add FrameLocalsProxyType to types

Doc/library/types.rst

@@ -333,6 +333,17 @@ 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

Doc/whatsnew/3.15.rst

@@ -278,6 +278,13 @@ tarfile
   and :cve:`2025-4435`.)
 
 
+types
+------
+
+* Added :data:`types.FrameLocalsProxyType` for representing the type of
+  the :attr:`frame.f_locals` attribute, as determined in :pep:`667`.
+
+
 zlib
 ----
 

Lib/test/test_inspect/test_inspect.py

@@ -5786,10 +5786,13 @@ def test_types_module_has_signatures(self):
             'AsyncGeneratorType': {'athrow'},
             'CoroutineType': {'throw'},
             'GeneratorType': {'throw'},
+            'FrameLocalsProxyType': {'setdefault', 'pop', 'get'}
         }
+        no_signature = {'FrameLocalsProxyType'}
         self._test_module_has_signatures(types,
                 unsupported_signature=unsupported_signature,
-                methods_no_signature=methods_no_signature)
+                methods_no_signature=methods_no_signature,
+                no_signature=no_signature)
 
     def test_sys_module_has_signatures(self):
         no_signature = {'getsizeof', 'set_asyncgen_hooks'}

Lib/test/test_types.py

@@ -58,6 +58,7 @@ def test_names(self):
             'MethodDescriptorType', 'MethodType', 'MethodWrapperType',
             'ModuleType', 'NoneType', 'NotImplementedType', 'SimpleNamespace',
             'TracebackType', 'UnionType', 'WrapperDescriptorType',
+            'FrameLocalsProxyType'
         }
         self.assertEqual(all_names, set(c_types.__all__))
         self.assertEqual(all_names - c_only_names, set(py_types.__all__))
@@ -711,6 +712,11 @@ def call(part):
         """
         assert_python_ok("-c", code)
 
+    def test_frame_locals_proxy(self):
+        frame = inspect.currentframe()
+        self.assertIsNotNone(frame)
+        self.assertIsInstance(frame.f_locals, types.FrameLocalsProxyType)
+
 
 class UnionTests(unittest.TestCase):
 

Lib/types.py

@@ -69,6 +69,7 @@ def _m(self): pass
     EllipsisType = type(Ellipsis)
     NoneType = type(None)
     NotImplementedType = type(NotImplemented)
+    FrameLocalsProxyType = (lambda: type(sys._getframe().f_locals))()
 
     # CapsuleType cannot be accessed from pure Python,
     # so there is no fallback definition.

Misc/NEWS.d/next/Library/2025-07-11-10-23-44.gh-issue-136492.BVi5h0.rst

@@ -0,0 +1 @@
+Add :data:`~types.FrameLocalsProxyType` to the :mod:`types` module.

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);