[issue26449] Tutorial on Python Scopes and Namespaces uses confusing 'read-only' terminology

[Steve Holden]

Steve Holden added the comment:

I don't agree there is any place for the term "read-only" in this document. A 
reader who doesn't understand it or seeks clarification is likely to end up at 
a page like https://en.wikipedia.org/wiki/Read-only. I submit that nowhere 
except the documentation under discussion are they likely to find any 
suggestion that a read-only variable can in fact be changed, and hence I regard 
the discussion as extremely misleading.

Surely it would be better to focus on the fundamental point here, which is that 
IN THE ABSENCE OF A global OR nonlocal DECLARATION, ASSIGNMENT BINDS IN THE 
LOCAL NAMESPACE in a function.

If this point is correctly emphasised it should then be relatively easy to 
explain that in the absence of such an assignment in the function body in 
question, the standard name resolution algorithm operates, and that the global 
and non-local declarations change the effect of assignments to operate on the 
namespace that is identified by the standard name resolution algorithm.

It's too easy to confuse newcomers, and there seems to be general agreement 
that this piece is confusing. I'll be happy to attempt a rewrite of this 
section if we can agree on the goals.

--
nosy: +holdenweb

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26449] Tutorial on Python Scopes and Namespaces uses confusing 'read-only' terminology

[Martijn Pieters]

Martijn Pieters added the comment:

+1 for "... can only be read". read-only can too easily be construed to mean 
that the variable cannot be set from *anywhere*, even the original scope. 
Another alternative would be "... is effectively read-only", but "... can only 
be read" is simpler.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26449] Tutorial on Python Scopes and Namespaces uses confusing 'read-only' terminology

[Georg Brandl]

Georg Brandl added the comment:

I think rephrasing with "... can only be read" would keep the intended meaning, 
but avoid the problematic "the namespaces are readonly" meaning.

--
nosy: +georg.brandl

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26449] Tutorial on Python Scopes and Namespaces uses confusing 'read-only' terminology

[Ezio Melotti]

Ezio Melotti added the comment:

I agree with Raymond.  IMHO the term "read-only" does a good job at conveying 
the fact that you can still access/read the value of the variable but you can't 
assign to it.  "read-only" is about /what/ you can do with the variable, even 
though it would also be good to clarify /why/ you can only read.

--
nosy: +ezio.melotti

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26449] Tutorial on Python Scopes and Namespaces uses confusing 'read-only' terminology

[Raymond Hettinger]

Raymond Hettinger added the comment:

FWIW, the learners in my Python classes seem to find the words "read-only" to 
be helpful.  Also, I think "not visible" conveys the wrong mental model 
("shadowed" being a little more accurate).  

I also disagree with saying that "variables are never read-only". In fact, 
unless declared "nonlocal", the namespace for the nested scope can't be written 
to; likewise, we also have dict proxies in classes that are specifically 
designed to be read-only; further, there are many read-only attributes in 
Python.

The current paragraph is succinct and accurate.   That said, there is no doubt 
that creative people can find ways to misread it, so I think  there is room to 
add an extra paragraph that elaborates on the rules:

1) variable *lookups* will search from locals to nested scopes to globals to 
builtins, stopping at the first match or raising NameError if not found; and, 

2) variable *writes* always go into locals unless explicitly declared as being 
in another namespace with "nonlocal" or "global".

The docs can't smooth this over by changing a single misinterpreted word.  One 
way or another, either in the tutorial or in a FAQ, users need to learn why x=1 
doesn't write to an enclosing scope without a namespace declaration and why 
self.x+=1 can read a class variable, increment the value, and then write to an 
instance variable.  Learning this is fundamental to understanding the language 
and it can't be glossed over by saying that the word "read-only" was confusing. 
 Everyone gets what "read-only" means; instead, the challenge is to grapple 
with what the rules are and why the language behaves this way.

--
nosy: +rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26449] Tutorial on Python Scopes and Namespaces uses confusing 'read-only' terminology

[Martijn Pieters]

Changes by Martijn Pieters :


--
assignee:  -> docs@python
components: +Documentation
nosy: +docs@python

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue26449] Tutorial on Python Scopes and Namespaces uses confusing 'read-only' terminology

[Martijn Pieters]

New submission from Martijn Pieters:

>From the 9.2. Python Scopes and Namespace section:

> If a name is declared global, then all references and assignments go directly 
> to the middle scope containing the module’s global names. To rebind variables 
> found outside of the innermost scope, the nonlocal statement can be used; if 
> not declared nonlocal, those variable are read-only (an attempt to write to 
> such a variable will simply create a new local variable in the innermost 
> scope, leaving the identically named outer variable unchanged).

This terminology is extremely confusing to newcomers; see 
https://stackoverflow.com/questions/35667757/read-only-namespace-in-python for 
an example. Variables are never read-only. The parent scope name simply is *not 
visible*, which is an entirely different concept. Can this section be 
re-written to not use the term 'read-only'?

--
messages: 260933
nosy: mjpieters
priority: normal
severity: normal
status: open
title: Tutorial on Python Scopes and Namespaces uses confusing 'read-only' 
terminology

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com