| Jeffrey Yasskin | 2f3c16b | 2008-01-03 02:21:52 +0000 | [diff] [blame] | 1 | |
| 2 | :mod:`numbers` --- Numeric abstract base classes |
| 3 | ================================================ |
| 4 | |
| 5 | .. module:: numbers |
| 6 | :synopsis: Numeric abstract base classes (Complex, Real, Integral, etc.). |
| 7 | |
| 8 | The :mod:`numbers` module (:pep:`3141`) defines a hierarchy of numeric abstract |
| 9 | base classes which progressively define more operations. These concepts also |
| 10 | provide a way to distinguish exact from inexact types. None of the types defined |
| 11 | in this module can be instantiated. |
| 12 | |
| 13 | |
| 14 | .. class:: Number |
| 15 | |
| 16 | The root of the numeric hierarchy. If you just want to check if an argument |
| 17 | *x* is a number, without caring what kind, use ``isinstance(x, Number)``. |
| 18 | |
| 19 | |
| 20 | Exact and inexact operations |
| 21 | ---------------------------- |
| 22 | |
| 23 | .. class:: Exact |
| 24 | |
| 25 | Subclasses of this type have exact operations. |
| 26 | |
| 27 | As long as the result of a homogenous operation is of the same type, you can |
| 28 | assume that it was computed exactly, and there are no round-off errors. Laws |
| 29 | like commutativity and associativity hold. |
| 30 | |
| 31 | |
| 32 | .. class:: Inexact |
| 33 | |
| 34 | Subclasses of this type have inexact operations. |
| 35 | |
| 36 | Given X, an instance of :class:`Inexact`, it is possible that ``(X + -X) + 3 |
| 37 | == 3``, but ``X + (-X + 3) == 0``. The exact form this error takes will vary |
| 38 | by type, but it's generally unsafe to compare this type for equality. |
| 39 | |
| 40 | |
| 41 | The numeric tower |
| 42 | ----------------- |
| 43 | |
| 44 | .. class:: Complex |
| 45 | |
| 46 | Subclasses of this type describe complex numbers and include the operations |
| 47 | that work on the builtin :class:`complex` type. These are: conversions to |
| 48 | :class:`complex` and :class:`bool`, :attr:`.real`, :attr:`.imag`, ``+``, |
| 49 | ``-``, ``*``, ``/``, :func:`abs`, :meth:`conjugate`, ``==``, and ``!=``. All |
| 50 | except ``-`` and ``!=`` are abstract. |
| 51 | |
| 52 | .. attribute:: Complex.real |
| 53 | |
| 54 | Abstract. Retrieves the :class:`Real` component of this number. |
| 55 | |
| 56 | .. attribute:: Complex.imag |
| 57 | |
| 58 | Abstract. Retrieves the :class:`Real` component of this number. |
| 59 | |
| 60 | .. method:: Complex.conjugate() |
| 61 | |
| 62 | Abstract. Returns the complex conjugate. For example, ``(1+3j).conjugate() == |
| 63 | (1-3j)``. |
| 64 | |
| 65 | .. class:: Real |
| 66 | |
| 67 | To :class:`Complex`, :class:`Real` adds the operations that work on real |
| 68 | numbers. |
| 69 | |
| 70 | In short, those are: a conversion to :class:`float`, :func:`trunc`, |
| 71 | :func:`round`, :func:`math.floor`, :func:`math.ceil`, :func:`divmod`, ``//``, |
| 72 | ``%``, ``<``, ``<=``, ``>``, and ``>=``. |
| 73 | |
| 74 | Real also provides defaults for :func:`complex`, :attr:`Complex.real`, |
| 75 | :attr:`Complex.imag`, and :meth:`Complex.conjugate`. |
| 76 | |
| 77 | |
| 78 | .. class:: Rational |
| 79 | |
| 80 | Subtypes both :class:`Real` and :class:`Exact`, and adds |
| 81 | :attr:`Rational.numerator` and :attr:`Rational.denominator` properties, which |
| 82 | should be in lowest terms. With these, it provides a default for |
| 83 | :func:`float`. |
| 84 | |
| 85 | .. attribute:: Rational.numerator |
| 86 | |
| 87 | Abstract. |
| 88 | |
| 89 | .. attribute:: Rational.denominator |
| 90 | |
| 91 | Abstract. |
| 92 | |
| 93 | |
| 94 | .. class:: Integral |
| 95 | |
| 96 | Subtypes :class:`Rational` and adds a conversion to :class:`long`, the |
| 97 | 3-argument form of :func:`pow`, and the bit-string operations: ``<<``, |
| 98 | ``>>``, ``&``, ``^``, ``|``, ``~``. Provides defaults for :func:`float`, |
| 99 | :attr:`Rational.numerator`, and :attr:`Rational.denominator`. |