Skip to content

Commit cd607cc

Browse files
author
jeffrey.yasskin
committed
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. git-svn-id: http://svn.python.org/projects/python/trunk@59671 6015fed2-1504-0410-9fe1-9d1591cc4771
1 parent ff9bf27 commit cd607cc

21 files changed

+1089
-124
lines changed

‎Doc/library/functions.rst‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -986,10 +986,13 @@ available. They are listed here in alphabetical order.
986986
.. function:: round(x[, n])
987987

988988
Return the floating point value *x* rounded to *n* digits after the decimal
989-
point. If *n* is omitted, it defaults to zero. The result is a floating point
990-
number. Values are rounded to the closest multiple of 10 to the power minus
991-
*n*; if two multiples are equally close, rounding is done away from 0 (so. for
992-
example, ``round(0.5)`` is ``1.0`` and ``round(-0.5)`` is ``-1.0``).
989+
point. If *n* is omitted, it defaults to zero. Values are rounded to the
990+
closest multiple of 10 to the power minus *n*; if two multiples are equally
991+
close, rounding is done toward the even choice (so, for example, both
992+
``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is
993+
``2``). Delegates to ``x.__round__(n)``.
994+
995+
.. versionchanged:: 2.6
993996

994997

995998
.. function:: set([iterable])
@@ -1132,6 +1135,14 @@ available. They are listed here in alphabetical order.
11321135
.. versionadded:: 2.2
11331136

11341137

1138+
.. function:: trunc(x)
1139+
1140+
Return the :class:`Real` value *x* truncated to an :class:`Integral` (usually
1141+
a long integer). Delegates to ``x.__trunc__()``.
1142+
1143+
.. versionadded:: 2.6
1144+
1145+
11351146
.. function:: tuple([iterable])
11361147

11371148
Return a tuple whose items are the same and in the same order as *iterable*'s

‎Doc/library/math.rst‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,9 @@ Number-theoretic and representation functions:
2626

2727
.. function:: ceil(x)
2828

29-
Return the ceiling of *x* as a float, the smallest integer value greater than or
30-
equal to *x*.
29+
Return the ceiling of *x* as a float, the smallest integer value greater than
30+
or equal to *x*. If *x* is not a float, delegates to ``x.__ceil__()``, which
31+
should return an :class:`Integral` value.
3132

3233

3334
.. function:: fabs(x)
@@ -37,8 +38,9 @@ Number-theoretic and representation functions:
3738

3839
.. function:: floor(x)
3940

40-
Return the floor of *x* as a float, the largest integer value less than or equal
41-
to *x*.
41+
Return the floor of *x* as a float, the largest integer value less than or
42+
equal to *x*. If *x* is not a float, delegates to ``x.__floor__()``, which
43+
should return an :class:`Integral` value.
4244

4345

4446
.. function:: fmod(x, y)

‎Doc/library/numbers.rst‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
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`.

‎Doc/library/numeric.rst‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,18 @@ Numeric and Mathematical Modules
66
********************************
77

88
The modules described in this chapter provide numeric and math-related functions
9-
and data types. The :mod:`math` and :mod:`cmath` contain various mathematical
10-
functions for floating-point and complex numbers. For users more interested in
11-
decimal accuracy than in speed, the :mod:`decimal` module supports exact
12-
representations of decimal numbers.
9+
and data types. The :mod:`numbers` module defines an abstract hierarchy of
10+
numeric types. The :mod:`math` and :mod:`cmath` modules contain various
11+
mathematical functions for floating-point and complex numbers. For users more
12+
interested in decimal accuracy than in speed, the :mod:`decimal` module supports
13+
exact representations of decimal numbers.
1314

1415
The following modules are documented in this chapter:
1516

1617

1718
.. toctree::
1819

20+
numbers.rst
1921
math.rst
2022
cmath.rst
2123
decimal.rst

‎Doc/library/stdtypes.rst‎

Lines changed: 28 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -270,9 +270,8 @@ numbers of mixed type use the same rule. [#]_ The constructors :func:`int`,
270270
:func:`long`, :func:`float`, and :func:`complex` can be used to produce numbers
271271
of a specific type.
272272

273-
All numeric types (except complex) support the following operations, sorted by
274-
ascending priority (operations in the same box have the same priority; all
275-
numeric operations have a higher priority than comparison operations):
273+
All builtin numeric types support the following operations. See
274+
:ref:`power` and later sections for the operators' priorities.
276275

277276
+--------------------+---------------------------------+--------+
278277
| Operation | Result | Notes |
@@ -285,7 +284,7 @@ numeric operations have a higher priority than comparison operations):
285284
+--------------------+---------------------------------+--------+
286285
| ``x / y`` | quotient of *x* and *y* | \(1) |
287286
+--------------------+---------------------------------+--------+
288-
| ``x // y`` | (floored) quotient of *x* and | \(5) |
287+
| ``x // y`` | (floored) quotient of *x* and | (4)(5) |
289288
| | *y* | |
290289
+--------------------+---------------------------------+--------+
291290
| ``x % y`` | remainder of ``x / y`` | \(4) |
@@ -294,7 +293,7 @@ numeric operations have a higher priority than comparison operations):
294293
+--------------------+---------------------------------+--------+
295294
| ``+x`` | *x* unchanged | |
296295
+--------------------+---------------------------------+--------+
297-
| ``abs(x)`` | absolute value or magnitude of | |
296+
| ``abs(x)`` | absolute value or magnitude of | \(3) |
298297
| | *x* | |
299298
+--------------------+---------------------------------+--------+
300299
| ``int(x)`` | *x* converted to integer | \(2) |
@@ -308,11 +307,11 @@ numeric operations have a higher priority than comparison operations):
308307
| | *im* defaults to zero. | |
309308
+--------------------+---------------------------------+--------+
310309
| ``c.conjugate()`` | conjugate of the complex number | |
311-
| | *c* | |
310+
| | *c*. (Identity on real numbers) | |
312311
+--------------------+---------------------------------+--------+
313312
| ``divmod(x, y)`` | the pair ``(x // y, x % y)`` | (3)(4) |
314313
+--------------------+---------------------------------+--------+
315-
| ``pow(x, y)`` | *x* to the power *y* | |
314+
| ``pow(x, y)`` | *x* to the power *y* | \(3) |
316315
+--------------------+---------------------------------+--------+
317316
| ``x ** y`` | *x* to the power *y* | |
318317
+--------------------+---------------------------------+--------+
@@ -341,9 +340,12 @@ Notes:
341340
pair: numeric; conversions
342341
pair: C; language
343342

344-
Conversion from floating point to (long or plain) integer may round or truncate
345-
as in C; see functions :func:`floor` and :func:`ceil` in the :mod:`math` module
346-
for well-defined conversions.
343+
Conversion from floating point to (long or plain) integer may round or
344+
truncate as in C.
345+
346+
.. deprecated:: 2.6
347+
Instead, convert floats to long explicitly with :func:`trunc`,
348+
:func:`math.floor`, or :func:`math.ceil`.
347349

348350
(3)
349351
See :ref:`built-in-funcs` for a full description.
@@ -364,6 +366,22 @@ Notes:
364366

365367
.. versionadded:: 2.6
366368

369+
All :class:`numbers.Real` types (:class:`int`, :class:`long`, and
370+
:class:`float`) also include the following operations:
371+
372+
+--------------------+--------------------------------+--------+
373+
| Operation | Result | Notes |
374+
+====================+================================+========+
375+
| ``trunc(x)`` | *x* truncated to Integral | |
376+
+--------------------+--------------------------------+--------+
377+
| ``round(x[, n])`` | *x* rounded to n digits, | |
378+
| | rounding half to even. If n is | |
379+
| | omitted, it defaults to 0. | |
380+
+--------------------+--------------------------------+--------+
381+
| ``math.floor(x)`` | the greatest Integral <= *x* | |
382+
+--------------------+--------------------------------+--------+
383+
| ``math.ceil(x)`` | the least Integral >= *x* | |
384+
+--------------------+--------------------------------+--------+
367385

368386
.. XXXJH exceptions: overflow (when? what operations?) zerodivision
369387

‎Doc/reference/datamodel.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,7 @@ Ellipsis
150150
indicate the presence of the ``...`` syntax in a slice. Its truth value is
151151
true.
152152

153-
Numbers
153+
:class:`numbers.Number`
154154
.. index:: object: numeric
155155

156156
These are created by numeric literals and returned as results by arithmetic
@@ -162,7 +162,7 @@ Numbers
162162
Python distinguishes between integers, floating point numbers, and complex
163163
numbers:
164164

165-
Integers
165+
:class:`numbers.Integral`
166166
.. index:: object: integer
167167

168168
These represent elements from the mathematical set of integers (positive and
@@ -214,7 +214,7 @@ Numbers
214214
without causing overflow, will yield the same result in the long integer domain
215215
or when using mixed operands.
216216

217-
Floating point numbers
217+
:class:`numbers.Real` (:class:`float`)
218218
.. index::
219219
object: floating point
220220
pair: floating point; number
@@ -229,7 +229,7 @@ Numbers
229229
overhead of using objects in Python, so there is no reason to complicate the
230230
language with two kinds of floating point numbers.
231231

232-
Complex numbers
232+
:class:`numbers.Complex`
233233
.. index::
234234
object: complex
235235
pair: complex; number

‎Doc/reference/expressions.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -801,7 +801,8 @@ were of integer types and the second argument was negative, an exception was
801801
raised).
802802

803803
Raising ``0.0`` to a negative power results in a :exc:`ZeroDivisionError`.
804-
Raising a negative number to a fractional power results in a :exc:`ValueError`.
804+
Raising a negative number to a fractional power results in a :class:`complex`
805+
number. (Since Python 2.6. In earlier versions it raised a :exc:`ValueError`.)
805806

806807

807808
.. _unary:

0 commit comments

Comments
 (0)