gh-74929: Rudimentary docs for PEP 667 (#118581)

This is *not* sufficient for the final 3.13 release, but it will do for beta 1:

- What's new entry
- Updated changelog entry (news blurb)
- Mention the proxy for f_globals in the datamodel and Python frame object docs

This doesn't have any C API details (what's new refers to the PEP).

Author: gvanrossum

Doc/c-api/frame.rst

@@ -120,12 +120,19 @@ See also :ref:`Reflection <reflection>`.
 
 .. c:function:: PyObject* PyFrame_GetLocals(PyFrameObject *frame)
 
-   Get the *frame*'s :attr:`~frame.f_locals` attribute (:class:`dict`).
+   Get the *frame*'s :attr:`~frame.f_locals` attribute.
+   If the frame refers to a function or comprehension, this returns
+   a write-through proxy object that allows modifying the locals.
+   In all other cases (classes, modules) it returns the :class:`dict`
+   representing the frame locals directly.
 
    Return a :term:`strong reference`.
 
    .. versionadded:: 3.11
 
+   .. versionchanged:: 3.13
+      Return a proxy object for functions and comprehensions.
+
 
 .. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)
 

Doc/reference/datamodel.rst

@@ -1341,7 +1341,12 @@ Special read-only attributes
 
    * - .. attribute:: frame.f_locals
      - The dictionary used by the frame to look up
-       :ref:`local variables <naming>`
+       :ref:`local variables <naming>`.
+       If the frame refers to a function or comprehension,
+       this may return a write-through proxy object.
+
+       .. versionchanged:: 3.13
+          Return a proxy for functions and comprehensions.
 
    * - .. attribute:: frame.f_globals
      - The dictionary used by the frame to look up

Doc/whatsnew/3.13.rst

@@ -87,6 +87,11 @@ Interpreter improvements:
   Performance improvements are modest -- we expect to be improving this
   over the next few releases.
 
+* :pep:`667`: :attr:`FrameType.f_locals <frame.f_locals>` when used in
+  a function now returns a write-through proxy to the frame's locals,
+  rather than a ``dict``. See the PEP for corresponding C API changes
+  and deprecations.
+
 New typing features:
 
 * :pep:`696`: Type parameters (:data:`typing.TypeVar`, :data:`typing.ParamSpec`,

Misc/NEWS.d/next/Core and Builtins/2024-04-27-21-44-40.gh-issue-74929.C2nESp.rst

@@ -1 +1,3 @@
-Implement PEP 667 - converted ``frame.f_locals`` to a write through proxy
+Implement PEP 667: converted :attr:`FrameType.f_locals <frame.f_locals>`
+and :c:func:`PyFrame_GetLocals` to return a write-through proxy object
+when the frame refers to a function or comprehension.