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