Incorporate Guido's decision to go for '__iadd__' for the Python class

hooks, and trim the 'open isues': PyNumber_InPlacePower() is now a
trinary function, like PyNumber_Power(), and I'm working on the docs and the
library.

pep-0203.txt

@@ -62,12 +62,12 @@ Proposed semantics
     
         x += y
     
-    tries to call x.__add_ab__(y), which is the `in-place' variant of
-    __add__. If __add_ab__ is not present, x.__add__(y) is
+    tries to call x.__iadd__(y), which is the `in-place' variant of
+    __add__. If __iadd__ is not present, x.__add__(y) is
     attempted, and finally y.__radd__(x) if __add__ is missing too. 
-    There is no `right-hand-side' variant of __add_ab__, because that
+    There is no `right-hand-side' variant of __iadd__, because that
     would require for `y' to know how to in-place modify `x', which is
-    unsafe to say the least. The __add_ab__ hook should behave similar
+    unsafe to say the least. The __add__ hook should behave similar
     to __add__, returning the result of the operation (which could be
     `self') which is to be stored in the variable `x'.
  
@@ -139,22 +139,19 @@ New methods
     which Python classes can implement to overload the augmented
     assignment operations:
     
-        __add_ab__
-        __sub_ab__
-        __mul_ab__
-        __div_ab__
-        __mod_ab__
-        __pow_ab__
-        __lshift_ab__
-        __rshift_ab__
-        __and_ab__
-        __xor_ab__
-        __or_ab__
+        __iadd__
+        __isub__
+        __imul__
+        __idiv__
+        __imod__
+        __ipow__
+        __ilshift__
+        __irshift__
+        __iand__
+        __ixor__
+        __ior__
     
-    The `__add_ab__' name is one proposed by Guido[1], and stands for
-    `and becomes'. Other proposed names include `__iadd__',
-    `__add_in__' and `__inplace_add__'. A firm decision by the BDFL is
-    probably needed to finalize this issue.
+    The `i' in `__iadd__' stands for `in-place'.
 
     For C extension types, the following struct members are added:
     
@@ -260,20 +257,11 @@ Implementation
 
 Open Issues
 
-    The PyNumber_InPlacePower() function only takes two arguments, not
-    one like PyNumber_Power(). This is because there is no way to do
-    an inplace three-argument-power trough the augmented assignment
-    syntax or the power() function.
-    
+    The PyNumber_InPlace API is only a subset of the normal PyNumber
+    API: only those functions that are required to support the
+    augmented assignment syntax are included. If other in-place API
+    functions are needed, they can be added later.
 
-    Possibly a more obvious name for the Python hooks can be found. 
-    `_ab_' is what Guido proposed[1] as a working name, and comes from
-    an old Algol-68 naming convention.
-
-
-    Documentation needs to be written. The reference manual, the `dis'
-    section of the library manual, and possibly the tutorial.
-    
 
     The DUP_TOPX bytecode is a conveniency bytecode, and is not
     actually necessary. It should be considered whether this bytecode
@@ -281,10 +269,6 @@ Open Issues
     bytecode at this time.
     
 
-    The standard library should be adjusted to provide augmented
-    assignment hooks, where sensible.
-
-
     It is not possible to do an inplace operation in the variant of
     
        <builtin type> += <instance object>
@@ -303,8 +287,7 @@ Copyright
 References
 
     [1] http://www.python.org/pipermail/python-list/2000-June/059556.html
-    [2]
-http://sourceforge.net/patch?func=detailpatch&patch_id=100699&group_id=5470
+    [2] http://sourceforge.net/patch?func=detailpatch&patch_id=100699&group_id=5470
     [3] PEP 211, Adding New Linear Algebra Operators,
         http://python.sourceforge.net/peps/pep-0211.html