[issue5621] Add description of special case to "Assignment statements" section

[John Posner]

New submission from John Posner <john_posner_ab71 at post.harvard.edu>:

The subsection "Augmented assignment statements" includes a note on this
special case:

  a.x += 1

But the parent section "Assignment statements" does not include such a
note, even though it's essentially the same situation. I suggest
replacing the bulleted paragraph that begins "If the target is an
attribute reference" with the following:

---------

*   If the target is an attribute reference: The primary expression in
    the reference is evaluated. It should yield an object with
    assignable attributes; if this is not the case, TypeError is raised.
    That object is then asked to assign the assigned object to the given
    attribute; if it cannot perform the assignment, it raises an
    exception (usually but not necessarily AttributeError).

    If the object is a class instance and the attribute
    reference occurs on both sides of the assignment operator; for example::

        a.x = a.x + 1

    ... in the RHS expression, ``a.x`` is evaluated with
    ``getattr()``, which can access either an instance attribute or (if
    no instance attribute exists) a class attribute. The LHS target
    ``a.x`` is assigned with ``setattr()``, which *always* accesses
    an instance attribute, creating it if necessary. Thus, the two
    occurrences of ``a.x`` do not necessarily refer to the same
    variable. If the RHS expression refers to a class attribute, the LHS
    creates a new instance attribute as the target of the assignment.
    (This description does not necessarily
    apply to attributes defined with ``property()``, which are accessed
    with user-defined functions instead of ``getattr()`` and ``setattr()``).

    See section "Augmented assignment statements" for a similar note on
    attribute references.

---------

----------
assignee: georg.brandl
components: Documentation
messages: 84790
nosy: georg.brandl, jjposner
severity: normal
status: open
title: Add description of special case to "Assignment statements" section
versions: Python 2.6, Python 3.0

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