[docs] [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 <report at bugs.python.org>
<http://bugs.python.org/issue26449>
_______________________________________