Lib/numbers.py

   1 # Copyright 2007 Google, Inc. All Rights Reserved.
   2 # Licensed to PSF under a Contributor Agreement.
   3
   4 """Abstract Base Classes (ABCs) for numbers, according to PEP 3141.
   5
   6 TODO: Fill out more detailed documentation on the operators."""
   7
   8 from abc import ABCMeta, abstractmethod, abstractproperty
   9
  10 __all__ = ["Number", "Complex", "Real", "Rational", "Integral"]
  11
  12 class Number(metaclass=ABCMeta):
  13     """All numbers inherit from this class.
  14
  15     If you just want to check if an argument x is a number, without
  16     caring what kind, use isinstance(x, Number).
  17     """
  18
  19
  20 ## Notes on Decimal
  21 ## ----------------
  22 ## Decimal has all of the methods specified by the Real abc, but it should
  23 ## not be registered as a Real because decimals do not interoperate with
  24 ## binary floats (i.e.  Decimal('3.14') + 2.71828 is undefined).  But,
  25 ## abstract reals are expected to interoperate (i.e. R1 + R2 should be
  26 ## expected to work if R1 and R2 are both Reals).
  27
  28 class Complex(Number):
  29     """Complex defines the operations that work on the builtin complex type.
  30
  31     In short, those are: a conversion to complex, .real, .imag, +, -,
  32     *, /, abs(), .conjugate, ==, and !=.
  33
  34     If it is given heterogenous arguments, and doesn't have special
  35     knowledge about them, it should fall back to the builtin complex
  36     type as described below.
  37     """
  38
  39     @abstractmethod
  40     def __complex__(self):
  41         """Return a builtin complex instance. Called for complex(self)."""
  42
  43     def __bool__(self):
  44         """True if self != 0. Called for bool(self)."""
  45         return self != 0
  46
  47     @abstractproperty
  48     def real(self):
  49         """Retrieve the real component of this number.
  50
  51         This should subclass Real.
  52         """
  53         raise NotImplementedError
  54
  55     @abstractproperty
  56     def imag(self):
  57         """Retrieve the real component of this number.
  58
  59         This should subclass Real.
  60         """
  61         raise NotImplementedError
  62
  63     @abstractmethod
  64     def __add__(self, other):
  65         """self + other"""
  66         raise NotImplementedError
  67
  68     @abstractmethod
  69     def __radd__(self, other):
  70         """other + self"""
  71         raise NotImplementedError
  72
  73     @abstractmethod
  74     def __neg__(self):
  75         """-self"""
  76         raise NotImplementedError
  77
  78     @abstractmethod
  79     def __pos__(self):
  80         """+self"""
  81         raise NotImplementedError
  82
  83     def __sub__(self, other):
  84         """self - other"""
  85         return self + -other
  86
  87     def __rsub__(self, other):
  88         """other - self"""
  89         return -self + other
  90
  91     @abstractmethod
  92     def __mul__(self, other):
  93         """self * other"""
  94         raise NotImplementedError
  95
  96     @abstractmethod
  97     def __rmul__(self, other):
  98         """other * self"""
  99         raise NotImplementedError
 100
 101     @abstractmethod
 102     def __truediv__(self, other):
 103         """self / other: Should promote to float when necessary."""
 104         raise NotImplementedError
 105
 106     @abstractmethod
 107     def __rtruediv__(self, other):
 108         """other / self"""
 109         raise NotImplementedError
 110
 111     @abstractmethod
 112     def __pow__(self, exponent):
 113         """self**exponent; should promote to float or complex when necessary."""
 114         raise NotImplementedError
 115
 116     @abstractmethod
 117     def __rpow__(self, base):
 118         """base ** self"""
 119         raise NotImplementedError
 120
 121     @abstractmethod
 122     def __abs__(self):
 123         """Returns the Real distance from 0. Called for abs(self)."""
 124         raise NotImplementedError
 125
 126     @abstractmethod
 127     def conjugate(self):
 128         """(x+y*i).conjugate() returns (x-y*i)."""
 129         raise NotImplementedError
 130
 131     @abstractmethod
 132     def __eq__(self, other):
 133         """self == other"""
 134         raise NotImplementedError
 135
 136     def __ne__(self, other):
 137         """self != other"""
 138         # The default __ne__ doesn't negate __eq__ until 3.0.
 139         return not (self == other)
 140
 141 Complex.register(complex)
 142
 143
 144 class Real(Complex):
 145     """To Complex, Real adds the operations that work on real numbers.
 146
 147     In short, those are: a conversion to float, trunc(), divmod,
 148     %, <, <=, >, and >=.
 149
 150     Real also provides defaults for the derived operations.
 151     """
 152
 153     @abstractmethod
 154     def __float__(self):
 155         """Any Real can be converted to a native float object.
 156
 157         Called for float(self)."""
 158         raise NotImplementedError
 159
 160     @abstractmethod
 161     def __trunc__(self):
 162         """trunc(self): Truncates self to an Integral.
 163
 164         Returns an Integral i such that:
 165           * i>0 iff self>0;
 166           * abs(i) <= abs(self);
 167           * for any Integral j satisfying the first two conditions,
 168             abs(i) >= abs(j) [i.e. i has "maximal" abs among those].
 169         i.e. "truncate towards 0".
 170         """
 171         raise NotImplementedError
 172
 173     @abstractmethod
 174     def __floor__(self):
 175         """Finds the greatest Integral <= self."""
 176         raise NotImplementedError
 177
 178     @abstractmethod
 179     def __ceil__(self):
 180         """Finds the least Integral >= self."""
 181         raise NotImplementedError
 182
 183     @abstractmethod
 184     def __round__(self, ndigits:"Integral"=None):
 185         """Rounds self to ndigits decimal places, defaulting to 0.
 186
 187         If ndigits is omitted or None, returns an Integral, otherwise
 188         returns a Real. Rounds half toward even.
 189         """
 190         raise NotImplementedError
 191
 192     def __divmod__(self, other):
 193         """divmod(self, other): The pair (self // other, self % other).
 194
 195         Sometimes this can be computed faster than the pair of
 196         operations.
 197         """
 198         return (self // other, self % other)
 199
 200     def __rdivmod__(self, other):
 201         """divmod(other, self): The pair (self // other, self % other).
 202
 203         Sometimes this can be computed faster than the pair of
 204         operations.
 205         """
 206         return (other // self, other % self)
 207
 208     @abstractmethod
 209     def __floordiv__(self, other):
 210         """self // other: The floor() of self/other."""
 211         raise NotImplementedError
 212
 213     @abstractmethod
 214     def __rfloordiv__(self, other):
 215         """other // self: The floor() of other/self."""
 216         raise NotImplementedError
 217
 218     @abstractmethod
 219     def __mod__(self, other):
 220         """self % other"""
 221         raise NotImplementedError
 222
 223     @abstractmethod
 224     def __rmod__(self, other):
 225         """other % self"""
 226         raise NotImplementedError
 227
 228     @abstractmethod
 229     def __lt__(self, other):
 230         """self < other
 231
 232         < on Reals defines a total ordering, except perhaps for NaN."""
 233         raise NotImplementedError
 234
 235     @abstractmethod
 236     def __le__(self, other):
 237         """self <= other"""
 238         raise NotImplementedError
 239
 240     # Concrete implementations of Complex abstract methods.
 241     def __complex__(self):
 242         """complex(self) == complex(float(self), 0)"""
 243         return complex(float(self))
 244
 245     @property
 246     def real(self):
 247         """Real numbers are their real component."""
 248         return +self
 249
 250     @property
 251     def imag(self):
 252         """Real numbers have no imaginary component."""
 253         return 0
 254
 255     def conjugate(self):
 256         """Conjugate is a no-op for Reals."""
 257         return +self
 258
 259 Real.register(float)
 260
 261
 262 class Rational(Real):
 263     """.numerator and .denominator should be in lowest terms."""
 264
 265     @abstractproperty
 266     def numerator(self):
 267         raise NotImplementedError
 268
 269     @abstractproperty
 270     def denominator(self):
 271         raise NotImplementedError
 272
 273     # Concrete implementation of Real's conversion to float.
 274     def __float__(self):
 275         """float(self) = self.numerator / self.denominator
 276
 277         It's important that this conversion use the integer's "true"
 278         division rather than casting one side to float before dividing
 279         so that ratios of huge integers convert without overflowing.
 280
 281         """
 282         return self.numerator / self.denominator
 283
 284
 285 class Integral(Rational):
 286     """Integral adds a conversion to int and the bit-string operations."""
 287
 288     @abstractmethod
 289     def __int__(self):
 290         """int(self)"""
 291         raise NotImplementedError
 292
 293     def __index__(self):
 294         """index(self)"""
 295         return int(self)
 296
 297     @abstractmethod
 298     def __pow__(self, exponent, modulus=None):
 299         """self ** exponent % modulus, but maybe faster.
 300
 301         Accept the modulus argument if you want to support the
 302         3-argument version of pow(). Raise a TypeError if exponent < 0
 303         or any argument isn't Integral. Otherwise, just implement the
 304         2-argument version described in Complex.
 305         """
 306         raise NotImplementedError
 307
 308     @abstractmethod
 309     def __lshift__(self, other):
 310         """self << other"""
 311         raise NotImplementedError
 312
 313     @abstractmethod
 314     def __rlshift__(self, other):
 315         """other << self"""
 316         raise NotImplementedError
 317
 318     @abstractmethod
 319     def __rshift__(self, other):
 320         """self >> other"""
 321         raise NotImplementedError
 322
 323     @abstractmethod
 324     def __rrshift__(self, other):
 325         """other >> self"""
 326         raise NotImplementedError
 327
 328     @abstractmethod
 329     def __and__(self, other):
 330         """self & other"""
 331         raise NotImplementedError
 332
 333     @abstractmethod
 334     def __rand__(self, other):
 335         """other & self"""
 336         raise NotImplementedError
 337
 338     @abstractmethod
 339     def __xor__(self, other):
 340         """self ^ other"""
 341         raise NotImplementedError
 342
 343     @abstractmethod
 344     def __rxor__(self, other):
 345         """other ^ self"""
 346         raise NotImplementedError
 347
 348     @abstractmethod
 349     def __or__(self, other):
 350         """self | other"""
 351         raise NotImplementedError
 352
 353     @abstractmethod
 354     def __ror__(self, other):
 355         """other | self"""
 356         raise NotImplementedError
 357
 358     @abstractmethod
 359     def __invert__(self):
 360         """~self"""
 361         raise NotImplementedError
 362
 363     # Concrete implementations of Rational and Real abstract methods.
 364     def __float__(self):
 365         """float(self) == float(int(self))"""
 366         return float(int(self))
 367
 368     @property
 369     def numerator(self):
 370         """Integers are their own numerators."""
 371         return +self
 372
 373     @property
 374     def denominator(self):
 375         """Integers have a denominator of 1."""
 376         return 1
 377
 378 Integral.register(int)