This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: __iadd__() doc not strictly correct
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, ferno, r.david.murray, terry.reedy
Priority: normal Keywords: patch

Created on 2013-12-11 20:13 by ferno, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
my.patch priyapappachan, 2014-03-09 19:24 review
my.patch priyapappachan, 2014-03-09 20:35 review
my.patch priyapappachan, 2014-03-09 22:16 Error in including hyperlink in datamodel.rst review
Pull Requests
URL Status Linked Edit
PR 11763 closed feliam, 2019-02-06 21:12
PR 11763 closed feliam, 2019-02-06 21:12
PR 11763 closed feliam, 2019-02-06 21:12
Messages (5)
msg205920 - (view) Author: (ferno) Date: 2013-12-11 20:13
Document in question is:

    http://docs.python.org/3.3/reference/datamodel.html#object.__iadd__

The documentation states,

    to execute the statement x += y, where x is an instance of a class that has an __iadd__() method, x.__iadd__(y) is called.

However, this doesn't appear to be strictly true. According to this, the following well-known example:

    >>> a = (1, [2, 3])
    >>> a[1] += [4, 5]
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: 'tuple' object does not support item assignment
    >>> a
    (1, [2, 3, 4, 5])

should give the same behaviour as:

    >>> a = (1, [2, 3])
    >>> a[1].__iadd__([4, 5])
    [2, 3, 4, 5]
    >>> a
    (1, [2, 3, 4, 5])

However, this snippet DOES give the identical behaviour:

    >>> a = (1, [2, 3])
    >>> a[1] = a[1].__iadd__([4, 5])
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: 'tuple' object does not support item assignment
    >>> a
    (1, [2, 3, 4, 5])

which leads me to suggest that this line of the documentation should be adjusted to read:

    to execute the statement x += y, where x is an instance of a class that has an __iadd__() method, x = x.__iadd__(y) is called.

This fix would incidentally harmonise with the documentation for operator.iadd() et al., (http://docs.python.org/3.3/library/operator.html#operator.iadd), which had a similar problem but was corrected following issue 7259 (http://bugs.python.org/issue7259), now reading:

    a = iadd(a, b) is equivalent to a += b.
msg206163 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-12-14 02:55
The current doc is correct. Unlike the old incorrect version of the operator doc (#7259), it does not say that the call is all of the execution. The suggested replacement "x = x.__iadd__(y) is called" is not correct as statements are not called.

The said, it seems that some people miss the fact that augmented assignment always does an assignment. So, considering that the first sentence of the paragraph, "These methods are called to implement the augmented arithmetic assignments (+=, -=, *=, /=, //=, %=, **=, <<=, >>=, &=, ^=, |=)." already talks about calling, I thing

"For instance, to execute the statement x += y, where x is an instance of a class that has an __iadd__() method, x.__iadd__(y) is called. If x is an instance of a class that does not define a __iadd__() method, x.__add__(y) and y.__radd__(x) are considered, as with the evaluation of x + y."

might be replaced by

"For instance, if x is an instance of a class with an __iadd__() method, x += y is equivalent to x = x.__iadd__(y) . Otherwise, x.__add__(y) and y.__radd__(x) are considered, as with the evaluation of x + y."
msg212980 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-03-09 19:42
I wonder if it would be worth adding a sentence that says, "In certain situations, augmented assignment can result in unexpected errors (see http://docs.python.org/3/faq/programming.html#id44)."
msg212999 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-03-09 22:52
New changeset f9cb5a44879c by R David Murray in branch '3.3':
#19953: Clarify the wording of the augmented assignment discussion.
http://hg.python.org/cpython/rev/f9cb5a44879c

New changeset 61ceb299a255 by R David Murray in branch 'default':
Merge #19953: Clarify the wording of the augmented assignment discussion.
http://hg.python.org/cpython/rev/61ceb299a255
msg213000 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-03-09 22:57
Thanks, Pryia.
History
Date User Action Args
2022-04-11 14:57:55adminsetgithub: 64152
2019-02-06 21:12:58feliamsetpull_requests: + pull_request11752
2019-02-06 21:12:49feliamsetpull_requests: + pull_request11751
2019-02-06 21:12:40feliamsetpull_requests: + pull_request11750
2014-03-09 22:57:21r.david.murraysetstatus: open -> closed

type: enhancement

nosy: - python-dev
messages: + msg213000
resolution: fixed
stage: needs patch -> resolved
2014-03-09 22:52:08python-devsetnosy: + python-dev
messages: + msg212999
2014-03-09 22:16:40priyapappachansetfiles: + my.patch
2014-03-09 20:35:16priyapappachansetfiles: + my.patch
2014-03-09 19:42:33r.david.murraysetnosy: + r.david.murray
messages: + msg212980
2014-03-09 19:24:08priyapappachansetfiles: + my.patch
2013-12-14 02:55:31terry.reedysetversions: - Python 2.6, Python 3.1, Python 3.2, Python 3.5
nosy: + terry.reedy

messages: + msg206163

keywords: + patch
stage: needs patch
2013-12-11 20:13:08fernocreate