Issue 4986: Augmented Assignment / Operations Confusion in Documentation (original) (raw)
Created on 2009-01-18 13:45 by acooke, last changed 2022-04-11 14:56 by admin. This issue is now closed.
Messages (3)
Author: andrew cooke (acooke)
Date: 2009-01-18 13:45
There's a small confusion in terminology in the documentation related to methods that implement augmented assignment.
The "Expressions" section of the language reference ("Simple statements") refers to augmented assignment - http://docs.python.org/3.0/reference/simple_stmts.html#augmented-assignment-statements
- and this seems to be a carefully chosen (and correct) phrase because the parsing is related to assignments, which are augmented with various operators.
It is important to note that augmented assignments ("+=" etc) are not parsed as operators. It is syntax error to use them in many places where an operator would be accepted.
In the "Data Model" section, however, things are less clear http://docs.python.org/3.0/reference/datamodel.html#emulating-numeric-types . The methods used to implement augmented assignment are grouped near those used to implement arithmetic operators. That seems natural. But the text confuses the two more than is strictly necessary. In particular there is the phrase "augmented arithmetic operations".
As I have already tried to make clear, these are not operations. They are augmented assignments. Calling them operations is misleading, because they cannot be used in the same places as "real" operations - the parser simply will not accept them.
Apart from changing "augmented arithmetic operations" to "augmented assignments" it might be worth adding some kind of note that explains to the user that the parser calls those methods to implement assignment, and that they are not valid in the same syntax as operations.
I am not sure the following will help, but it does illustrate the confusion caused - http://groups.google.com/group/comp.lang.python/browse_thread/thread/f1322928300b2b71
Cheers, Andrew
Author: Georg Brandl (georg.brandl) * 
Date: 2009-01-18 18:27
Fixed in r68727.
IMO, "augmented operation" was an acceptable term -- the term "operator" is not strictly limited to operators usable in expressions in Python. However, since it's called "augmented assignment" everywhere else, it's better here too for consistency.
A real mistake was that the same paragraph called "a += b" an expression -- it really is a statement. Fixed that too.
Author: andrew cooke (acooke)
Date: 2009-01-18 18:35
thanks!
History
Date
User
Action
Args
2022-04-11 14:56:44
admin
set
github: 49236
2009-01-18 18:35:39
acooke
set
messages: +
2009-01-18 18:27:21
georg.brandl
set
status: open -> closed
resolution: fixed
messages: +
2009-01-18 13:45:50
acooke
create