gh-74929: Rudimentary docs for PEP 667

[gvanrossum]

This is not sufficient for the final 3.13 release, but it may have to do for beta 1:

• What's new entry
• Updated changelog entry (news blurb)
• Mention the proxy for f_globals in the datamodel and Python frame object docs

This doesn't have any C API details (what's new refers to the PEP).

For some reason I cannot get the "versionchanged" note in the datamodel docs to show. @hugovk ?

• Issue: Local variable assignment is broken when combined with threads + tracing + closures #74929

---

📚 Documentation preview 📚: https://cpython-previews--118581.org.readthedocs.build/

[gaogaotiantian]

There's a minor technicality here that might worth clarification.

import sys
frame1 = [sys._getframe() for a in [0]][0]
frame2 = sys._getframe()
assert frame1 is frame2

local1 = [sys._getframe().f_locals for a in [0]][0]
local2 = sys._getframe().f_locals
assert local1 != local2

Whether f_locals is a proxy or a dict technically does not entirely depend on the frame. It depends on when is the frame.f_locals call made - inside a comprehension or not.

As you can tell from the example above, the frame is exactly the same frame object, but the f_locals is different.

[gvanrossum]

There's a minor technicality here that might worth clarification. [...]

That's very subtle. Is it explained in PEP 667? I'm not sure how to work this in the existing (pretty sparse) docs for f_locals.

[gaogaotiantian]

Actually the final behavior we agreed on is slightly different from what PEP 667 proposed. PEP 667 also did not mention how f_locals should work with inline comprehensions. Can we modify PEP 667 after it was accepted? I don't know if we should dump all the details in the f_locals docs because it would be rare for the users to use f_locals inside the comprehension so no need to confuse them, but it would be nice to explain it well in PEP 667.

[gvanrossum]

Actually the final behavior we agreed on is slightly different from what PEP 667 proposed. PEP 667 also did not mention how f_locals should work with inline comprehensions. Can we modify PEP 667 after it was accepted? I don't know if we should dump all the details in the f_locals docs because it would be rare for the users to use f_locals inside the comprehension so no need to confuse them, but it would be nice to explain it well in PEP 667.

Assuming this is about clarifying something that the original text of the PEP did not specify precisely enough, and given that the PEP is brand new, I think it's okay to clarify in the PEP. Although in general PEPs are nowadays seen as historic documents, not as living specifications.

[AlexWaygood]

It's not something that has to be done in this PR, but if we think that there are some subtleties here that warrant detailed explanation and that the datamodel docs aren't the right place to do that, one option would be to add a howto similar to the one Larry added in 3.10 to explain the semantics of the __annotations__ attribute: https://docs.python.org/3/howto/annotations.html

It wouldn't really be a howto in the Diataxis sense of the term, but we don't really have a better place for that kind of in-depth article in the CPython docs currently, and there are lots of other articles in that directory that also don't meet Diataxis's strict definition of a "howto" article. And as @gvanrossum says, all the relevant information regarding the semantics here should ideally be findable in the CPython docs somewhere, without having to refer to the PEP, which is a historical document now that it has been accepted.

(But we can probably update the PEP as well, given that it's only just been accepted :-)

[gvanrossum]

@AlexWaygood @gaogaotiantian Are you two okay with me merging this? I'm all for iterating later, but I feel it's important to mention at least this much in the beta 1 docs, which I expect will reach a relatively big audience of people who are thinking of testing the beta.

[gaogaotiantian]

Yes this feels okay for beta.

[AlexWaygood]

Suggested change

	rather than a ``dict``. See the PEP for corresponding C API changes
	rather than a :class:`dict`. See the PEP for corresponding C API changes

[gvanrossum]

I think that would be a case of over-linking. Surely readers who know what f_locals is will be familiar with dict.

[AlexWaygood]

Sure, I don't feel strongly, feel free to ignore

[AlexWaygood]

And apparently this also applies for type parameter scopes? Though I have no idea if that was deliberate:

>>> import sys
>>> type T[X: type(sys._getframe().f_locals)] = ...
>>> T.__type_params__[0].__bound__
<class 'FrameLocalsProxy'>