[issue16701] Docs missing the behavior of += (in-place add) for lists.

[benrg]

benrg added the comment:

This is bizarre:

Python 3.3.0 (v3.3.0:bd8afb90ebf2, Sep 29 2012, 10:55:48) [MSC v.1600 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> x = y = [1, 2]
>>> x += [3]
>>> y
[1, 2, 3]
>>> x = y = {1, 2}
>>> x -= {2}
>>> y
{1}
>>>

Since when has this been standard behavior? The documentation says:

"An augmented assignment expression like x += 1 can be rewritten as x = x + 1 to achieve a similar, but not exactly equal effect. In the augmented version, x is only evaluated once. Also, when possible, the actual operation is performed in-place, meaning that rather than creating a new object and assigning that to the target, the old object is modified instead."

What is "when possible" supposed to mean here? I always thought it meant "when there are known to be no other references to the object". If op= is always destructive on lists and sets, then "where possible" needs to be changed to "always" and a prominent warning added, like "WARNING: X OP= EXPR DOES NOT BEHAVE EVEN REMOTELY LIKE X = X OP EXPR IN PYTHON WHEN X IS A MUTABLE OBJECT, IN STARK CONTRAST TO EVERY OTHER LANGUAGE WITH A SIMILAR SYNTAX."

----------
nosy: +benrg

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue16701>
_______________________________________