Check in some documentation tweaks for PEP 3141, add some tests, and implement

the promotion to complex on pow(negative, fraction).

Lib/numbers.py

@@ -1,7 +1,9 @@
 # Copyright 2007 Google, Inc. All Rights Reserved.
 # Licensed to PSF under a Contributor Agreement.
 
-"""Abstract Base Classes (ABCs) for numbers, according to PEP 3141."""
+"""Abstract Base Classes (ABCs) for numbers, according to PEP 3141.
+
+TODO: Fill out more detailed documentation on the operators."""
 
 from abc import ABCMeta, abstractmethod, abstractproperty
 
@@ -56,10 +58,10 @@ class Complex(Number):
 
     @abstractmethod
     def __complex__(self):
-        """Return a builtin complex instance."""
+        """Return a builtin complex instance. Called for complex(self)."""
 
     def __bool__(self):
-        """True if self != 0."""
+        """True if self != 0. Called for bool(self)."""
         return self != 0
 
     @abstractproperty
@@ -80,53 +82,64 @@ class Complex(Number):
 
     @abstractmethod
     def __add__(self, other):
+        """self + other"""
         raise NotImplementedError
 
     @abstractmethod
     def __radd__(self, other):
+        """other + self"""
         raise NotImplementedError
 
     @abstractmethod
     def __neg__(self):
+        """-self"""
         raise NotImplementedError
 
     def __pos__(self):
+        """+self"""
         return self
 
     def __sub__(self, other):
+        """self - other"""
         return self + -other
 
     def __rsub__(self, other):
+        """other - self"""
         return -self + other
 
     @abstractmethod
     def __mul__(self, other):
+        """self * other"""
         raise NotImplementedError
 
     @abstractmethod
     def __rmul__(self, other):
+        """other * self"""
         raise NotImplementedError
 
     @abstractmethod
     def __div__(self, other):
+        """self / other"""
         raise NotImplementedError
 
     @abstractmethod
     def __rdiv__(self, other):
+        """other / self"""
         raise NotImplementedError
 
     @abstractmethod
     def __pow__(self, exponent):
-        """Like division, a**b should promote to complex when necessary."""
+        """Like division, self**exponent should promote to complex when necessary."""
         raise NotImplementedError
 
     @abstractmethod
     def __rpow__(self, base):
+        """base ** self"""
         raise NotImplementedError
 
     @abstractmethod
     def __abs__(self):
-        """Returns the Real distance from 0."""
+        """Returns the Real distance from 0. Called for abs(self)."""
         raise NotImplementedError
 
     @abstractmethod
@@ -136,9 +149,11 @@ class Complex(Number):
 
     @abstractmethod
     def __eq__(self, other):
+        """self == other"""
         raise NotImplementedError
 
     def __ne__(self, other):
+        """self != other"""
         return not (self == other)
 
 Complex.register(complex)
@@ -155,12 +170,14 @@ class Real(Complex):
 
     @abstractmethod
     def __float__(self):
-        """Any Real can be converted to a native float object."""
+        """Any Real can be converted to a native float object.
+
+        Called for float(self)."""
         raise NotImplementedError
 
     @abstractmethod
     def __trunc__(self):
-        """Truncates self to an Integral.
+        """trunc(self): Truncates self to an Integral.
 
         Returns an Integral i such that:
           * i>0 iff self>0
@@ -169,7 +186,7 @@ class Real(Complex):
         raise NotImplementedError
 
     def __divmod__(self, other):
