Merged revisions 60481,60485,60489-60492,60494-60496,60498-60499,60501-60503,60505-60506,60508-60509,60523-60524,60532,60543,60545,60547-60548,60552,60554,60556-60559,60561-60562,60569,60571-60572,60574,60576-60583,60585-60586,60589,60591,60594-60595,60597-60598,60600-60601,60606-60612,60615,60617,60619-60621,60623-60625,60627-60629,60631,60633,60635,60647,60650,60652,60654,60656,60658-60659,60664-60666,60668-60670,60672,60676,60678,60680-60683,60685-60686,60688,60690,60692-60694,60697-60700,60705-60706,60708,60711,60714,60720,60724-60730,60732,60736,60742,60744,60746,60748,60750-60751,60753,60756-60757,60759-60761,60763-60764,60766,60769-60770,60774-60784,60787-60845 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r60790 | raymond.hettinger | 2008-02-14 10:32:45 +0100 (Thu, 14 Feb 2008) | 4 lines

  Add diagnostic message to help figure-out why SocketServer tests occasionally crash
  when trying to remove a pid that in not in the activechildren list.
........
  r60791 | raymond.hettinger | 2008-02-14 11:46:57 +0100 (Thu, 14 Feb 2008) | 1 line

  Add fixed-point examples to the decimal FAQ
........
  r60792 | raymond.hettinger | 2008-02-14 12:01:10 +0100 (Thu, 14 Feb 2008) | 1 line

  Improve rst markup
........
  r60794 | raymond.hettinger | 2008-02-14 12:57:25 +0100 (Thu, 14 Feb 2008) | 1 line

  Show how to remove exponents.
........
  r60795 | raymond.hettinger | 2008-02-14 13:05:42 +0100 (Thu, 14 Feb 2008) | 1 line

  Fix markup.
........
  r60797 | christian.heimes | 2008-02-14 13:47:33 +0100 (Thu, 14 Feb 2008) | 1 line

  Implemented Martin's suggestion to clear the free lists during the garbage collection of the highest generation.
........
  r60798 | raymond.hettinger | 2008-02-14 13:49:37 +0100 (Thu, 14 Feb 2008) | 1 line

  Simplify moneyfmt() recipe.
........
  r60810 | raymond.hettinger | 2008-02-14 20:02:39 +0100 (Thu, 14 Feb 2008) | 1 line

  Fix markup
........
  r60811 | raymond.hettinger | 2008-02-14 20:30:30 +0100 (Thu, 14 Feb 2008) | 1 line

  No need to register subclass of ABCs.
........
  r60814 | thomas.heller | 2008-02-14 22:00:28 +0100 (Thu, 14 Feb 2008) | 1 line

  Try to correct a markup error that does hide the following paragraph.
........
  r60822 | christian.heimes | 2008-02-14 23:40:11 +0100 (Thu, 14 Feb 2008) | 1 line

  Use a static and interned string for __subclasscheck__ and __instancecheck__ as suggested by Thomas Heller in #2115
........
  r60827 | christian.heimes | 2008-02-15 07:57:08 +0100 (Fri, 15 Feb 2008) | 1 line

  Fixed repr() and str() of complex numbers. Complex suffered from the same problem as floats but I forgot to test and fix them.
........
  r60830 | christian.heimes | 2008-02-15 09:20:11 +0100 (Fri, 15 Feb 2008) | 2 lines

  Bug #2111: mmap segfaults when trying to write a block opened with PROT_READ
  Thanks to Thomas Herve for the fix.
........
  r60835 | eric.smith | 2008-02-15 13:14:32 +0100 (Fri, 15 Feb 2008) | 1 line

  In PyNumber_ToBase, changed from an assert to returning an error when PyObject_Index() returns something other than an int or long.  It should never be possible to trigger this, as PyObject_Index checks to make sure it returns an int or long.
........
  r60837 | skip.montanaro | 2008-02-15 20:03:59 +0100 (Fri, 15 Feb 2008) | 8 lines

  Two new functions:

    * place_summary_first copies the regrtest summary to the front of the file
      making it easier to scan quickly for problems.

    * count_failures gets the actual count of the number of failing tests, not
      just a 1 (some failures) or 0 (no failures).
........
  r60840 | raymond.hettinger | 2008-02-15 22:21:25 +0100 (Fri, 15 Feb 2008) | 1 line

  Update example to match the current syntax.
........
  r60841 | amaury.forgeotdarc | 2008-02-15 22:22:45 +0100 (Fri, 15 Feb 2008) | 8 lines

  Issue #2115: __slot__ attributes setting was 10x slower.
  Also correct a possible crash using ABCs.

  This change is exactly the same as an optimisation
  done 5 years ago, but on slot *access*:
  http://svn.python.org/view?view=rev&rev=28297
