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,60735-60751 via svnmerge from

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

........
  r60735 | raymond.hettinger | 2008-02-11 23:53:01 +0100 (Mon, 11 Feb 2008) | 1 line

  Add notes on how decimal fits into the model.
........
  r60737 | raymond.hettinger | 2008-02-12 00:34:56 +0100 (Tue, 12 Feb 2008) | 1 line

  Fix markup
........
  r60738 | raymond.hettinger | 2008-02-12 00:38:00 +0100 (Tue, 12 Feb 2008) | 1 line

  Backport ABC docs
........
  r60739 | raymond.hettinger | 2008-02-12 01:15:32 +0100 (Tue, 12 Feb 2008) | 1 line

  Restore fractions.rst to the document tree.
........
  r60740 | raymond.hettinger | 2008-02-12 01:48:20 +0100 (Tue, 12 Feb 2008) | 1 line

  Fix typo in comments
........
  r60741 | raymond.hettinger | 2008-02-12 02:18:03 +0100 (Tue, 12 Feb 2008) | 1 line

  Bring decimal a bit closer to the spec for Reals.
........
  r60743 | martin.v.loewis | 2008-02-12 14:47:26 +0100 (Tue, 12 Feb 2008) | 2 lines

  Patch #1736: Fix file name handling of _msi.FCICreate.
........
  r60745 | kurt.kaiser | 2008-02-12 16:45:50 +0100 (Tue, 12 Feb 2008) | 2 lines

  what??! Correct r60225.
........
  r60747 | martin.v.loewis | 2008-02-12 19:47:34 +0100 (Tue, 12 Feb 2008) | 4 lines

  Patch #1966: Break infinite loop in httplib when the servers
  implements the chunked encoding incorrectly.
  Will backport to 2.5.
........
  r60749 | raymond.hettinger | 2008-02-12 20:05:36 +0100 (Tue, 12 Feb 2008) | 1 line

  dict.copy() rises from the ashes.  Revert r60687.
........

1 files changed, 26 insertions, 0 deletions

diff --git a/Lib/numbers.py b/Lib/numbers.py
index b5150d22ff..a4b7a6d260 100644
--- a/Lib/numbers.py
+++ b/Lib/numbers.py
@@ -46,6 +46,32 @@ Inexact.register(float)
 # Inexact.register(decimal.Decimal)
 
 
+## Notes on Decimal and it how relates to the numeric tower
+## --------------------------------------------------------
+## Decimal is Real except that it does not support rich comparisons.
+##
+## Decimal has some of the characteristics of Integrals.  It provides
+## logical operations but not as operators.  The logical operations only apply
+## to a subset of decimals (those that are non-negative, have a zero exponent,
+## and have digits that are only 0 or 1).  It does provide __long__() and
+## a three argument form of __pow__ that includes exactness guarantees.
+## It does not provide an __index__() method.
+##
+## Depending on context, decimal operations may be exact or inexact.
+##
+## When decimal is run in a context with small precision and automatic rounding,
+## it is Inexact.  See the "Floating point notes" section of the decimal docs
+## for an example of losing the associative and distributive properties of
+## addition.
+##
+## When decimal is used for high precision integer arithmetic, it is Exact.
+## When the decimal used as fixed-point, it is Exact.
+## When it is run with sufficient precision, it is Exact.
+## When the decimal.Inexact trap is set, decimal operations are Exact.
+## For an example, see the float_to_decimal() recipe in the "Decimal FAQ"
+## section of the docs -- it shows an how traps are used in conjunction
+## with variable precision to reliably achieve exact results.
+
 class Complex(Number):
     """Complex defines the operations that work on the builtin complex type.