Description

jsbueno

opened on Jul 10, 2025

Issue body actions

Bug report

Update

Turns out it is correctly registered as a subclass of Mapping of Python 3.13.2 (at least) - which was the original report - but then it should be exposed in types.

Bug description:

Although the FrameLocalsProxy object created when retrieving the .f_locals attribute
from a frame is a complete mutable mapping, and created so it could be a drop-in,
backwards compatible replacement for the plain dict that was retrieved from
there prior to Python 3.13, it can't be tested as a Mapping in either
dynamic or static checking.

In practical terms, if I have a function that will support receiving a mapping, and into which I would pass a FrameLocalsProxy, static checkers would fail.

this is testable on the repl:

import sys
from collections.abc import Mapping, MutableMapping

FrameLocalsProxy = (lambda: type(sys._getframe().f_locals)()

def gen():
   yield

running_gen = gen()
next(running_gen)

f_locals = running_gen.gi_frame.f_locals

isinstance(f_locals, FrameLocalsProxy)
# True

isinstance(f_locals, Mapping)
# False

isinstance(f_locals, MutableMapping)
# False

Admittedly, it can't conform with MutableMapping since it doesn't make sense to try to delete items from such a proxy - although values can be replaced and added. In accord, it lacks clear and popitem methods -
Therefore one trying to accurately trying to static type a method that could receive a FrameLocalsProxy one intends to modify will have to resort to protocols. But that doesn't need to be the case for Mapping, since it is fully conformant.

Also, otherwise code which wants to test in runtime if an object is a mapping should be able to know that with an isinstance check.

---

I am willing to contribute this change if it is judged correct.

CPython versions tested on:

3.13

Operating systems tested on:

Linux

Linked PRs

• gh-136492: Add FrameLocalsProxyType to types #136546

Activity

1. jsbueno

   added

   type-bugAn unexpected behavior, bug, or errorAn unexpected behavior, bug, or error

   on Jul 10, 2025
2. gaogaotiantian commented on Jul 10, 2025

   

   gaogaotiantian

   on Jul 10, 2025

   Member

   More actions

   I agree that this should probably be a Mapping. On a side note, we should probably also expose the type in types? So we don't have to do FrameLocalsProxy = (lambda: type(sys._getframe().f_locals)().

   Reacted by Petr Viktorin and Peter Bierma
3. jsbueno commented on Jul 10, 2025

   

   jsbueno

   on Jul 10, 2025

   ContributorAuthor

   More actions

   Given that types does exactly this kind of thing for other seldom needed types, it would certainly be handy.
4. StanFromIreland

   added

   stdlibStandard Library Python modules in the Lib/ directoryStandard Library Python modules in the Lib/ directory

   on Jul 10, 2025
5. sobolevn commented on Jul 10, 2025

   

   sobolevn

   on Jul 10, 2025

   Member

   More actions

   On a side note, we should probably also expose the type in types?

   When exposing something, it means that it would be really hard to remove. I thought that localsproxy for now is an implementation detail, not a documented contract 🤔
6. gaogaotiantian commented on Jul 10, 2025

   

   gaogaotiantian

   on Jul 10, 2025

   Member

   More actions

   Well it's already part of the C-API - https://docs.python.org/3/c-api/frame.html#c.PyFrameLocalsProxy_Type
7. ZeroIntensity commented on Jul 11, 2025

   

   ZeroIntensity

   on Jul 11, 2025

   Member

   More actions

   I think as long as we document it as "the type of f_locals", we can expose it without worrying too much. If we change the type of f_locals someday, we can just alias FrameLocalsProxy to whatever that type is.
8. gaogaotiantian commented on Jul 12, 2025

   

   gaogaotiantian

   on Jul 12, 2025

   Member

   More actions

   Okay so I just took a look at the code. Which 3.13 did you use? This should be fixed in #120101 and backported to 3.13 prior to it's first official release. In theory this should work on 3.13.0. I confirmed that it works properly on 3.13.4 and main.

   I'll keep this issue open because we probably still want to expose the type, but FrameLocalsProxy is already a Mapping.
9. jsbueno commented on Jul 15, 2025

   

   jsbueno

   on Jul 15, 2025

   ContributorAuthor

   More actions

   Indeed - I think I ran the test in an old virtualenv with a beta 3.13 build around here.

   So, it is resolved for FrameLocalsMapping being a correct mapping - and the PEP itself explicitly lays the difference towards a MutableMapping.

   Exposing it to types should be up to consideration, then -

   I've updated the description - but I am not sure if this should be moved from "bug" to "feature request" (or if one could just add the feature in the main branch and close the issue :-) )
10. ZeroIntensity

    added a commit that references this issue on Jul 20, 2025

    gh-136492: Add `FrameLocalsProxyType` to `types` (GH-136546)

    8f59fbb
11. ZeroIntensity

    closed this as completedon Jul 20, 2025
12. taegyunkim

    added a commit that references this issue on Aug 4, 2025

    pythongh-136492: Add `FrameLocalsProxyType` to `types` (pythonGH-136546)

    bb70585
13. Agent-Hellboy

    added a commit that references this issue on Aug 19, 2025

    pythongh-136492: Add `FrameLocalsProxyType` to `types` (pythonGH-136546)

    b4e0f1a

Issue actions