From 07c0e7942861b74d3945958dadf2c81f032b7474 Mon Sep 17 00:00:00 2001 From: VimalN2005 Date: Sun, 20 Sep 2026 23:00:10 +0530 Subject: [PATCH] gh-125731: Document FrameLocalsProxy behaviour quirks in datamodel.rst --- Doc/reference/datamodel.rst | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 00a80010543be1..daac32dc24423a 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1705,7 +1705,8 @@ Special read-only attributes - The mapping used by the frame to look up :ref:`local variables `. If the frame refers to an :term:`optimized scope`, - this may return a write-through proxy object. + this may return a write-through proxy object + (see :ref:`frame-locals-proxy-behaviour`). .. versionchanged:: 3.13 Return a proxy for optimized scopes. @@ -1784,6 +1785,35 @@ Frame objects support one method: (as has always been the case for executing frames). +.. _frame-locals-proxy-behaviour: + +Frame locals proxy behaviour +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When :attr:`frame.f_locals` is accessed on a frame that refers to an +:term:`optimized scope` (such as a function or comprehension), it returns a +write-through proxy object rather than a direct reference to an internal +dictionary. + +This proxy object exhibits several specific behaviours: + +* A new proxy instance is returned on every access to :attr:`frame.f_locals`. +* Two proxy instances with the same keys and values will compare unequal + if they refer to different frame objects. +* Extra keys (names that do not correspond to local variables of the code object) + can be stored in the proxy; these extra variables are stored on the frame itself + and are therefore shared across all proxy instances for that same frame. +* Keys corresponding to local variables defined in the function cannot be deleted + from the proxy (attempting to do so raises :exc:`KeyError`). +* Calling :meth:`~dict.copy` (or any other API that constructs a new container + from the proxy) returns a standard :class:`dict` instance rather than a proxy. + +.. seealso:: + + :pep:`667` -- Consistent views of namespaces + Introduced write-through proxy semantics for :attr:`frame.f_locals`. + + .. _traceback-objects: Traceback objects