From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> Date: Wed, 11 Dec 2024 16:34:35 +0000 (+0100) Subject: [3.13] gh-118915: C API: Document frame locals proxies. (GH-127720) (#127831) X-Git-Tag: v3.13.2~209 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=8b24d042b4d23700f873c23f78cee0972ad24f62;p=thirdparty%2FPython%2Fcpython.git [3.13] gh-118915: C API: Document frame locals proxies. (GH-127720) (#127831) gh-118915: C API: Document frame locals proxies. (GH-127720) (cherry picked from commit dd9da738ad1d420fabafaded3fe63912b2b17cfb) Co-authored-by: Peter Bierma Co-authored-by: Alex Waygood --- diff --git a/Doc/c-api/frame.rst b/Doc/c-api/frame.rst index 638a740e0c24..1a52e146a697 100644 --- a/Doc/c-api/frame.rst +++ b/Doc/c-api/frame.rst @@ -132,7 +132,7 @@ See also :ref:`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 `. 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 ` +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 ^^^^^^^^^^^^^^^