Check in some documentation tweaks for PEP 3141, add some tests, and implement
the promotion to complex on pow(negative, fraction).
diff --git a/Lib/numbers.py b/Lib/numbers.py
index 8678a3a..34cc803 100644
--- a/Lib/numbers.py
+++ b/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 @@
@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 @@
@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 @@
@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 @@
@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 @@
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 @@
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 @@
@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 @@
# 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 @@
@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)