classification
Title: Augmented Assignment / Operations Confusion in Documentation
Type: Stage:
Components: Documentation Versions: Python 3.0
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: acooke, georg.brandl
Priority: normal Keywords:

Created on 2009-01-18 13:45 by acooke, last changed 2009-01-18 18:35 by acooke. This issue is now closed.

Messages (3)
msg80098 - (view) 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
msg80112 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) 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.
msg80113 - (view) Author: andrew cooke (acooke) Date: 2009-01-18 18:35
thanks!
History
Date User Action Args
2009-01-18 18:35:39acookesetmessages: + msg80113
2009-01-18 18:27:21georg.brandlsetstatus: open -> closed
resolution: fixed
messages: + msg80112
2009-01-18 13:45:50acookecreate