python / python/cpython

Document FrameLocalsProxy behaviour quirks

Open Beginner friendly
#125,731 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

3.13 3.14 docs triaged
Dominant language
Python
Stars
77.2k
Forks
35.9k
PR merge metrics
PR metrics pending

Description

Following PEP 667, https://docs.python.org/dev/reference/datamodel.html#frame-objects mentions that frame.f_locals may be a write-through proxy object, but doesn't really explain what that means.

Once https://github.com/python/peps/pull/3845 lands PEP 667 will contain such a description, but the main docs should at least cover the key behaviours:

  • new instance on every attribute access
  • two proxies with the same keys and values will still be unequal if they refer to different frames
  • extra keys can be stored and are stored on the frame itself so they're shared across all proxies for the same frame
  • keys corresponding to local variables can't be deleted
  • .copy() (and any other API that produces a new container) returns a regular dict instance

Suggested location would be as a new 4th subsection under the frame objects section linked above. A "see also" from that new subsection back to PEP 667 would also be a useful addition.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the frame objects section in the Python data model documentation and review PEP 667, including the linked PEP pull request. Add a fourth subsection describing the five listed FrameLocalsProxy behaviours and a see-also link back to PEP 667. Done means the main docs explain proxy identity, shared extra keys, undeletable locals, and dict-producing APIs.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
88/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.