Add notes on how decimal fits into the model.

diff --git a/Lib/numbers.py b/Lib/numbers.py
index cbcecedeca1c404c55a6eae8d99507a17afcd739..4728f99a59007688bb0ab8b41cf70d2277ae6aed 100644 (file)
--- a/Lib/numbers.py
+++ b/Lib/numbers.py
@@ -49,6 +49,35 @@ Inexact.register(float)
 # Inexact.register(decimal.Decimal)
 
 
+## Notes on Decimal and how relates to the numeric tower
+## -----------------------------------------------------
+## Decimal is Real except that it does not support the real and imag properties
+## or the conjugate() and complex() methods.  If those get defined at some
+## point, they cannot use the default implementation which would be sensitive
+## to decimal.Context and could produce different answers at different times.
+##
+## 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.