From dd9da738ad1d420fabafaded3fe63912b2b17cfb Mon Sep 17 00:00:00 2001
From: Peter Bierma <zintensitydev@gmail.com>
Date: Wed, 11 Dec 2024 11:28:44 -0500
Subject: gh-118915: C API: Document frame locals proxies. (#127720)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
---
Doc/c-api/frame.rst | 22 +++++++++++++++++++++-
1 file changed, 21 insertions(+), 1 deletion(-)
diff --git a/Doc/c-api/frame.rst b/Doc/c-api/frame.rst
index 638a740..1a52e14 100644
--- a/Doc/c-api/frame.rst
+++ b/Doc/c-api/frame.rst
@@ -132,7 +132,7 @@ See also :ref:`Reflection <reflection>`.
.. versionadded:: 3.11
.. versionchanged:: 3.13
- As part of :pep:`667`, return a proxy object for optimized scopes.
+ As part of :pep:`667`, return an instance of :c:var:`PyFrameLocalsProxy_Type`.
.. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)
@@ -140,6 +140,26 @@ See also :ref:`Reflection <reflection>`.
Return the line number that *frame* is currently executing.
+Frame Locals Proxies
+^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 3.13
+
+The :attr:`~frame.f_locals` attribute on a :ref:`frame object <frame-objects>`
+is an instance of a "frame-locals proxy". The proxy object exposes a
+write-through view of the underlying locals dictionary for the frame. This
+ensures that the variables exposed by ``f_locals`` are always up to date with
+the live local variables in the frame itself.
+
+See :pep:`667` for more information.
+
+.. c:var:: PyTypeObject PyFrameLocalsProxy_Type
+
+ The type of frame :func:`locals` proxy objects.
+
+.. c:function:: int PyFrameLocalsProxy_Check(PyObject *obj)
+
+ Return non-zero if *obj* is a frame :func:`locals` proxy.
Internal Frames
^^^^^^^^^^^^^^^
--
cgit v0.12