This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Documentation of globals() and locals() should be improved
Type: Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Zahari.Dim, docs@python, lukasz.langa, martin.panter, miss-islington, r.david.murray, terry.reedy, wangjiahua
Priority: normal Keywords: easy, patch

Created on 2013-11-23 16:51 by Zahari.Dim, last changed 2022-04-11 14:57 by admin. This issue is now closed.

File name Uploaded Description Edit
globals-copy.patch martin.panter, 2014-12-17 02:53 review
Pull Requests
URL Status Linked Edit
PR 29823 merged wangjiahua, 2021-11-28 14:46
PR 30041 merged miss-islington, 2021-12-11 00:04
PR 30042 merged miss-islington, 2021-12-11 00:04
Messages (12)
msg204052 - (view) Author: Zahari Dim (Zahari.Dim) Date: 2013-11-23 16:51
The globals() notification states:

Return a dictionary representing the current global symbol table.[...]

This doc and the fact that globals() is called as a function made me think that globals() returns a copy of the global namespace dict, rather than an object that could be used to actually modify the namespace. I don't find obvious the meaning of "representing" in this context.

This of course led to a very nasty and sneaky bug in my code.

The docs of locals() don't seem clear to me either, thought at least it seems to imply that it is actually modifying the namespace.
msg204055 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-11-23 17:06
We've tried improving the locals docs several times.  Modifying it is not "safe", in the sense that what happens when you do is not defined by the language.  Which locals docs were you looking at?

I agree that 'representing' is not as clear as would be optimal in the globals description.  Again, which bit of the docs are you looking at?
msg204128 - (view) Author: Zahari Dim (Zahari.Dim) Date: 2013-11-23 23:37
I am looking at the docs of the built-in functions:
msg204769 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-11-30 03:25
In my opinion, vague ideas like this one should go to python-ideas first.

I agree with David that globals() and locals() are separate issues. Since there have been and perhaps still are locals() doc issues, I will take this one to be about 'globals()'.

A 'symbol table' is a mapping between 'symbols' and 'values'. I presume such were originally implemented as a concrete list of pairs, but the term is now is an abstraction. In the Python context, I think 'namespace' would be a better word, but I would not make the change without getting other opinions, such as on python-ideas. 

The [...] that you omitted says "This is always the dictionary of the current module (...)." I cannot interpret 'is' to mean a copy. So I think "[concrete] dictionary represents [abstract] symbol table [namespace]" is fine.
msg204777 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2013-11-30 05:31
How about swapping the two sentences for globals() then:

“Returns the dictionary of the module . . . This represents the symbol table . . .”

I thought the current locals() entry is fairly clear. It actually says _not_ to modify the dictionary!
msg232796 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2014-12-17 02:51
Here is a patch with my suggestion. It also now refers to _the_ dictionary rather than just _a_ dictionary, and drops the word “current”, so that it does not sound like saving a snapshot.
msg243430 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2015-05-17 22:13
My succinct version:

Return the dictionary implementing the current module namespace. For code within functions, this is set when the function is defined and remains the same regardless of where a function is called.
msg243547 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-05-18 22:46
Terry’s “dictionary implementing the namespace” version would work for me.
msg408277 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-12-11 00:04
New changeset 4fe5585240f64c3d14eb635ff82b163f92074b3a by 180909 in branch 'main':
bpo-19737: Improved the documentation for globals (GH-29823)
msg408281 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-12-11 00:32
New changeset 1f7000808e8385e2a29ffd0ef6aac9a6139d3d92 by Miss Islington (bot) in branch '3.10':
bpo-19737: Improved the documentation for globals (GH-29823) (GH-30041)
msg408282 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-12-11 00:32
New changeset 9299e3a39c3b1dd7d5db0d88080249c2dab3070f by Miss Islington (bot) in branch '3.9':
bpo-19737: Improved the documentation for globals (GH-29823) (GH-30042)
msg408283 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-12-11 00:33
Thanks! ✨ 🍰 ✨
Date User Action Args
2022-04-11 14:57:54adminsetgithub: 63936
2021-12-11 00:33:08lukasz.langasetstatus: open -> closed
resolution: fixed
messages: + msg408283

stage: patch review -> resolved
2021-12-11 00:32:33lukasz.langasetmessages: + msg408282
2021-12-11 00:32:28lukasz.langasetmessages: + msg408281
2021-12-11 00:04:39miss-islingtonsetpull_requests: + pull_request28268
2021-12-11 00:04:32miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request28267
2021-12-11 00:04:24lukasz.langasetnosy: + lukasz.langa
messages: + msg408277
2021-11-28 14:46:17wangjiahuasetnosy: + wangjiahua

pull_requests: + pull_request28055
stage: patch review
2021-11-27 12:45:44iritkatrielsetkeywords: + easy
versions: + Python 3.9, Python 3.10, Python 3.11, - Python 2.7, Python 3.4, Python 3.5
2015-05-18 22:46:45martin.pantersetmessages: + msg243547
2015-05-17 22:13:16terry.reedysetmessages: + msg243430
versions: + Python 3.5, - Python 3.3
2014-12-17 02:53:53martin.pantersetfiles: - globals-copy.patch
2014-12-17 02:53:41martin.pantersetfiles: + globals-copy.patch
2014-12-17 02:51:42martin.pantersetfiles: + globals-copy.patch
keywords: + patch
messages: + msg232796
2013-11-30 05:31:16martin.pantersetmessages: + msg204777
2013-11-30 03:25:54terry.reedysetnosy: + terry.reedy

messages: + msg204769
versions: + Python 2.7, Python 3.3, Python 3.4
2013-11-24 00:01:25martin.pantersetnosy: + martin.panter
2013-11-23 23:37:04Zahari.Dimsetmessages: + msg204128
2013-11-23 17:06:39r.david.murraysetnosy: + r.david.murray
messages: + msg204055
2013-11-23 16:51:01Zahari.Dimcreate