Redundant sentence in FAQ

[fossilet]

BPO	23589
Nosy	@rhettinger, @rbtcollins, @ezio-melotti, @bitdancer, @demianbrecht
Files	faq_fix.diff faq_fix_1.diff

^{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/ezio-melotti'
closed_at = <Date 2015-07-29.18:21:12.664>
created_at = <Date 2015-03-05.08:32:38.399>
labels = ['type-feature', 'docs']
title = 'Redundant sentence in FAQ'
updated_at = <Date 2015-07-29.18:21:12.664>
user = 'https://bugs.python.org/fossilet'

bugs.python.org fields:

activity = <Date 2015-07-29.18:21:12.664>
actor = 'rbcollins'
assignee = 'ezio.melotti'
closed = True
closed_date = <Date 2015-07-29.18:21:12.664>
closer = 'rbcollins'
components = ['Documentation']
creation = <Date 2015-03-05.08:32:38.399>
creator = 'fossilet'
dependencies = []
files = ['38339', '38340']
hgrepos = []
issue_num = 23589
keywords = ['patch']
message_count = 9.0
messages = ['237248', '237255', '237256', '237261', '237340', '237341', '237365', '247591', '247592']
nosy_count = 8.0
nosy_names = ['rhettinger', 'fossilet', 'rbcollins', 'ezio.melotti', 'r.david.murray', 'docs@python', 'python-dev', 'demian.brecht']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue23589'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5', 'Python 3.6']

[fossilet]

In https://docs.python.org/3/faq/programming.html#what-are-the-rules-for-local-and-global-variables-in-python, two sentences of essentially the same meaning exist. I try to remove this redundancy.

[rhettinger]

How about:

In Python, variables that are only referenced inside a function are implicitly
global. If a variable is assigned a value anywhere within the function's
body, it's assumed to be a local unless explicitly declared as global.

[fossilet]

Updated diff as Raymond's wording.

[ezio-melotti]

I think the first sentence could be improved, even though it's correct.
A superficial reading might give the impression that function variables are implicitly global, or that only the variables inside a function are global, especially if the reader is not familiar with the term "referenced".
Swapping the two sentences and talking first about assignment might be enough to make clear that the other sentence is talking about variables that are only read/accessed by the function but not defined/assigned.
The paragraph can also be rephrased to say that Python can freely access variables from outer scopes, but that "global" is required to assign a new value to a global variable, and that variables defined inside a function are local.

[fossilet]

What about changing the first sentence to:

In Python, variables that are only referenced but not assigned inside a function are implicitly global.?

[fossilet]

Or:

In Python, variables inside a function that are only referenced but not assigned are implicitly global.?

[demianbrecht]

Not to throw a wrench into this, but would it perhaps not be worthwhile to refactor this section in order to include nonlocals as well (obviously not for 2.7)? It seems a little odd to me to have this amount of detail without mentioning nonlocal.

[rbtcollins]

@demian, I agree that there are more improvements we can make. The current patch addresses the specific issue of this bug, and if you wished to make a new issue with further improvements that would be great. I'm going to apply this patch now though.

[python-dev]

New changeset 02f3bf3f74aa by Robert Collins in branch '2.7':
Issue bpo-23589: Remove duplicate sentence from the FAQ. Patch by Yongzhi Pan.
https://hg.python.org/cpython/rev/02f3bf3f74aa

New changeset 941b9c27b8c8 by Robert Collins in branch '3.4':
Issue bpo-23589: Remove duplicate sentence from the FAQ. Patch by Yongzhi Pan.
https://hg.python.org/cpython/rev/941b9c27b8c8

New changeset 93f3ca8fdc39 by Robert Collins in branch '3.5':
Issue bpo-23589: Remove duplicate sentence from the FAQ. Patch by Yongzhi Pan.
https://hg.python.org/cpython/rev/93f3ca8fdc39

New changeset 7163dd7e9511 by Robert Collins in branch 'default':
Issue bpo-23589: Remove duplicate sentence from the FAQ. Patch by Yongzhi Pan.
https://hg.python.org/cpython/rev/7163dd7e9511