........
  r60842 | amaury.forgeotdarc | 2008-02-15 22:27:44 +0100 (Fri, 15 Feb 2008) | 2 lines

  Temporarily let these tests pass
........
  r60843 | kurt.kaiser | 2008-02-15 22:56:36 +0100 (Fri, 15 Feb 2008) | 2 lines

  ScriptBinding event handlers weren't returning 'break'. Patch 2050, Tal Einat.
........
  r60844 | kurt.kaiser | 2008-02-15 23:25:09 +0100 (Fri, 15 Feb 2008) | 4 lines

  Configured selection highlighting colors were ignored; updating highlighting
  in the config dialog would cause non-Python files to be colored as if they
  were Python source; improve use of ColorDelagator.  Patch 1334. Tal Einat.
........
  r60845 | amaury.forgeotdarc | 2008-02-15 23:44:20 +0100 (Fri, 15 Feb 2008) | 9 lines

  Re-enable tests, they were failing since gc.collect() clears the various freelists.
  They still remain fragile.

  For example, a call to assertEqual currently does not make any allocation
  (which surprised me at first).
  But this can change when gc.collect also deletes the numerous "zombie frames"
  attached to each function.
........

1 files changed, 46 insertions, 17 deletions

diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst
index afba964..b0845e9 100644
--- a/Doc/library/decimal.rst
+++ b/Doc/library/decimal.rst
@@ -1352,19 +1352,15 @@ to work with the :class:`Decimal` class::
        '<.02>'
 
        """
-       q = Decimal((0, (1,), -places))    # 2 places --> '0.01'
-       sign, digits, exp = value.quantize(q).as_tuple()
-       assert exp == -places    
+       q = Decimal(10) ** -places      # 2 places --> '0.01'
+       sign, digits, exp = value.quantize(q).as_tuple()  
        result = []
        digits = map(str, digits)
        build, next = result.append, digits.pop
        if sign:
            build(trailneg)
        for i in range(places):
-           if digits:
-               build(next())
-           else:
-               build('0')
+           build(next() if digits else '0')
        build(dp)
        i = 0
        while digits:
@@ -1374,12 +1370,8 @@ to work with the :class:`Decimal` class::
                i = 0
                build(sep)
        build(curr)
-       if sign:
-           build(neg)
-       else:
-           build(pos)
-       result.reverse()
-       return ''.join(result)
+       build(neg if sign else pos)
+       return ''.join(reversed(result))
 
    def pi():
        """Compute Pi to the current precision.
@@ -1482,7 +1474,7 @@ Decimal FAQ
 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')
@@ -1513,9 +1505,36 @@ the :const:`Inexact` trap is set, it is also useful for validation::
 Q. Once I have valid two place inputs, how do I maintain that invariant
 throughout an application?
 
-A. Some operations like addition and subtraction automatically preserve fixed
-point.  Others, like multiplication and division, change the number of decimal
-places and need to be followed-up with a :meth:`quantize` step.
+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::
+
+    >>> a = Decimal('102.72')           # Initial fixed-point values
+    >>> b = Decimal('3.17')
+    >>> a + b                           # Addition preserves fixed-point
+    Decimal('105.89')
+    >>> a - b
+    Decimal('99.55')
+    >>> a * 42                          # So does integer multiplication
+    Decimal('4314.24')
+    >>> (a * b).quantize(TWOPLACES)     # Must quantize non-integer multiplication
+    Decimal('325.62')
+    >>> (b / a).quantize(TWOPLACES)     # And quantize division
+    Decimal('0.03')
+
+In developing fixed-point applications, it is convenient to define functions
+to handle the :meth:`quantize` step::
+
+    >>> def mul(x, y, fp=TWOPLACES):
+    ...     return (x * y).quantize(fp)
+    >>> def div(x, y, fp=TWOPLACES):
+    ...     return (x / y).quantize(fp)
+
+    >>> mul(a, b)                       # Automatically preserve fixed-point
+    Decimal('325.62')
+    >>> div(b, a)
+    Decimal('0.03')
 
 Q. There are many ways to express the same value.  The numbers :const:`200`,
 :const:`200.000`, :const:`2E2`, and :const:`.02E+4` all have the same value at
@@ -1537,6 +1556,16 @@ of significant places in the coefficient.  For example, expressing
 :const:`5.0E+3` as :const:`5000` keeps the value constant but cannot show the
 original's two-place significance.
 
+If an application does not care about tracking significance, it is easy to
+remove the exponent and trailing zeroes, losing signficance, but keeping the
+value unchanged::
+
+    >>> def remove_exponent(d):
+    ...     return d.quantize(Decimal(1)) if d == d.to_integral() else d.normalize()
+
+    >>> remove_exponent(Decimal('5E+3'))
+    Decimal('5000')
+
 Q. Is there a way to convert a regular float to a :class:`Decimal`?
 
 A. Yes, all binary floating point numbers can be exactly expressed as a