Backport PEP 3141 from the py3k branch to the trunk. This includes r50877 (just

the complex_pow part), r56649, r56652, r56715, r57296, r57302, r57359, r57361,
r57372, r57738, r57739, r58017, r58039, r58040, and r59390, and new
documentation. The only significant difference is that round(x) returns a float
to preserve backward-compatibility. See http://bugs.python.org/issue1689.

7 files changed, 160 insertions, 27 deletions

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 9c11b6d..3236ccd 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -986,10 +986,13 @@ available.  They are listed here in alphabetical order.
 .. function:: round(x[, n])
 
    Return the floating point value *x* rounded to *n* digits after the decimal
-   point.  If *n* is omitted, it defaults to zero. The result is a floating point
-   number.  Values are rounded to the closest multiple of 10 to the power minus
-   *n*; if two multiples are equally close, rounding is done away from 0 (so. for
-   example, ``round(0.5)`` is ``1.0`` and ``round(-0.5)`` is ``-1.0``).
+   point.  If *n* is omitted, it defaults to zero.  Values are rounded to the
+   closest multiple of 10 to the power minus *n*; if two multiples are equally
+   close, rounding is done toward the even choice (so, for example, both
+   ``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is
+   ``2``). Delegates to ``x.__round__(n)``.
+
+   .. versionchanged:: 2.6
 
 
 .. function:: set([iterable])
@@ -1132,6 +1135,14 @@ available.  They are listed here in alphabetical order.
    .. versionadded:: 2.2
 
 
+.. function:: trunc(x)
+
+   Return the :class:`Real` value *x* truncated to an :class:`Integral` (usually
+   a long integer). Delegates to ``x.__trunc__()``.
+
+   .. versionadded:: 2.6
+
+
 .. function:: tuple([iterable])
 
    Return a tuple whose items are the same and in the same order as *iterable*'s
diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index 17c75d3..f92610f 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -26,8 +26,9 @@ Number-theoretic and representation functions:
 
 .. function:: ceil(x)
 
-   Return the ceiling of *x* as a float, the smallest integer value greater than or
-   equal to *x*.
+   Return the ceiling of *x* as a float, the smallest integer value greater than
+   or equal to *x*. If *x* is not a float, delegates to ``x.__ceil__()``, which
+   should return an :class:`Integral` value.
 
 
 .. function:: fabs(x)
@@ -37,8 +38,9 @@ Number-theoretic and representation functions:
 
 .. function:: floor(x)
 
-   Return the floor of *x* as a float, the largest integer value less than or equal
-   to *x*.
+   Return the floor of *x* as a float, the largest integer value less than or
+   equal to *x*. If *x* is not a float, delegates to ``x.__floor__()``, which
+   should return an :class:`Integral` value.
 
 
 .. function:: fmod(x, y)
