Documentation of globals() and locals() should be improved #63936
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
assignee = None closed_at = <Date 2021-12-11.00:33:08.004> created_at = <Date 2013-11-23.16:51:01.066> labels = ['easy', '3.11', '3.9', '3.10', 'docs'] title = 'Documentation of globals() and locals() should be improved' updated_at = <Date 2021-12-11.00:33:08.002> user = 'https://github.com/Zaharid'
activity = <Date 2021-12-11.00:33:08.002> actor = 'lukasz.langa' assignee = 'docs@python' closed = True closed_date = <Date 2021-12-11.00:33:08.004> closer = 'lukasz.langa' components = ['Documentation'] creation = <Date 2013-11-23.16:51:01.066> creator = 'Zahari.Dim' dependencies =  files = ['37479'] hgrepos =  issue_num = 19737 keywords = ['patch', 'easy'] message_count = 12.0 messages = ['204052', '204055', '204128', '204769', '204777', '232796', '243430', '243547', '408277', '408281', '408282', '408283'] nosy_count = 8.0 nosy_names = ['terry.reedy', 'r.david.murray', 'docs@python', 'lukasz.langa', 'martin.panter', 'Zahari.Dim', 'miss-islington', 'wangjiahua'] pr_nums = ['29823', '30041', '30042'] priority = 'normal' resolution = 'fixed' stage = 'resolved' status = 'closed' superseder = None type = None url = 'https://bugs.python.org/issue19737' versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']
The text was updated successfully, but these errors were encountered:
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.
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?
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.