gh-136492: Add `FrameLocalsProxy` to `types` #136546

ZeroIntensity · 2025-07-11T14:27:42Z

Expose PEP-667's FrameLocalsProxy type as FrameLocalsProxyType in the types module.

Issue: FrameLocalsProxy (PEP 667) is not registered as a subclass of abc.Mapping #136492

📚 Documentation preview 📚: https://cpython-previews--136546.org.readthedocs.build/en/136546/library/types.html#types.FrameLocalsProxyType

picnixz · 2025-07-11T15:01:45Z

Doc/whatsnew/3.15.rst

@@ -226,6 +226,13 @@ os.path
  (Contributed by Petr Viktorin for :cve:`2025-4517`.)


+types


Can you put the section below tarfile?

Oops, got my ABCs wrong.

picnixz · 2025-07-11T15:02:38Z

Lib/test/test_types.py

-            'MethodDescriptorType', 'MethodType', 'MethodWrapperType',
-            'ModuleType', 'NoneType', 'NotImplementedType', 'SimpleNamespace',
-            'TracebackType', 'UnionType', 'WrapperDescriptorType',
+            'FrameLocalsProxyType', 'GeneratorType', 'GenericAlias',


A simple suggestion, but how about adding just FrameLocalsProxyType on a single line?

Yeah, I was 50/50 on whether not we should keep this alphabetical. I'll change it.

ZeroIntensity · 2025-07-11T15:14:01Z

Ugh, those test failures look like an existing bug on FrameLocalsProxy.

picnixz · 2025-07-11T17:00:18Z

@python/organization-owners Could you block blockchainGuru1018 for spam & misguided reviews? TiA.

gaogaotiantian · 2025-07-11T19:12:29Z

Doc/library/types.rst

@@ -333,6 +333,14 @@ Standard names are defined for the following types:
   :attr:`tb.tb_frame <traceback.tb_frame>` if ``tb`` is a traceback object.


+.. data:: FrameLocalsProxyType
+
+   The type of frame :func:`locals` proxy objects, as found on the


I don't think it's proper to link :func:`locals` here. locals() is a function that returns a snapshot (dict) of the local variables. That is a different path to local variables. frame.f_locals is designed to be different than locals(), it might be a bit confusing here.

I just used it to give context to what "locals" mean. I did the same for the C API docs. Should we change it there too?

gaogaotiantian · 2025-07-11T19:14:05Z

Doc/library/types.rst

+.. data:: FrameLocalsProxyType
+
+   The type of frame :func:`locals` proxy objects, as found on the
+   :attr:`frame.f_locals` attribute. See :pep:`667` for more information.


I'm not sure if we should refer to PEP 667 here - the PEP itself is a historical document and we are redirecting people to a different place in the PEP.

How about a seealso note instead?

gaogaotiantian · 2025-07-11T19:16:27Z

Ugh, those test failures look like an existing bug on FrameLocalsProxy.

Could you be more specific? Maybe raise an issue for that so I can fix it later?

ZeroIntensity · 2025-07-11T19:33:12Z

Could you be more specific? Maybe raise an issue for that so I can fix it later?

There were a few things I had to skip in test_inspect. I think they're bugs, but I haven't investigated the test enough to be sure.

gaogaotiantian · 2025-07-11T19:51:27Z

Okay now we need some typing expert to review this. @JelleZijlstra maybe?

ZeroIntensity · 2025-07-12T12:59:33Z

I'd also appreciate it if @AA-Turner could take a look; he's done some recent work with types and _types.

JelleZijlstra · 2025-07-12T16:34:50Z

You don't really need a static typing expert for the types module; it predates static typing and is useful even without static typing. The PR seems pretty straightforward to me.

JelleZijlstra · 2025-07-12T16:35:18Z

Doc/whatsnew/3.15.rst

+------
+
+* Added :data:`types.FrameLocalsProxyType` for representing the type of
+  the :attr:`frame.f_locals` attribute, as determined in :pep:`667`.


"determined" sounds a little odd here, maybe:

Suggested change

the :attr:`frame.f_locals` attribute, as determined in :pep:`667`.

the :attr:`frame.f_locals` attribute, as described in :pep:`667`.

JelleZijlstra · 2025-07-12T16:41:05Z

Lib/test/test_inspect/test_inspect.py

        }