diff --git a/Doc/library/numbers.rst b/Doc/library/numbers.rst
new file mode 100644
index 0000000..d0f9c3b
--- /dev/null
+++ b/Doc/library/numbers.rst
@@ -0,0 +1,99 @@
+
+:mod:`numbers` --- Numeric abstract base classes
+================================================
+
+.. module:: numbers
+   :synopsis: Numeric abstract base classes (Complex, Real, Integral, etc.).
+
+The :mod:`numbers` module (:pep:`3141`) defines a hierarchy of numeric abstract
+base classes which progressively define more operations. These concepts also
+provide a way to distinguish exact from inexact types. None of the types defined
+in this module can be instantiated.
+
+
+.. class:: Number
+
+   The root of the numeric hierarchy. If you just want to check if an argument
+   *x* is a number, without caring what kind, use ``isinstance(x, Number)``.
+
+
+Exact and inexact operations
+----------------------------
+
+.. class:: Exact
+
+   Subclasses of this type have exact operations.
+
+   As long as the result of a homogenous operation is of the same type, you can
+   assume that it was computed exactly, and there are no round-off errors. Laws
+   like commutativity and associativity hold.
+
+
+.. class:: Inexact
+
+   Subclasses of this type have inexact operations.
+
+   Given X, an instance of :class:`Inexact`, it is possible that ``(X + -X) + 3
+   == 3``, but ``X + (-X + 3) == 0``. The exact form this error takes will vary
+   by type, but it's generally unsafe to compare this type for equality.
+
+
+The numeric tower
+-----------------
+
+.. class:: Complex
+
+   Subclasses of this type describe complex numbers and include the operations
+   that work on the builtin :class:`complex` type. These are: conversions to
+   :class:`complex` and :class:`bool`, :attr:`.real`, :attr:`.imag`, ``+``,
+   ``-``, ``*``, ``/``, :func:`abs`, :meth:`conjugate`, ``==``, and ``!=``. All
+   except ``-`` and ``!=`` are abstract.
+
+.. attribute:: Complex.real
+
+   Abstract. Retrieves the :class:`Real` component of this number.
+
+.. attribute:: Complex.imag
+
+   Abstract. Retrieves the :class:`Real` component of this number.
+
+.. method:: Complex.conjugate()
+
+   Abstract. Returns the complex conjugate. For example, ``(1+3j).conjugate() ==
+   (1-3j)``.
+
+.. class:: Real
+
+   To :class:`Complex`, :class:`Real` adds the operations that work on real
+   numbers.
+
+   In short, those are: a conversion to :class:`float`, :func:`trunc`,
+   :func:`round`, :func:`math.floor`, :func:`math.ceil`, :func:`divmod`, ``//``,
+   ``%``, ``<``, ``<=``, ``>``, and ``>=``.
+
+   Real also provides defaults for :func:`complex`, :attr:`Complex.real`,
+   :attr:`Complex.imag`, and :meth:`Complex.conjugate`.
+
+
+.. class:: Rational
+
+   Subtypes both :class:`Real` and :class:`Exact`, and adds
+   :attr:`Rational.numerator` and :attr:`Rational.denominator` properties, which
+   should be in lowest terms. With these, it provides a default for
+   :func:`float`.
+
+.. attribute:: Rational.numerator
+
+   Abstract.
+
+.. attribute:: Rational.denominator
+
+   Abstract.
+
+
+.. class:: Integral
+
+   Subtypes :class:`Rational` and adds a conversion to :class:`long`, the
+   3-argument form of :func:`pow`, and the bit-string operations: ``<<``,
+   ``>>``, ``&``, ``^``, ``|``, ``~``. Provides defaults for :func:`float`,
+   :attr:`Rational.numerator`, and :attr:`Rational.denominator`.
diff --git a/Doc/library/numeric.rst b/Doc/library/numeric.rst
index 0d9d59f..d2b4d8b 100644
--- a/Doc/library/numeric.rst
+++ b/Doc/library/numeric.rst
@@ -6,16 +6,18 @@ Numeric and Mathematical Modules
 ********************************
 
 The modules described in this chapter provide numeric and math-related functions
-and data types. The :mod:`math` and :mod:`cmath` contain  various mathematical
-functions for floating-point and complex numbers. For users more interested in
-decimal accuracy than in speed, the  :mod:`decimal` module supports exact
-representations of  decimal numbers.
+and data types. The :mod:`numbers` module defines an abstract hierarchy of
+numeric types. The :mod:`math` and :mod:`cmath` modules contain various
+mathematical functions for floating-point and complex numbers. For users more
+interested in decimal accuracy than in speed, the :mod:`decimal` module supports
+exact representations of decimal numbers.
 
 The following modules are documented in this chapter:
 
 
 .. toctree::
 
+   numbers.rst
    math.rst
    cmath.rst
    decimal.rst
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 99c1923..7352a1d 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -270,9 +270,8 @@ numbers of mixed type use the same rule. [#]_ The constructors :func:`int`,
 :func:`long`, :func:`float`, and :func:`complex` can be used to produce numbers
 of a specific type.
 
-All numeric types (except complex) support the following operations, sorted by
-ascending priority (operations in the same box have the same priority; all
-numeric operations have a higher priority than comparison operations):
+All builtin numeric types support the following operations. See
+:ref:`power` and later sections for the operators' priorities.
 
 +--------------------+---------------------------------+--------+
 | Operation          | Result                          | Notes  |
@@ -285,7 +284,7 @@ numeric operations have a higher priority than comparison operations):
 +--------------------+---------------------------------+--------+
 | ``x / y``          | quotient of *x* and *y*         | \(1)   |
 +--------------------+---------------------------------+--------+
-| ``x // y``         | (floored) quotient of *x* and   | \(5)   |
+| ``x // y``         | (floored) quotient of *x* and   | (4)(5) |
 |                    | *y*                             |        |
 +--------------------+---------------------------------+--------+
 | ``x % y``          | remainder of ``x / y``          | \(4)   |
@@ -294,7 +293,7 @@ numeric operations have a higher priority than comparison operations):
 +--------------------+---------------------------------+--------+
 | ``+x``             | *x* unchanged                   |        |
 +--------------------+---------------------------------+--------+
