Doc/library/numbers.rst

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