python-peps/pep-0357.txt

PEP: 357
Title: Allowing Any Object to be Used for Slicing
Version: $Revision$
Last Modified: $Date$
Author: Travis Oliphant <oliphant@ee.byu.edu>
Status: Draft
Type: Standards Track
Created: 09-Feb-2006
Python-Version: 2.5

Abstract

    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.

    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 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 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.

    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: 

    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?:

    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
 
    Submitted as a patch to SourceForge.

Copyright

    This document is placed in the public domain