Document FrameLocalsProxy behaviour quirks
Nobody has claimed this yet.
- 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 regulardictinstance
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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