Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation of globals() and locals() should be improved #63936

Closed
Zaharid mannequin opened this issue Nov 23, 2013 · 12 comments
Closed

Documentation of globals() and locals() should be improved #63936

Zaharid mannequin opened this issue Nov 23, 2013 · 12 comments
Labels
3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir easy

Comments

@Zaharid
Copy link
Mannequin

Zaharid mannequin commented Nov 23, 2013

BPO 19737
Nosy @terryjreedy, @bitdancer, @ambv, @vadmium, @Zaharid, @miss-islington, @180909
PRs
  • bpo-19737: Improved the documentation for globals #29823
  • [3.10] bpo-19737: Improved the documentation for globals (GH-29823) #30041
  • [3.9] bpo-19737: Improved the documentation for globals (GH-29823) #30042
    		•
    Files
  • globals-copy.patch
    		•

    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

    GitHub fields:

    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'

    bugs.python.org fields:

    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']
    @Zaharid
    Copy link
    Mannequin Author

    Zaharid mannequin commented Nov 23, 2013

    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.

    @Zaharid Zaharid mannequin assigned docspython Nov 23, 2013
    @Zaharid Zaharid mannequin added the docs Documentation in the Doc dir label Nov 23, 2013
    @bitdancer
    Copy link
    Member

    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?

    @Zaharid
    Copy link
    Mannequin Author

    Zaharid mannequin commented Nov 23, 2013

    I am looking at the docs of the built-in functions:

    http://docs.python.org/2/library/functions.html

    @terryjreedy
    Copy link
    Member

    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.

    @vadmium
    Copy link
    Member

    vadmium commented Nov 30, 2013

    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!

    @vadmium
    Copy link
    Member

    vadmium commented Dec 17, 2014

    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.

    @terryjreedy
    Copy link
    Member

    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.

    @vadmium
    Copy link
    Member

    vadmium commented May 18, 2015

    Terry’s “dictionary implementing the namespace” version would work for me.

    @iritkatriel iritkatriel added easy 3.9 only security fixes 3.10 only security fixes 3.11 only security fixes labels Nov 27, 2021
    @ambv
    Copy link
    Contributor

    ambv commented Dec 11, 2021

    New changeset 4fe5585 by 180909 in branch 'main':
    bpo-19737: Improved the documentation for globals (GH-29823)
    4fe5585

    @ambv
    Copy link
    Contributor

    ambv commented Dec 11, 2021

    New changeset 1f70008 by Miss Islington (bot) in branch '3.10':
    bpo-19737: Improved the documentation for globals (GH-29823) (GH-30041)
    1f70008

    @ambv
    Copy link
    Contributor

    ambv commented Dec 11, 2021

    New changeset 9299e3a by Miss Islington (bot) in branch '3.9':
    bpo-19737: Improved the documentation for globals (GH-29823) (GH-30042)
    9299e3a

    @ambv
    Copy link
    Contributor

    ambv commented Dec 11, 2021

    Thanks! ✨ 🍰 ✨

    @ambv ambv closed this as completed Dec 11, 2021
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.9 only security fixes 3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir easy
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    5 participants
    @ambv @bitdancer @vadmium @iritkatriel @terryjreedy