[Python-Dev] Mini-Pep: Simplifying the Integral ABC

[Raymond Hettinger]

Target:  Py2.6 and Py3.0
Author: Raymond Hettinger
Date: May 31, 2008

Motivation
----------
The principal purpose of an abstract base class is to support multiple
implementations of an API; thereby allowing one concrete class to be
substitutable for another. This purpose is defeated when useful substitutions
are precluded because the ABC is too aggressive in its behavioral requirements
-- mandating too many methods, mandating methods that are difficult to
implement, or too closely following the full API of a single concrete type.

The Integral ABC is somewhat extensive and requires essentially every behavior
exhibited by the int concrete class.  Usefully, it provides for basic integer
behaviors like simple arithmetic and ordering relations.  However, the current
ABC goes beyond that and requires bit-flipping and other operations that are
not fundamental to the notion of being an integer.  That makes it challenging
to define a new Integral class that isn't already an int.

Proposal
--------
Remove non-essential abstract methods like __index__, three argument __pow__,
__lshift__, __rlshift__, __rshift__, __rrshift__, __and__, __rand__, __xor__,
__rxor__, __or__, __ror__, and __invert__, numerator, and denominator.

Discussion
----------
The only known use cases for variants of int are types that limit the range of
values to those that fit in a fixed storage width.

One existing implementation is in numpy which has types like int0, int8,
int16, int32, and int16.  The numpy integral types implement all the methods
present in Integral except for the new methods like __trunc__, __index__,
real, imag, conjugate, numerator, and denominator.  For the most part, they
are fully substitutable into code that expects regular ints; however, they do
have wrap-around behaviors such as int8(200)+int8(100) --> int8(44). The
wrap-around behaviors make the numpy types totally unsuitable for some
applications of Integral such as the fractions module which accepts any
integral numerator and denominator.