-| ``abs(x)``         | absolute value or magnitude of  |        |
+| ``abs(x)``         | absolute value or magnitude of  | \(3)   |
 |                    | *x*                             |        |
 +--------------------+---------------------------------+--------+
 | ``int(x)``         | *x* converted to integer        | \(2)   |
@@ -308,11 +307,11 @@ numeric operations have a higher priority than comparison operations):
 |                    | *im* defaults to zero.          |        |
 +--------------------+---------------------------------+--------+
 | ``c.conjugate()``  | conjugate of the complex number |        |
-|                    | *c*                             |        |
+|                    | *c*. (Identity on real numbers) |        |
 +--------------------+---------------------------------+--------+
 | ``divmod(x, y)``   | the pair ``(x // y, x % y)``    | (3)(4) |
 +--------------------+---------------------------------+--------+
-| ``pow(x, y)``      | *x* to the power *y*            |        |
+| ``pow(x, y)``      | *x* to the power *y*            | \(3)   |
 +--------------------+---------------------------------+--------+
 | ``x ** y``         | *x* to the power *y*            |        |
 +--------------------+---------------------------------+--------+
@@ -341,9 +340,12 @@ Notes:
       pair: numeric; conversions
       pair: C; language
 
-   Conversion from floating point to (long or plain) integer may round or truncate
-   as in C; see functions :func:`floor` and :func:`ceil` in the :mod:`math` module
-   for well-defined conversions.
+   Conversion from floating point to (long or plain) integer may round or
+   truncate as in C.
+
+   .. deprecated:: 2.6
+      Instead, convert floats to long explicitly with :func:`trunc`,
+      :func:`math.floor`, or :func:`math.ceil`.
 
 (3)
    See :ref:`built-in-funcs` for a full description.
@@ -364,6 +366,22 @@ Notes:
    
    .. versionadded:: 2.6
 
+All :class:`numbers.Real` types (:class:`int`, :class:`long`, and
+:class:`float`) also include the following operations:
+
++--------------------+--------------------------------+--------+
+| Operation          | Result                         | Notes  |
++====================+================================+========+
+| ``trunc(x)``       | *x* truncated to Integral      |        |
++--------------------+--------------------------------+--------+
+| ``round(x[, n])``  | *x* rounded to n digits,       |        |
+|                    | rounding half to even. If n is |        |
+|                    | omitted, it defaults to 0.     |        |
++--------------------+--------------------------------+--------+
+| ``math.floor(x)``  | the greatest Integral <= *x*   |        |
++--------------------+--------------------------------+--------+
+| ``math.ceil(x)``   | the least Integral >= *x*      |        |
++--------------------+--------------------------------+--------+
 
 .. XXXJH exceptions: overflow (when? what operations?) zerodivision
 
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index b45044d..6fc1f8e 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -150,7 +150,7 @@ Ellipsis
    indicate the presence of the ``...`` syntax in a slice.  Its truth value is
    true.
 
-Numbers
+:class:`numbers.Number`
    .. index:: object: numeric
 
    These are created by numeric literals and returned as results by arithmetic
@@ -162,7 +162,7 @@ Numbers
    Python distinguishes between integers, floating point numbers, and complex
    numbers:
 
-   Integers
+   :class:`numbers.Integral`
       .. index:: object: integer
 
       These represent elements from the mathematical set of integers (positive and
@@ -214,7 +214,7 @@ Numbers
       without causing overflow, will yield the same result in the long integer domain
       or when using mixed operands.
 
-   Floating point numbers
+   :class:`numbers.Real` (:class:`float`)
       .. index::
          object: floating point
          pair: floating point; number
@@ -229,7 +229,7 @@ Numbers
       overhead of using objects in Python, so there is no reason to complicate the
       language with two kinds of floating point numbers.
 
-   Complex numbers
+   :class:`numbers.Complex`
       .. index::
          object: complex
          pair: complex; number
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index ea2bb1a..9c416f8 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -801,7 +801,8 @@ were of integer types and the second argument was negative, an exception was
 raised).
 
 Raising ``0.0`` to a negative power results in a :exc:`ZeroDivisionError`.
-Raising a negative number to a fractional power results in a :exc:`ValueError`.
+Raising a negative number to a fractional power results in a :class:`complex`
+number. (Since Python 2.6. In earlier versions it raised a :exc:`ValueError`.)
 
 
 .. _unary: