Slightly modify locals() doc?

[terryjreedy]

BPO	655271
Nosy	@rhettinger, @terryjreedy

^{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 = 'https://github.com/rhettinger'
closed_at = <Date 2003-01-04.02:18:16.000>
created_at = <Date 2002-12-17.16:46:54.000>
labels = ['docs']
title = 'Slightly modify locals() doc?'
updated_at = <Date 2003-01-04.02:18:16.000>
user = 'https://github.com/terryjreedy'

bugs.python.org fields:

activity = <Date 2003-01-04.02:18:16.000>
actor = 'rhettinger'
assignee = 'rhettinger'
closed = True
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2002-12-17.16:46:54.000>
creator = 'terry.reedy'
dependencies = []
files = []
hgrepos = []
issue_num = 655271
keywords = []
message_count = 2.0
messages = ['13654', '13655']
nosy_count = 2.0
nosy_names = ['rhettinger', 'terry.reedy']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue655271'
versions = []

[terryjreedy]

Lib ref manual 2.1 builtin funcs: locals() says
"Return a dictionary representing the current local
symbol table"
This can be (and has been, by experience users)
interpreted as "return a *new* dictionary..."

It would better describe current behavior if it said:
"Update and return the dictionary...."
This would make the following less surprising:

>>> def f():
...   foo = 'bar'
...   a = locals()
...   a['foo'] = 'Guido'
...   try: print a['a']
...   except: print "'a' is not in a"
...   print a['foo'], locals()['foo'], a['foo'], a['a']
...
>>> f()
'a' is not in a
Guido bar bar {'a': {...}, 'foo': 'bar'}

[rhettinger]

Logged In: YES
user_id=80475

Applied as libfuncs.tex 1.127 and bltinmodule.c 2.270.
Closing bug.