-        """The pair (self // other, self % other).
+        """divmod(self, other): The pair (self // other, self % other).
 
         Sometimes this can be computed faster than the pair of
         operations.
@@ -177,7 +194,7 @@ class Real(Complex):
         return (self // other, self % other)
 
     def __rdivmod__(self, other):
-        """The pair (self // other, self % other).
+        """divmod(other, self): The pair (self // other, self % other).
 
         Sometimes this can be computed faster than the pair of
         operations.
@@ -186,40 +203,49 @@ class Real(Complex):
 
     @abstractmethod
     def __floordiv__(self, other):
-        """The floor() of self/other."""
+        """self // other: The floor() of self/other."""
         raise NotImplementedError
 
     @abstractmethod
     def __rfloordiv__(self, other):
-        """The floor() of other/self."""
+        """other // self: The floor() of other/self."""
         raise NotImplementedError
 
     @abstractmethod
     def __mod__(self, other):
+        """self % other"""
         raise NotImplementedError
 
     @abstractmethod
     def __rmod__(self, other):
+        """other % self"""
         raise NotImplementedError
 
     @abstractmethod
     def __lt__(self, other):
-        """< on Reals defines a total ordering, except perhaps for NaN."""
+        """self < other
+
+        < on Reals defines a total ordering, except perhaps for NaN."""
         raise NotImplementedError
 
+    @abstractmethod
     def __le__(self, other):
+        """self <= other"""
         raise NotImplementedError
 
     # Concrete implementations of Complex abstract methods.
     def __complex__(self):
+        """complex(self) == complex(float(self), 0)"""
         return complex(float(self))
 
     @property
     def real(self):
+        """Real numbers are their real component."""
         return self
 
     @property
     def imag(self):
+        """Real numbers have no imaginary component."""
         return 0
 
     def conjugate(self):
@@ -242,6 +268,7 @@ class Rational(Real, Exact):
 
     # Concrete implementation of Real's conversion to float.
     def __float__(self):
+        """float(self) = self.numerator / self.denominator"""
         return self.numerator / self.denominator
 
 
@@ -250,76 +277,92 @@ class Integral(Rational):
 
     @abstractmethod
     def __int__(self):
+        """int(self)"""
         raise NotImplementedError
 
     def __index__(self):
+        """index(self)"""
         return int(self)
 
     @abstractmethod
-    def __pow__(self, exponent, modulus):
+    def __pow__(self, exponent, modulus=None):
         """self ** exponent % modulus, but maybe faster.
 
-        Implement this if you want to support the 3-argument version
-        of pow(). Otherwise, just implement the 2-argument version
-        described in Complex. Raise a TypeError if exponent < 0 or any
-        argument isn't Integral.
+        Accept the modulus argument if you want to support the
+        3-argument version of pow(). Raise a TypeError if exponent < 0
+        or any argument isn't Integral. Otherwise, just implement the
+        2-argument version described in Complex.
         """
         raise NotImplementedError
 
     @abstractmethod
     def __lshift__(self, other):
+        """self << other"""
         raise NotImplementedError
 
     @abstractmethod
     def __rlshift__(self, other):
+        """other << self"""
         raise NotImplementedError
 
     @abstractmethod
     def __rshift__(self, other):
+        """self >> other"""
         raise NotImplementedError
 
     @abstractmethod
     def __rrshift__(self, other):
+        """other >> self"""
         raise NotImplementedError
 
     @abstractmethod
     def __and__(self, other):
+        """self & other"""
         raise NotImplementedError
 
     @abstractmethod
     def __rand__(self, other):
+        """other & self"""
         raise NotImplementedError
 
     @abstractmethod
     def __xor__(self, other):
+        """self ^ other"""
         raise NotImplementedError
 
     @abstractmethod
     def __rxor__(self, other):
+        """other ^ self"""
         raise NotImplementedError
 
     @abstractmethod
     def __or__(self, other):
+        """self | other"""
         raise NotImplementedError
 
     @abstractmethod
     def __ror__(self, other):
+        """other | self"""
         raise NotImplementedError
 
     @abstractmethod
     def __invert__(self):
+        """~self"""
         raise NotImplementedError
 
     # Concrete implementations of Rational and Real abstract methods.
     def __float__(self):
+        """float(self) == float(int(self))"""
         return float(int(self))
 
     @property
     def numerator(self):
+        """Integers are their own numerators."""
         return self
 
     @property
     def denominator(self):
+        """Integers have a denominator of 1."""
         return 1
 
 Integral.register(int)