+        no_signature = {'FrameLocalsProxyType'}


This should be fixable by adding a tp_doc to FrameLocalsProxy that includes the signature; see types.CellType in cellobject.c for an example.

JelleZijlstra · 2025-07-12T16:42:06Z

Lib/test/test_inspect/test_inspect.py

@@ -5786,10 +5786,13 @@ def test_types_module_has_signatures(self):
            'AsyncGeneratorType': {'athrow'},
            'CoroutineType': {'throw'},
            'GeneratorType': {'throw'},
+            'FrameLocalsProxyType': {'setdefault', 'pop', 'get'}


This should be fixable by converting these methods to Argument Clinic or manually adding a docstring with a signature.

To be clear I'm not asking you to necessarily fix this, though I think it'd be nice to reduce the size of the denylist in this test.

JelleZijlstra · 2025-07-12T16:45:56Z

Lib/types.py

@@ -69,6 +69,7 @@ def _m(self): pass
    EllipsisType = type(Ellipsis)
    NoneType = type(None)
    NotImplementedType = type(NotImplemented)
+    FrameLocalsProxyType = (lambda: type(sys._getframe().f_locals))()


Introspecting this class currently would make you think it is builtins.FrameLocalProxy:

>>> FrameLocalsProxyType = (lambda: type(sys._getframe().f_locals))() >>> FrameLocalsProxyType.__module__ 'builtins' >>> FrameLocalsProxyType.__name__ 'FrameLocalsProxy'

What do you think about changing its tp_name to types.FrameLocalsProxyType, so that the runtime __module__ and __name__ attributes are consistent with the place where you can actually find it? This is what types.SimpleNamespace already does.

Personally I'd ideally want to do this for all the types.* types, but there are compatibility concerns for some. Here though, given that the type is relatively new and private, maybe we can get away with changing its name and module.

ZeroIntensity added 8 commits July 11, 2025 10:12

Expose FrameLocalsProxy in types and _types

78b842c

Add a test case.

e2ddcbe

Add a documentation entry.

22e056d

Use the 'type' suffix.

b8fd733

Add a whatsnew entry.

abbe1d3

Add blurb.

753c9bc

Fix the tests.

b087d9b

Sort the name alphabetically.

1971a14

ZeroIntensity requested a review from gaogaotiantian July 11, 2025 14:27

bedevere-app bot added the awaiting core review label Jul 11, 2025

bedevere-app bot mentioned this pull request Jul 11, 2025

FrameLocalsProxy (PEP 667) is not registered as a subclass of abc.Mapping #136492

Open

Sort alphabetically in _types.

fdeb2d0

picnixz reviewed Jul 11, 2025

View reviewed changes

ZeroIntensity added 3 commits July 11, 2025 11:08

Move whatsnew section.

c8600b9

Somewhat fix the tests.

70cc4db

Reduce the diff.

fee5256

Use a workaround for the tests.

a110148

This comment was marked as spam.

Sign in to view

gaogaotiantian reviewed Jul 11, 2025

View reviewed changes

Move PEP note and remove locals() reference.

929f81e

JelleZijlstra reviewed Jul 12, 2025

View reviewed changes

		@@ -226,6 +226,13 @@ os.path
		(Contributed by Petr Viktorin for :cve:`2025-4517`.)


		types

	the :attr:`frame.f_locals` attribute, as determined in :pep:`667`.
	the :attr:`frame.f_locals` attribute, as described in :pep:`667`.

Uh oh!

gh-136492: Add FrameLocalsProxy to types #136546

Are you sure you want to change the base?

gh-136492: Add FrameLocalsProxy to types #136546

Conversation

ZeroIntensity commented Jul 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity commented Jul 11, 2025

Uh oh!

This comment was marked as spam.

Uh oh!

picnixz commented Jul 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gaogaotiantian commented Jul 11, 2025

Uh oh!

ZeroIntensity commented Jul 11, 2025

Uh oh!

gaogaotiantian commented Jul 11, 2025

Uh oh!

ZeroIntensity commented Jul 12, 2025

Uh oh!

JelleZijlstra commented Jul 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

gh-136492: Add `FrameLocalsProxy` to `types` #136546

gh-136492: Add `FrameLocalsProxy` to `types` #136546

ZeroIntensity commented Jul 11, 2025 •

edited

Loading