[Python-checkins] cpython (3.3): #19953: Clarify the wording of the augmented assignment discussion.

[r.david.murray]

http://hg.python.org/cpython/rev/f9cb5a44879c
changeset:   89540:f9cb5a44879c
branch:      3.3
parent:      89534:c3836de644e0
user:        R David Murray <rdmurray at bitdance.com>
date:        Sun Mar 09 18:51:16 2014 -0400
summary:
  #19953: Clarify the wording of the augmented assignment discussion.

Patch by Priya Pappachan, based on suggestions from Terry Reedy
and myself.

files:
  Doc/faq/programming.rst     |   1 +
  Doc/reference/datamodel.rst |  12 +++++++-----
  2 files changed, 8 insertions(+), 5 deletions(-)


diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst
--- a/Doc/faq/programming.rst
+++ b/Doc/faq/programming.rst
@@ -1103,6 +1103,7 @@
 
    result = [obj.method() for obj in mylist]
 
+.. _faq-augmented-assignment-tuple-error:
 
 Why does a_tuple[i] += ['item'] raise an exception when the addition works?
 ---------------------------------------------------------------------------
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -2023,11 +2023,13 @@
    ``&=``, ``^=``, ``|=``).  These methods should attempt to do the operation
    in-place (modifying *self*) and return the result (which could be, but does
    not have to be, *self*).  If a specific method is not defined, the augmented
-   assignment falls back to the normal methods.  For instance, to execute the
-   statement ``x += y``, where *x* is an instance of a class that has an
-   :meth:`__iadd__` method, ``x.__iadd__(y)`` is called.  If *x* is an instance
-   of a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)``
-   and ``y.__radd__(x)`` are considered, as with the evaluation of ``x + y``.
+   assignment falls back to the normal methods.  For instance, if *x* is an
+   instance of a class with an :meth:`__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``. In certain situations,
+   augmented assignment can result in unexpected errors (see
+   :ref:`faq-augmented-assignment-tuple-error`), but this behavior is in
+   fact part of the data model.
 
 
 .. method:: object.__neg__(self)

-- 
Repository URL: http://hg.python.org/cpython