Merged revisions 74817-74820,74822-74824 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r74817 | georg.brandl | 2009-09-16 11:05:11 +0200 (Mi, 16 Sep 2009) | 1 line

  Make deprecation notices as visible as warnings are right now.
........
  r74818 | georg.brandl | 2009-09-16 11:23:04 +0200 (Mi, 16 Sep 2009) | 1 line

  #6880: add reference to classes section in exceptions section, which comes earlier.
........
  r74819 | georg.brandl | 2009-09-16 11:24:57 +0200 (Mi, 16 Sep 2009) | 1 line

  #6876: fix base class constructor invocation in example.
........
  r74820 | georg.brandl | 2009-09-16 11:30:48 +0200 (Mi, 16 Sep 2009) | 1 line

  #6891: comment out dead link to Unicode article.
........
  r74822 | georg.brandl | 2009-09-16 12:12:06 +0200 (Mi, 16 Sep 2009) | 1 line

  #5621: refactor description of how class/instance attributes interact on a.x=a.x+1 or augassign.
........
  r74823 | georg.brandl | 2009-09-16 15:06:22 +0200 (Mi, 16 Sep 2009) | 1 line

  Remove strange trailing commas.
........
  r74824 | georg.brandl | 2009-09-16 15:11:06 +0200 (Mi, 16 Sep 2009) | 1 line

  #6892: fix optparse example involving help option.
........

1 files changed, 21 insertions, 10 deletions

diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index 46eea20..a8ec495 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -170,6 +170,25 @@ Assignment of an object to a single target is recursively defined as follows.
   perform the assignment, it raises an exception (usually but not necessarily
   :exc:`AttributeError`).
 
+  .. _attr-target-note:
+
+  Note: If the object is a class instance and the attribute reference occurs on
+  both sides of the assignment operator, the RHS expression, ``a.x`` can access
+  either an instance attribute or (if no instance attribute exists) a class
+  attribute.  The LHS target ``a.x`` is always set as an instance attribute,
+  creating it if necessary.  Thus, the two occurrences of ``a.x`` do not
+  necessarily refer to the same attribute: if the RHS expression refers to a
+  class attribute, the LHS creates a new instance attribute as the target of the
+  assignment::
+
+     class Cls:
+         x = 3             # class variable
+     inst = Cls()
+     inst.x = inst.x + 1   # writes inst.x as 4 leaving Cls.x as 3
+
+  This description does not necessarily apply to descriptor attributes, such as
+  properties created with :func:`property`.
+
   .. index::
      pair: subscription; assignment
      object: mutable
@@ -276,16 +295,8 @@ same way as normal assignments. Similarly, with the exception of the possible
 *in-place* behavior, the binary operation performed by augmented assignment is
 the same as the normal binary operations.
 
-For targets which are attribute references, the initial value is retrieved with
-a :meth:`getattr` and the result is assigned with a :meth:`setattr`.  Notice
-that the two methods do not necessarily refer to the same variable.  When
-:meth:`getattr` refers to a class variable, :meth:`setattr` still writes to an
-instance variable. For example::
-
-   class A:
-       x = 3    # class variable
-   a = A()
-   a.x += 1     # writes a.x as 4 leaving A.x as 3
+For targets which are attribute references, the same :ref:`caveat about class
+and instance attributes <attr-target-note>` applies as for regular assignments.
 
 
 .. _assert: