Merged revisions 61724-61725,61731-61735,61737,61739,61741,61743-61744,61753,61761,61765-61767,61769,61773,61776-61778,61780-61783,61788,61793,61796,61807,61813 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
................
r61724 | martin.v.loewis | 2008-03-22 01:01:12 +0100 (Sat, 22 Mar 2008) | 49 lines
Merged revisions 61602-61723 via svnmerge from
svn+ssh://pythondev@svn.python.org/sandbox/trunk/2to3/lib2to3
........
r61626 | david.wolever | 2008-03-19 17:19:16 +0100 (Mi, 19 M?\195?\164r 2008) | 1 line
Added fixer for implicit local imports. See #2414.
........
r61628 | david.wolever | 2008-03-19 17:57:43 +0100 (Mi, 19 M?\195?\164r 2008) | 1 line
Added a class for tests which should not run if a particular import is found.
........
r61629 | collin.winter | 2008-03-19 17:58:19 +0100 (Mi, 19 M?\195?\164r 2008) | 1 line
Two more relative import fixes in pgen2.
........
r61635 | david.wolever | 2008-03-19 20:16:03 +0100 (Mi, 19 M?\195?\164r 2008) | 1 line
Fixed print fixer so it will do the Right Thing when it encounters __future__.print_function. 2to3 gets upset, though, so the tests have been commented out.
........
r61637 | david.wolever | 2008-03-19 21:37:17 +0100 (Mi, 19 M?\195?\164r 2008) | 3 lines
Added a fixer for itertools imports (from itertools import imap, ifilterfalse --> from itertools import filterfalse)
........
r61645 | david.wolever | 2008-03-19 23:22:35 +0100 (Mi, 19 M?\195?\164r 2008) | 1 line
SVN is happier when you add the files you create... -_-'
........
r61654 | david.wolever | 2008-03-20 01:09:56 +0100 (Do, 20 M?\195?\164r 2008) | 1 line
Added an explicit sort order to fixers -- fixes problems like #2427
........
r61664 | david.wolever | 2008-03-20 04:32:40 +0100 (Do, 20 M?\195?\164r 2008) | 3 lines
Fixes #2428 -- comments are no longer eatten by __future__ fixer.
........
r61673 | david.wolever | 2008-03-20 17:22:40 +0100 (Do, 20 M?\195?\164r 2008) | 1 line
Added 2to3 node pretty-printer
........
r61679 | david.wolever | 2008-03-20 20:50:42 +0100 (Do, 20 M?\195?\164r 2008) | 1 line
Made node printing a little bit prettier
........
r61723 | martin.v.loewis | 2008-03-22 00:59:27 +0100 (Sa, 22 M?\195?\164r 2008) | 2 lines
Fix whitespace.
........
................
r61725 | martin.v.loewis | 2008-03-22 01:02:41 +0100 (Sat, 22 Mar 2008) | 2 lines
Install lib2to3.
................
r61731 | facundo.batista | 2008-03-22 03:45:37 +0100 (Sat, 22 Mar 2008) | 4 lines
Small fix that complicated the test actually when that
test failed.
................
r61732 | alexandre.vassalotti | 2008-03-22 05:08:44 +0100 (Sat, 22 Mar 2008) | 2 lines
Added warning for the removal of 'hotshot' in Py3k.
................
r61733 | georg.brandl | 2008-03-22 11:07:29 +0100 (Sat, 22 Mar 2008) | 4 lines
#1918: document that weak references *to* an object are
cleared before the object's __del__ is called, to ensure that the weak
reference callback (if any) finds the object healthy.
................
r61734 | georg.brandl | 2008-03-22 11:56:23 +0100 (Sat, 22 Mar 2008) | 2 lines
Activate the Sphinx doctest extension and convert howto/functional to use it.
................
r61735 | georg.brandl | 2008-03-22 11:58:38 +0100 (Sat, 22 Mar 2008) | 2 lines
Allow giving source names on the cmdline.
................
r61737 | georg.brandl | 2008-03-22 12:00:48 +0100 (Sat, 22 Mar 2008) | 2 lines
Fixup this HOWTO's doctest blocks so that they can be run with sphinx' doctest builder.
................
r61739 | georg.brandl | 2008-03-22 12:47:10 +0100 (Sat, 22 Mar 2008) | 2 lines
Test decimal.rst doctests as far as possible with sphinx doctest.
................
r61741 | georg.brandl | 2008-03-22 13:04:26 +0100 (Sat, 22 Mar 2008) | 2 lines
Make doctests in re docs usable with sphinx' doctest.
................
r61743 | georg.brandl | 2008-03-22 13:59:37 +0100 (Sat, 22 Mar 2008) | 2 lines
Make more doctests in pprint docs testable.
................
r61744 | georg.brandl | 2008-03-22 14:07:06 +0100 (Sat, 22 Mar 2008) | 2 lines
No need to specify explicit "doctest_block" anymore.
................
r61753 | georg.brandl | 2008-03-22 21:08:43 +0100 (Sat, 22 Mar 2008) | 2 lines
Fix-up syntax problems.
................
r61761 | georg.brandl | 2008-03-22 22:06:20 +0100 (Sat, 22 Mar 2008) | 4 lines
Make collections' doctests executable.
(The <BLANKLINE>s will be stripped from presentation output.)
................
r61765 | georg.brandl | 2008-03-22 22:21:57 +0100 (Sat, 22 Mar 2008) | 2 lines
Test doctests in datetime docs.
................
r61766 | georg.brandl | 2008-03-22 22:26:44 +0100 (Sat, 22 Mar 2008) | 2 lines
Test doctests in operator docs.
................
r61767 | georg.brandl | 2008-03-22 22:38:33 +0100 (Sat, 22 Mar 2008) | 2 lines
Enable doctests in functions.rst. Already found two errors :)
................
r61769 | georg.brandl | 2008-03-22 23:04:10 +0100 (Sat, 22 Mar 2008) | 3 lines
Enable doctest running for several other documents.
We have now over 640 doctests that are run with "make doctest".
................
r61773 | raymond.hettinger | 2008-03-23 01:55:46 +0100 (Sun, 23 Mar 2008) | 1 line
Simplify demo code.
................
r61776 | neal.norwitz | 2008-03-23 04:43:33 +0100 (Sun, 23 Mar 2008) | 7 lines
Try to make this test a little more robust and not fail with:
timeout (10.0025) is more than 2 seconds more than expected (0.001)
I'm assuming this problem is caused by DNS lookup. This change
does a DNS lookup of the hostname before trying to connect, so the time
is not included.
................
r61777 | neal.norwitz | 2008-03-23 05:08:30 +0100 (Sun, 23 Mar 2008) | 1 line
Speed up the test by avoiding socket timeouts.
................
r61778 | neal.norwitz | 2008-03-23 05:43:09 +0100 (Sun, 23 Mar 2008) | 1 line
Skip the epoll test if epoll() does not work
................
r61780 | neal.norwitz | 2008-03-23 06:47:20 +0100 (Sun, 23 Mar 2008) | 1 line
Suppress failure (to avoid a flaky test) if we cannot connect to svn.python.org
................
r61781 | neal.norwitz | 2008-03-23 07:13:25 +0100 (Sun, 23 Mar 2008) | 4 lines
Move itertools before future_builtins since the latter depends on the former.
From a clean build importing future_builtins would fail since itertools
wasn't built yet.
................
r61782 | neal.norwitz | 2008-03-23 07:16:04 +0100 (Sun, 23 Mar 2008) | 1 line
Try to prevent the alarm going off early in tearDown
................
r61783 | neal.norwitz | 2008-03-23 07:19:57 +0100 (Sun, 23 Mar 2008) | 4 lines
Remove compiler warnings (on Alpha at least) about using chars as
array subscripts. Using chars are dangerous b/c they are signed
on some platforms and unsigned on others.
................
r61788 | georg.brandl | 2008-03-23 09:05:30 +0100 (Sun, 23 Mar 2008) | 2 lines
Make the doctests presentation-friendlier.
................
r61793 | amaury.forgeotdarc | 2008-03-23 10:55:29 +0100 (Sun, 23 Mar 2008) | 4 lines
#1477: ur'\U0010FFFF' raised in narrow unicode builds.
Corrected the raw-unicode-escape codec to use UTF-16 surrogates in
this case, just like the unicode-escape codec.
................
r61796 | raymond.hettinger | 2008-03-23 14:32:32 +0100 (Sun, 23 Mar 2008) | 1 line
Issue 1681432: Add triangular distribution the random module.
................
r61807 | raymond.hettinger | 2008-03-23 20:37:53 +0100 (Sun, 23 Mar 2008) | 4 lines
Adopt Nick's suggestion for useful default arguments.
Clean-up floating point issues by adding true division and float constants.
................
r61813 | gregory.p.smith | 2008-03-23 22:04:43 +0100 (Sun, 23 Mar 2008) | 6 lines
Fix gzip to deal with CRC's being signed values in Python 2.x properly and to
read 32bit values as unsigned to start with rather than applying signedness
fixups allover the place afterwards.
This hopefully fixes the test_tarfile failure on the alpha/tru64 buildbot.
................
diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst
index ac21b57..04433c1 100644
--- a/Doc/library/decimal.rst
+++ b/Doc/library/decimal.rst
@@ -12,6 +12,14 @@
.. moduleauthor:: Tim Peters <tim.one at comcast.net>
.. sectionauthor:: Raymond D. Hettinger <python at rcn.com>
+.. import modules for testing inline doctests with the Sphinx doctest builder
+.. testsetup:: *
+
+ import decimal
+ import math
+ from decimal import *
+ # make sure each group gets a fresh context
+ setcontext(Context())
The :mod:`decimal` module provides support for decimal floating point
arithmetic. It offers several advantages over the :class:`float` datatype:
@@ -42,7 +50,7 @@
* Unlike hardware based binary floating point, the decimal module has a user
alterable precision (defaulting to 28 places) which can be as large as needed for
- a given problem::
+ a given problem:
>>> getcontext().prec = 6
>>> Decimal(1) / Decimal(7)
@@ -115,8 +123,8 @@
>>> from decimal import *
>>> getcontext()
Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
- capitals=1, flags=[], traps=[Overflow, InvalidOperation,
- DivisionByZero])
+ capitals=1, flags=[], traps=[Overflow, DivisionByZero,
+ InvalidOperation])
>>> getcontext().prec = 7 # Set a new precision
@@ -125,7 +133,7 @@
serves as an explicit reminder of the details of the conversion (including
representation error). Decimal numbers include special values such as
:const:`NaN` which stands for "Not a number", positive and negative
-:const:`Infinity`, and :const:`-0`. ::
+:const:`Infinity`, and :const:`-0`.
>>> Decimal(10)
Decimal('10')
@@ -144,7 +152,9 @@
The significance of a new Decimal is determined solely by the number of digits
input. Context precision and rounding only come into play during arithmetic
-operations. ::
+operations.
+
+.. doctest:: newcontext
>>> getcontext().prec = 6
>>> Decimal('3.0')
@@ -158,7 +168,10 @@
Decimal('5.85988')
Decimals interact well with much of the rest of Python. Here is a small decimal
-floating point flying circus::
+floating point flying circus:
+
+.. doctest::
+ :options: +NORMALIZE_WHITESPACE
>>> data = map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split())
>>> max(data)
@@ -186,7 +199,7 @@
>>> c % a
Decimal('0.77')
-And some mathematical functions are also available to Decimal::
+And some mathematical functions are also available to Decimal:
>>> Decimal(2).sqrt()
Decimal('1.414213562373095048801688724')
@@ -199,7 +212,7 @@
The :meth:`quantize` method rounds a number to a fixed exponent. This method is
useful for monetary applications that often round results to a fixed number of
-places::
+places:
>>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)
Decimal('7.32')
@@ -217,7 +230,10 @@
In accordance with the standard, the :mod:`Decimal` module provides two ready to
use standard contexts, :const:`BasicContext` and :const:`ExtendedContext`. The
former is especially useful for debugging because many of the traps are
-enabled::
+enabled:
+
+.. doctest:: newcontext
+ :options: +NORMALIZE_WHITESPACE
>>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)
>>> setcontext(myothercontext)
@@ -251,15 +267,18 @@
Decimal('3.14159292')
>>> getcontext()
Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
- capitals=1, flags=[Inexact, Rounded], traps=[])
+ capitals=1, flags=[Rounded, Inexact], traps=[])
The *flags* entry shows that the rational approximation to :const:`Pi` was
rounded (digits beyond the context precision were thrown away) and that the
result is inexact (some of the discarded digits were non-zero).
Individual traps are set using the dictionary in the :attr:`traps` field of a
-context::
+context:
+.. doctest:: newcontext
+
+ >>> setcontext(ExtendedContext)
>>> Decimal(1) / Decimal(0)
Decimal('Infinity')
>>> getcontext().traps[DivisionByZero] = 1
@@ -387,7 +406,7 @@
but the result gives a total ordering on :class:`Decimal`
instances. Two :class:`Decimal` instances with the same numeric
value but different representations compare unequal in this
- ordering::
+ ordering:
>>> Decimal('12.0').compare_total(Decimal('12'))
Decimal('-1')
@@ -426,7 +445,7 @@
.. method:: Decimal.copy_sign(other)
Return a copy of the first operand with the sign set to be the
- same as the sign of the second operand. For example::
+ same as the sign of the second operand. For example:
>>> Decimal('2.3').copy_sign(Decimal('-1.5'))
Decimal('-2.3')
@@ -934,7 +953,9 @@
needed by the application. Another benefit is that rounding immediately
eliminates unintended effects from digits beyond the current precision. In the
following example, using unrounded inputs means that adding zero to a sum can
- change the result::
+ change the result:
+
+ .. doctest:: newcontext
>>> getcontext().prec = 3
>>> Decimal('3.4445') + Decimal('1.0023')
@@ -1187,7 +1208,9 @@
of nearly offsetting quantities resulting in loss of significance. Knuth
provides two instructive examples where rounded floating point arithmetic with
insufficient precision causes the breakdown of the associative and distributive
-properties of addition::
+properties of addition:
+
+.. doctest:: newcontext
# Examples from Seminumerical Algorithms, Section 4.2.2.
>>> from decimal import Decimal, getcontext
@@ -1206,7 +1229,9 @@
Decimal('0.0060000')
The :mod:`decimal` module makes it possible to restore the identities by
-expanding the precision sufficiently to avoid loss of significance::
+expanding the precision sufficiently to avoid loss of significance:
+
+.. doctest:: newcontext
>>> getcontext().prec = 20
>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
@@ -1272,7 +1297,7 @@
various representations of zero with differing precisions yet equivalent in
value. This takes a bit of getting used to. For an eye accustomed to
normalized floating point representations, it is not immediately obvious that
-the following calculation returns a value equal to zero::
+the following calculation returns a value equal to zero:
>>> 1 / Decimal('Infinity')
Decimal('0E-1000000026')
@@ -1474,7 +1499,7 @@
Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to
minimize typing when using the interactive interpreter?
-A. Some users abbreviate the constructor to just a single letter::
+A. Some users abbreviate the constructor to just a single letter:
>>> D = decimal.Decimal
>>> D('1.23') + D('3.45')
@@ -1485,7 +1510,7 @@
and need to be validated. What methods should be used?
A. The :meth:`quantize` method rounds to a fixed number of decimal places. If
-the :const:`Inexact` trap is set, it is also useful for validation::
+the :const:`Inexact` trap is set, it is also useful for validation:
>>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01')
@@ -1500,7 +1525,7 @@
>>> Decimal('3.214').quantize(TWOPLACES, context=Context(traps=[Inexact]))
Traceback (most recent call last):
...
- Inexact: Changed in rounding
+ Inexact
Q. Once I have valid two place inputs, how do I maintain that invariant
throughout an application?
@@ -1508,7 +1533,7 @@
A. Some operations like addition, subtraction, and multiplication by an integer
will automatically preserve fixed point. Others operations, like division and
non-integer multiplication, will change the number of decimal places and need to
-be followed-up with a :meth:`quantize` step::
+be followed-up with a :meth:`quantize` step:
>>> a = Decimal('102.72') # Initial fixed-point values
>>> b = Decimal('3.17')
@@ -1524,7 +1549,7 @@
Decimal('0.03')
In developing fixed-point applications, it is convenient to define functions
-to handle the :meth:`quantize` step::
+to handle the :meth:`quantize` step:
>>> def mul(x, y, fp=TWOPLACES):
... return (x * y).quantize(fp)
@@ -1542,7 +1567,7 @@
canonical value?
A. The :meth:`normalize` method maps all equivalent values to a single
-representative::
+representative:
>>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
>>> [v.normalize() for v in values]
@@ -1558,7 +1583,7 @@
If an application does not care about tracking significance, it is easy to
remove the exponent and trailing zeroes, losing significance, but keeping the
-value unchanged::
+value unchanged:
>>> def remove_exponent(d):
... return d.quantize(Decimal(1)) if d == d.to_integral() else d.normalize()
@@ -1570,7 +1595,9 @@
A. Yes, all binary floating point numbers can be exactly expressed as a
Decimal. An exact conversion may take more precision than intuition would
-suggest, so we trap :const:`Inexact` to signal a need for more precision::
+suggest, so we trap :const:`Inexact` to signal a need for more precision:
+
+.. testcode::
def float_to_decimal(f):
"Convert a floating point number to a Decimal with no loss of information"
@@ -1583,6 +1610,8 @@
except Inexact:
ctx.prec += 1
+.. doctest::
+
>>> float_to_decimal(math.pi)
Decimal('3.141592653589793115997963468544185161590576171875')
@@ -1590,7 +1619,7 @@
A. There is some question about whether it is advisable to mix binary and
decimal floating point. Also, its use requires some care to avoid the
-representation issues associated with binary floating point::
+representation issues associated with binary floating point:
>>> float_to_decimal(1.1)
Decimal('1.100000000000000088817841970012523233890533447265625')
@@ -1610,23 +1639,27 @@
A. Yes. The principle is that all values are considered to be exact and so is
the arithmetic on those values. Only the results are rounded. The advantage
for inputs is that "what you type is what you get". A disadvantage is that the
-results can look odd if you forget that the inputs haven't been rounded::
+results can look odd if you forget that the inputs haven't been rounded:
+
+.. doctest:: newcontext
>>> getcontext().prec = 3
- >>> Decimal('3.104') + D('2.104')
+ >>> Decimal('3.104') + Decimal('2.104')
Decimal('5.21')
- >>> Decimal('3.104') + D('0.000') + D('2.104')
+ >>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104')
Decimal('5.20')
The solution is either to increase precision or to force rounding of inputs
-using the unary plus operation::
+using the unary plus operation:
+
+.. doctest:: newcontext
>>> getcontext().prec = 3
>>> +Decimal('1.23456789') # unary plus triggers rounding
Decimal('1.23')
Alternatively, inputs can be rounded upon creation using the
-:meth:`Context.create_decimal` method::
+:meth:`Context.create_decimal` method:
>>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
Decimal('1.2345')