New version from Travis.

pep-0357.txt

@@ -10,63 +10,84 @@ Python-Version: 2.5
 
 Abstract
 
-  This PEP proposes adding an nb_as_index slot in PyNumberMethods and
-  an __index__ special method so that arbitrary objects can be used
-  in slice syntax.
+    This PEP proposes adding an nb_index slot in PyNumberMethods and an
+    __index__ special method so that arbitrary objects can be used
+    whenever only integers are called for in Python, such as in slice
+    syntax (from which the slot gets its name).
 
 Rationale
 
-  Currently integers and long integers play a special role in slice
-  notation in that they are the only objects allowed in slice
-  syntax. In other words, if X is an object implementing the sequence
-  protocol, then X[obj1:obj2] is only valid if obj1 and obj2 are both
-  integers or long integers.  There is no way for obj1 and obj2 to
-  tell Python that they could be reasonably used as indexes into a
-  sequence.  This is an unnecessary limitation.
+    Currently integers and long integers play a special role in slice
+    notation in that they are the only objects allowed in slice
+    syntax. In other words, if X is an object implementing the sequence
+    protocol, then X[obj1:obj2] is only valid if obj1 and obj2 are both
+    integers or long integers.  There is no way for obj1 and obj2 to
+    tell Python that they could be reasonably used as indexes into a
+    sequence.  This is an unnecessary limitation.
 
-  In NumPy, for example, there are 8 different integer scalars
-  corresponding to unsigned and signed integers of 8, 16, 32, and 64
-  bits.  These type-objects could reasonably be used as indexes into
-  a sequence if there were some way for their typeobjects to tell
-  Python what integer value to use.
+    In NumPy, for example, there are 8 different integer scalars
+    corresponding to unsigned and signed integers of 8, 16, 32, and 64
+    bits.  These type-objects could reasonably be used as integers in
+    many places where Python expects true integers. There should be
+    some way to be able to tell Python that an object can behave like
+    an integer.
+
+    It is not possible to use the nb_int (and __int__ special method)
+    for this purpose because that method is used to *coerce* objects to
+    integers.  It would be inappropriate to allow every object that can
+    be coerced to an integer to be used as an integer everywhere Python
+    expects a true integer.
 
 Proposal
-
-  Add a nb_index slot to PyNumberMethods, and a corresponding
-  __index__ special method.  Objects could define a function to
-  place in the sq_index slot that returns an appropriate
-  C-integer for use as ilow or ihigh in PySequence_GetSlice,
-  PySequence_SetSlice, and PySequence_DelSlice.
+ 
+    Add a nb_index slot to PyNumberMethods, and a corresponding
+    __index__ special method.  Objects could define a function to place
+    in the nb_index slot that returns an appropriate C-integer for use
+    as ilow or ihigh in PySequence_GetSlice, PySequence_SetSlice, and
+    PySequence_DelSlice.
 
 Implementation Plan
 
-  1) Add the slots
+    1) Add the nb_index slot in object.h and modify typeobject.c to 
+       create the __index__ method. 
 
-  2) Change the ISINT macro in ceval.c to ISINDEX and alter it to
-     accomodate objects with the index slot defined.
+    2) Change the ISINT macro in ceval.c to ISINDEX and alter it to 
+       accomodate objects with the index slot defined.
 
-  3) Change the _PyEval_SliceIndex function to accomodate objects
-     with the index slot defined.
+    3) Change the _PyEval_SliceIndex function to accomodate objects
+       with the index slot defined.
+
+    4) Change all builtin objects that use the subscript form and
+       special-check for integers to check for the slot as well
+
+    5) Add PyNumber_Index C-API to return an integer from any 
+       Python Object that has the nb_index slot.
+
+    6) Add an operator.index(x) function that calls x.__index__()
 
 Possible Concerns
 
-  Speed:
+    Speed: 
 
-  Implementation should not slow down Python because integers and long
-  integers used as indexes will complete in the same number of
-  instructions.  The only change will be that what used to generate
-  an error will now be acceptable.
+    Implementation should not slow down Python because integers and long
+    integers used as indexes will complete in the same number of
+    instructions.  The only change will be that what used to generate
+    an error will now be acceptable.
 
-  Why not use nb_int which is already there?
+    Why not use nb_int which is already there?:
 
-  The nb_int, nb_oct, and nb_hex methods are used for coercion.
-  Floats have these methods defined and floats should not be used in
-  slice notation.
+    The nb_int method is used for coercion and so means something
+    fundamentally different than what is requested here.  This PEP
+    proposes a method for something that *can* already be thought of as
+    an integer communicate that information to Python when it needs an
+    integer.  The biggest example of why using nb_int would be a bad
+    thing is that float objects already define the nb_int method, but
+    float objects *should not* be used as indexes in a sequence.
 
 Reference Implementation
-
-  Available on PEP acceptance.
+ 
+    Submitted as a patch to SourceForge.
 
 Copyright
 
-  This document is placed in the public domain
+    This document is placed in the public domain