Move the 3k reST doc tree in place.

1 files changed, 1289 insertions, 0 deletions

diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst
new file mode 100644
index 0000000..1d17109
--- /dev/null
+++ b/Doc/library/decimal.rst
@@ -0,0 +1,1289 @@
+
+:mod:`decimal` --- Decimal floating point arithmetic
+====================================================
+
+.. module:: decimal
+   :synopsis: Implementation of the General Decimal Arithmetic  Specification.
+
+
+.. moduleauthor:: Eric Price <eprice at tjhsst.edu>
+.. moduleauthor:: Facundo Batista <facundo at taniquetil.com.ar>
+.. moduleauthor:: Raymond Hettinger <python at rcn.com>
+.. moduleauthor:: Aahz <aahz at pobox.com>
+.. moduleauthor:: Tim Peters <tim.one at comcast.net>
+
+
+.. sectionauthor:: Raymond D. Hettinger <python at rcn.com>
+
+
+.. versionadded:: 2.4
+
+The :mod:`decimal` module provides support for decimal floating point
+arithmetic.  It offers several advantages over the :class:`float()` datatype:
+
+* Decimal numbers can be represented exactly.  In contrast, numbers like
+  :const:`1.1` do not have an exact representation in binary floating point. End
+  users typically would not expect :const:`1.1` to display as
+  :const:`1.1000000000000001` as it does with binary floating point.
+
+* The exactness carries over into arithmetic.  In decimal floating point, ``0.1
+  + 0.1 + 0.1 - 0.3`` is exactly equal to zero.  In binary floating point, result
+  is :const:`5.5511151231257827e-017`.  While near to zero, the differences
+  prevent reliable equality testing and differences can accumulate. For this
+  reason, decimal would be preferred in accounting applications which have strict
+  equality invariants.
+
+* The decimal module incorporates a notion of significant places so that ``1.30
+  + 1.20`` is :const:`2.50`.  The trailing zero is kept to indicate significance.
+  This is the customary presentation for monetary applications. For
+  multiplication, the "schoolbook" approach uses all the figures in the
+  multiplicands.  For instance, ``1.3 * 1.2`` gives :const:`1.56` while ``1.30 *
+  1.20`` gives :const:`1.5600`.
+
+* Unlike hardware based binary floating point, the decimal module has a user
+  settable precision (defaulting to 28 places) which can be as large as needed for
+  a given problem::
+
+     >>> getcontext().prec = 6
+     >>> Decimal(1) / Decimal(7)
+     Decimal("0.142857")
+     >>> getcontext().prec = 28
+     >>> Decimal(1) / Decimal(7)
+     Decimal("0.1428571428571428571428571429")
+
+* Both binary and decimal floating point are implemented in terms of published
+  standards.  While the built-in float type exposes only a modest portion of its
+  capabilities, the decimal module exposes all required parts of the standard.
+  When needed, the programmer has full control over rounding and signal handling.
+
+The module design is centered around three concepts:  the decimal number, the
+context for arithmetic, and signals.
+
+A decimal number is immutable.  It has a sign, coefficient digits, and an
+exponent.  To preserve significance, the coefficient digits do not truncate
+trailing zeroes.  Decimals also include special values such as
+:const:`Infinity`, :const:`-Infinity`, and :const:`NaN`.  The standard also
+differentiates :const:`-0` from :const:`+0`.
+
+The context for arithmetic is an environment specifying precision, rounding
+rules, limits on exponents, flags indicating the results of operations, and trap
+enablers which determine whether signals are treated as exceptions.  Rounding
+options include :const:`ROUND_CEILING`, :const:`ROUND_DOWN`,
+:const:`ROUND_FLOOR`, :const:`ROUND_HALF_DOWN`, :const:`ROUND_HALF_EVEN`,
+:const:`ROUND_HALF_UP`, and :const:`ROUND_UP`.
+
+Signals are groups of exceptional conditions arising during the course of
+computation.  Depending on the needs of the application, signals may be ignored,
+considered as informational, or treated as exceptions. The signals in the
+decimal module are: :const:`Clamped`, :const:`InvalidOperation`,
+:const:`DivisionByZero`, :const:`Inexact`, :const:`Rounded`, :const:`Subnormal`,
+:const:`Overflow`, and :const:`Underflow`.
+
+For each signal there is a flag and a trap enabler.  When a signal is
+encountered, its flag is incremented from zero and, then, if the trap enabler is
+set to one, an exception is raised.  Flags are sticky, so the user needs to
+reset them before monitoring a calculation.
+
+
+.. seealso::
+
+   IBM's General Decimal Arithmetic Specification, `The General Decimal Arithmetic
+   Specification <http://www2.hursley.ibm.com/decimal/decarith.html>`_.
+
+   IEEE standard 854-1987, `Unofficial IEEE 854 Text
+   <http://www.cs.berkeley.edu/~ejr/projects/754/private/drafts/854-1987/dir.html>`_.
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-tutorial:
+
+Quick-start Tutorial
+--------------------
+
+The usual start to using decimals is importing the module, viewing the current
+context with :func:`getcontext` and, if necessary, setting new values for
+precision, rounding, or enabled traps::
+
+   >>> from decimal import *
+   >>> getcontext()
+   Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
+           capitals=1, flags=[], traps=[Overflow, InvalidOperation,
+           DivisionByZero])
+
+   >>> getcontext().prec = 7       # Set a new precision
+
+Decimal instances can be constructed from integers, strings, or tuples.  To
+create a Decimal from a :class:`float`, first convert it to a string.  This
+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`.         ::
+
+   >>> Decimal(10)
+   Decimal("10")
+   >>> Decimal("3.14")
+   Decimal("3.14")
+   >>> Decimal((0, (3, 1, 4), -2))
+   Decimal("3.14")
+   >>> Decimal(str(2.0 ** 0.5))
+   Decimal("1.41421356237")
+   >>> Decimal("NaN")
+   Decimal("NaN")
+   >>> Decimal("-Infinity")
+   Decimal("-Infinity")
+
+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. ::
+
+   >>> getcontext().prec = 6
+   >>> Decimal('3.0')
+   Decimal("3.0")
+   >>> Decimal('3.1415926535')
+   Decimal("3.1415926535")
+   >>> Decimal('3.1415926535') + Decimal('2.7182818285')
+   Decimal("5.85987")
+   >>> getcontext().rounding = ROUND_UP
+   >>> Decimal('3.1415926535') + Decimal('2.7182818285')
+   Decimal("5.85988")
+
+Decimals interact well with much of the rest of Python.  Here is a small decimal
+floating point flying circus::
+
+   >>> data = map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split())
+   >>> max(data)
+   Decimal("9.25")
+   >>> min(data)
+   Decimal("0.03")
+   >>> sorted(data)
+   [Decimal("0.03"), Decimal("1.00"), Decimal("1.34"), Decimal("1.87"),
+    Decimal("2.35"), Decimal("3.45"), Decimal("9.25")]
+   >>> sum(data)
+   Decimal("19.29")
+   >>> a,b,c = data[:3]
+   >>> str(a)
+   '1.34'
+   >>> float(a)
+   1.3400000000000001
+   >>> round(a, 1)     # round() first converts to binary floating point
+   1.3
+   >>> int(a)
+   1
+   >>> a * 5
+   Decimal("6.70")
+   >>> a * b
+   Decimal("2.5058")
+   >>> c % a
+   Decimal("0.77")
+
+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::
+
+   >>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)
+   Decimal("7.32")
+   >>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)
+   Decimal("8")
+
+As shown above, the :func:`getcontext` function accesses the current context and
+allows the settings to be changed.  This approach meets the needs of most
+applications.
+
+For more advanced work, it may be useful to create alternate contexts using the
+Context() constructor.  To make an alternate active, use the :func:`setcontext`
+function.
+
+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::
+
+   >>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)
+   >>> setcontext(myothercontext)
+   >>> Decimal(1) / Decimal(7)
+   Decimal("0.142857142857142857142857142857142857142857142857142857142857")
+
+   >>> ExtendedContext
+   Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
+           capitals=1, flags=[], traps=[])
+   >>> setcontext(ExtendedContext)
+   >>> Decimal(1) / Decimal(7)
+   Decimal("0.142857143")
+   >>> Decimal(42) / Decimal(0)
+   Decimal("Infinity")
+
+   >>> setcontext(BasicContext)
+   >>> Decimal(42) / Decimal(0)
+   Traceback (most recent call last):
+     File "<pyshell#143>", line 1, in -toplevel-
+       Decimal(42) / Decimal(0)
+   DivisionByZero: x / 0
+
+Contexts also have signal flags for monitoring exceptional conditions
+encountered during computations.  The flags remain set until explicitly cleared,
+so it is best to clear the flags before each set of monitored computations by
+using the :meth:`clear_flags` method. ::
+
+   >>> setcontext(ExtendedContext)
+   >>> getcontext().clear_flags()
+   >>> Decimal(355) / Decimal(113)
+   Decimal("3.14159292")
+   >>> getcontext()
+   Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
+           capitals=1, flags=[Inexact, Rounded], 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::
+
+   >>> Decimal(1) / Decimal(0)
+   Decimal("Infinity")
+   >>> getcontext().traps[DivisionByZero] = 1
+   >>> Decimal(1) / Decimal(0)
+   Traceback (most recent call last):
+     File "<pyshell#112>", line 1, in -toplevel-
+       Decimal(1) / Decimal(0)
+   DivisionByZero: x / 0
+
+Most programs adjust the current context only once, at the beginning of the
+program.  And, in many applications, data is converted to :class:`Decimal` with
+a single cast inside a loop.  With context set and decimals created, the bulk of
+the program manipulates the data no differently than with other Python numeric
+types.
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-decimal:
+
+Decimal objects
+---------------
+
+
+.. class:: Decimal([value [, context]])
+
+   Constructs a new :class:`Decimal` object based from *value*.
+
+   *value* can be an integer, string, tuple, or another :class:`Decimal` object. If
+   no *value* is given, returns ``Decimal("0")``.  If *value* is a string, it
+   should conform to the decimal numeric string syntax::
+
+      sign           ::=  '+' | '-'
+      digit          ::=  '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
+      indicator      ::=  'e' | 'E'
+      digits         ::=  digit [digit]...
+      decimal-part   ::=  digits '.' [digits] | ['.'] digits
+      exponent-part  ::=  indicator [sign] digits
+      infinity       ::=  'Infinity' | 'Inf'
+      nan            ::=  'NaN' [digits] | 'sNaN' [digits]
+      numeric-value  ::=  decimal-part [exponent-part] | infinity
+      numeric-string ::=  [sign] numeric-value | [sign] nan  
+
+   If *value* is a :class:`tuple`, it should have three components, a sign
+   (:const:`0` for positive or :const:`1` for negative), a :class:`tuple` of
+   digits, and an integer exponent. For example, ``Decimal((0, (1, 4, 1, 4), -3))``
+   returns ``Decimal("1.414")``.
+
+   The *context* precision does not affect how many digits are stored. That is
+   determined exclusively by the number of digits in *value*. For example,
+   ``Decimal("3.00000")`` records all five zeroes even if the context precision is
+   only three.
+
+   The purpose of the *context* argument is determining what to do if *value* is a
+   malformed string.  If the context traps :const:`InvalidOperation`, an exception
+   is raised; otherwise, the constructor returns a new Decimal with the value of
+   :const:`NaN`.
+
+   Once constructed, :class:`Decimal` objects are immutable.
+
+Decimal floating point objects share many properties with the other builtin
+numeric types such as :class:`float` and :class:`int`.  All of the usual math
+operations and special methods apply.  Likewise, decimal objects can be copied,
+pickled, printed, used as dictionary keys, used as set elements, compared,
+sorted, and coerced to another type (such as :class:`float` or :class:`long`).
+
+In addition to the standard numeric properties, decimal floating point objects
+also have a number of specialized methods:
+
+
+.. method:: Decimal.adjusted()
+
+   Return the adjusted exponent after shifting out the coefficient's rightmost
+   digits until only the lead digit remains: ``Decimal("321e+5").adjusted()``
+   returns seven.  Used for determining the position of the most significant digit
+   with respect to the decimal point.
+
+
+.. method:: Decimal.as_tuple()
+
+   Returns a tuple representation of the number: ``(sign, digittuple, exponent)``.
+
+
+.. method:: Decimal.compare(other[, context])
+
+   Compares like :meth:`__cmp__` but returns a decimal instance::
+
+      a or b is a NaN ==> Decimal("NaN")
+      a < b           ==> Decimal("-1")
+      a == b          ==> Decimal("0")
+      a > b           ==> Decimal("1")
+
+
+.. method:: Decimal.max(other[, context])
+
+   Like ``max(self, other)`` except that the context rounding rule is applied
+   before returning and that :const:`NaN` values are either signalled or ignored
+   (depending on the context and whether they are signaling or quiet).
+
+
+.. method:: Decimal.min(other[, context])
+
+   Like ``min(self, other)`` except that the context rounding rule is applied
+   before returning and that :const:`NaN` values are either signalled or ignored
+   (depending on the context and whether they are signaling or quiet).
+
+
+.. method:: Decimal.normalize([context])
+
+   Normalize the number by stripping the rightmost trailing zeroes and converting
+   any result equal to :const:`Decimal("0")` to :const:`Decimal("0e0")`. Used for
+   producing canonical values for members of an equivalence class. For example,
+   ``Decimal("32.100")`` and ``Decimal("0.321000e+2")`` both normalize to the
+   equivalent value ``Decimal("32.1")``.
+
+
+.. method:: Decimal.quantize(exp [, rounding[, context[, watchexp]]])
+
+   Quantize makes the exponent the same as *exp*.  Searches for a rounding method
+   in *rounding*, then in *context*, and then in the current context.
+
+   If *watchexp* is set (default), then an error is returned whenever the resulting
+   exponent is greater than :attr:`Emax` or less than :attr:`Etiny`.
+
+
+.. method:: Decimal.remainder_near(other[, context])
+
+   Computes the modulo as either a positive or negative value depending on which is
+   closest to zero.  For instance, ``Decimal(10).remainder_near(6)`` returns
+   ``Decimal("-2")`` which is closer to zero than ``Decimal("4")``.
+
+   If both are equally close, the one chosen will have the same sign as *self*.
+
+
+.. method:: Decimal.same_quantum(other[, context])
+
+   Test whether self and other have the same exponent or whether both are
+   :const:`NaN`.
+
+
+.. method:: Decimal.sqrt([context])
+
+   Return the square root to full precision.
+
+
+.. method:: Decimal.to_eng_string([context])
+
+   Convert to an engineering-type string.
+
+   Engineering notation has an exponent which is a multiple of 3, so there are up
+   to 3 digits left of the decimal place.  For example, converts
+   ``Decimal('123E+1')`` to ``Decimal("1.23E+3")``
+
+
+.. method:: Decimal.to_integral([rounding[, context]])
+
+   Rounds to the nearest integer without signaling :const:`Inexact` or
+   :const:`Rounded`.  If given, applies *rounding*; otherwise, uses the rounding
+   method in either the supplied *context* or the current context.
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-context:
+
+Context objects
+---------------
+
+Contexts are environments for arithmetic operations.  They govern precision, set
+rules for rounding, determine which signals are treated as exceptions, and limit
+the range for exponents.
+
+Each thread has its own current context which is accessed or changed using the
+:func:`getcontext` and :func:`setcontext` functions:
+
+
+.. function:: getcontext()
+
+   Return the current context for the active thread.
+
+
+.. function:: setcontext(c)
+
+   Set the current context for the active thread to *c*.
+
+Beginning with Python 2.5, you can also use the :keyword:`with` statement and
+the :func:`localcontext` function to temporarily change the active context.
+
+
+.. function:: localcontext([c])
+
+   Return a context manager that will set the current context for the active thread
+   to a copy of *c* on entry to the with-statement and restore the previous context
+   when exiting the with-statement. If no context is specified, a copy of the
+   current context is used.
+
+   .. versionadded:: 2.5
+
+   For example, the following code sets the current decimal precision to 42 places,
+   performs a calculation, and then automatically restores the previous context::
+
+      from __future__ import with_statement
+      from decimal import localcontext
+
+      with localcontext() as ctx:
+          ctx.prec = 42   # Perform a high precision calculation
+          s = calculate_something()
+      s = +s  # Round the final result back to the default precision
+
+New contexts can also be created using the :class:`Context` constructor
+described below. In addition, the module provides three pre-made contexts:
+
+
+.. class:: BasicContext
+
+   This is a standard context defined by the General Decimal Arithmetic
+   Specification.  Precision is set to nine.  Rounding is set to
+   :const:`ROUND_HALF_UP`.  All flags are cleared.  All traps are enabled (treated
+   as exceptions) except :const:`Inexact`, :const:`Rounded`, and
+   :const:`Subnormal`.
+
+   Because many of the traps are enabled, this context is useful for debugging.
+
+
+.. class:: ExtendedContext
+
+   This is a standard context defined by the General Decimal Arithmetic
+   Specification.  Precision is set to nine.  Rounding is set to
+   :const:`ROUND_HALF_EVEN`.  All flags are cleared.  No traps are enabled (so that
+   exceptions are not raised during computations).
+
+   Because the trapped are disabled, this context is useful for applications that
+   prefer to have result value of :const:`NaN` or :const:`Infinity` instead of
+   raising exceptions.  This allows an application to complete a run in the
+   presence of conditions that would otherwise halt the program.
+
+
+.. class:: DefaultContext
+
+   This context is used by the :class:`Context` constructor as a prototype for new
+   contexts.  Changing a field (such a precision) has the effect of changing the
+   default for new contexts creating by the :class:`Context` constructor.
+
+   This context is most useful in multi-threaded environments.  Changing one of the
+   fields before threads are started has the effect of setting system-wide
+   defaults.  Changing the fields after threads have started is not recommended as
+   it would require thread synchronization to prevent race conditions.
+
+   In single threaded environments, it is preferable to not use this context at
+   all.  Instead, simply create contexts explicitly as described below.
+
+   The default values are precision=28, rounding=ROUND_HALF_EVEN, and enabled traps
+   for Overflow, InvalidOperation, and DivisionByZero.
+
+In addition to the three supplied contexts, new contexts can be created with the
+:class:`Context` constructor.
+
+
+.. class:: Context(prec=None, rounding=None, traps=None, flags=None, Emin=None, Emax=None, capitals=1)
+
+   Creates a new context.  If a field is not specified or is :const:`None`, the
+   default values are copied from the :const:`DefaultContext`.  If the *flags*
+   field is not specified or is :const:`None`, all flags are cleared.
+
+   The *prec* field is a positive integer that sets the precision for arithmetic
+   operations in the context.
+
+   The *rounding* option is one of:
+
+   * :const:`ROUND_CEILING` (towards :const:`Infinity`),
+   * :const:`ROUND_DOWN` (towards zero),
+   * :const:`ROUND_FLOOR` (towards :const:`-Infinity`),
+   * :const:`ROUND_HALF_DOWN` (to nearest with ties going towards zero),
+   * :const:`ROUND_HALF_EVEN` (to nearest with ties going to nearest even integer),
+   * :const:`ROUND_HALF_UP` (to nearest with ties going away from zero), or
+   * :const:`ROUND_UP` (away from zero).
+
+   The *traps* and *flags* fields list any signals to be set. Generally, new
+   contexts should only set traps and leave the flags clear.
+
+   The *Emin* and *Emax* fields are integers specifying the outer limits allowable
+   for exponents.
+
+   The *capitals* field is either :const:`0` or :const:`1` (the default). If set to
+   :const:`1`, exponents are printed with a capital :const:`E`; otherwise, a
+   lowercase :const:`e` is used: :const:`Decimal('6.02e+23')`.
+
+The :class:`Context` class defines several general purpose methods as well as a
+large number of methods for doing arithmetic directly in a given context.
+
+
+.. method:: Context.clear_flags()
+
+   Resets all of the flags to :const:`0`.
+
+
+.. method:: Context.copy()
+
+   Return a duplicate of the context.
+
+
+.. method:: Context.create_decimal(num)
+
+   Creates a new Decimal instance from *num* but using *self* as context. Unlike
+   the :class:`Decimal` constructor, the context precision, rounding method, flags,
+   and traps are applied to the conversion.
+
+   This is useful because constants are often given to a greater precision than is
+   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::
+
+      >>> getcontext().prec = 3
+      >>> Decimal("3.4445") + Decimal("1.0023")
+      Decimal("4.45")
+      >>> Decimal("3.4445") + Decimal(0) + Decimal("1.0023")
+      Decimal("4.44")
+
+
+.. method:: Context.Etiny()
+
+   Returns a value equal to ``Emin - prec + 1`` which is the minimum exponent value
+   for subnormal results.  When underflow occurs, the exponent is set to
+   :const:`Etiny`.
+
+
+.. method:: Context.Etop()
+
+   Returns a value equal to ``Emax - prec + 1``.
+
+The usual approach to working with decimals is to create :class:`Decimal`
+instances and then apply arithmetic operations which take place within the
+current context for the active thread.  An alternate approach is to use context
+methods for calculating within a specific context.  The methods are similar to
+those for the :class:`Decimal` class and are only briefly recounted here.
+
+
+.. method:: Context.abs(x)
+
+   Returns the absolute value of *x*.
+
+
+.. method:: Context.add(x, y)
+
+   Return the sum of *x* and *y*.
+
+
+.. method:: Context.compare(x, y)
+
+   Compares values numerically.
+
+   Like :meth:`__cmp__` but returns a decimal instance::
+
+      a or b is a NaN ==> Decimal("NaN")
+      a < b           ==> Decimal("-1")
+      a == b          ==> Decimal("0")
+      a > b           ==> Decimal("1")
+
+
+.. method:: Context.divide(x, y)
+
+   Return *x* divided by *y*.
+
+
+.. method:: Context.divmod(x, y)
+
+   Divides two numbers and returns the integer part of the result.
+
+
+.. method:: Context.max(x, y)
+
+   Compare two values numerically and return the maximum.
+
+   If they are numerically equal then the left-hand operand is chosen as the
+   result.
+
+
+.. method:: Context.min(x, y)
+
+   Compare two values numerically and return the minimum.
+
+   If they are numerically equal then the left-hand operand is chosen as the
+   result.
+
+
+.. method:: Context.minus(x)
+
+   Minus corresponds to the unary prefix minus operator in Python.
+
+
+.. method:: Context.multiply(x, y)
+
+   Return the product of *x* and *y*.
+
+
+.. method:: Context.normalize(x)
+
+   Normalize reduces an operand to its simplest form.
+
+   Essentially a :meth:`plus` operation with all trailing zeros removed from the
+   result.
+
+
+.. method:: Context.plus(x)
+
+   Plus corresponds to the unary prefix plus operator in Python.  This operation
+   applies the context precision and rounding, so it is *not* an identity
+   operation.
+
+
+.. method:: Context.power(x, y[, modulo])
+
+   Return ``x ** y`` to the *modulo* if given.
+
+   The right-hand operand must be a whole number whose integer part (after any
+   exponent has been applied) has no more than 9 digits and whose fractional part
+   (if any) is all zeros before any rounding. The operand may be positive,
+   negative, or zero; if negative, the absolute value of the power is used, and the
+   left-hand operand is inverted (divided into 1) before use.
+
+   If the increased precision needed for the intermediate calculations exceeds the
+   capabilities of the implementation then an :const:`InvalidOperation` condition
+   is signaled.
+
+   If, when raising to a negative power, an underflow occurs during the division
+   into 1, the operation is not halted at that point but continues.
+
+
+.. method:: Context.quantize(x, y)
+
+   Returns a value equal to *x* after rounding and having the exponent of *y*.
+
+   Unlike other operations, if the length of the coefficient after the quantize
+   operation would be greater than precision, then an :const:`InvalidOperation` is
+   signaled. This guarantees that, unless there is an error condition, the
+   quantized exponent is always equal to that of the right-hand operand.
+
+   Also unlike other operations, quantize never signals Underflow, even if the
+   result is subnormal and inexact.
+
+
+.. method:: Context.remainder(x, y)
+
+   Returns the remainder from integer division.
+
+   The sign of the result, if non-zero, is the same as that of the original
+   dividend.
+
+
+.. method:: Context.remainder_near(x, y)
+
+   Computed the modulo as either a positive or negative value depending on which is
+   closest to zero.  For instance, ``Decimal(10).remainder_near(6)`` returns
+   ``Decimal("-2")`` which is closer to zero than ``Decimal("4")``.
+
+   If both are equally close, the one chosen will have the same sign as *self*.
+
+
+.. method:: Context.same_quantum(x, y)
+
+   Test whether *x* and *y* have the same exponent or whether both are
+   :const:`NaN`.
+
+
+.. method:: Context.sqrt(x)
+
+   Return the square root of *x* to full precision.
+
+
+.. method:: Context.subtract(x, y)
+
+   Return the difference between *x* and *y*.
+
+
+.. method:: Context.to_eng_string()
+
+   Convert to engineering-type string.
+
+   Engineering notation has an exponent which is a multiple of 3, so there are up
+   to 3 digits left of the decimal place.  For example, converts
+   ``Decimal('123E+1')`` to ``Decimal("1.23E+3")``
+
+
+.. method:: Context.to_integral(x)
+
+   Rounds to the nearest integer without signaling :const:`Inexact` or
+   :const:`Rounded`.
+
+
+.. method:: Context.to_sci_string(x)
+
+   Converts a number to a string using scientific notation.
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-signals:
+
+Signals
+-------
+
+Signals represent conditions that arise during computation. Each corresponds to
+one context flag and one context trap enabler.
+
+The context flag is incremented whenever the condition is encountered. After the
+computation, flags may be checked for informational purposes (for instance, to
+determine whether a computation was exact). After checking the flags, be sure to
+clear all flags before starting the next computation.
+
+If the context's trap enabler is set for the signal, then the condition causes a
+Python exception to be raised.  For example, if the :class:`DivisionByZero` trap
+is set, then a :exc:`DivisionByZero` exception is raised upon encountering the
+condition.
+
+
+.. class:: Clamped
+
+   Altered an exponent to fit representation constraints.
+
+   Typically, clamping occurs when an exponent falls outside the context's
+   :attr:`Emin` and :attr:`Emax` limits.  If possible, the exponent is reduced to
+   fit by adding zeroes to the coefficient.
+
+
+.. class:: DecimalException
+
+   Base class for other signals and a subclass of :exc:`ArithmeticError`.
+
+
+.. class:: DivisionByZero
+
+   Signals the division of a non-infinite number by zero.
+
+   Can occur with division, modulo division, or when raising a number to a negative
+   power.  If this signal is not trapped, returns :const:`Infinity` or
+   :const:`-Infinity` with the sign determined by the inputs to the calculation.
+
+
+.. class:: Inexact
+
+   Indicates that rounding occurred and the result is not exact.
+
+   Signals when non-zero digits were discarded during rounding. The rounded result
+   is returned.  The signal flag or trap is used to detect when results are
+   inexact.
+
+
+.. class:: InvalidOperation
+
+   An invalid operation was performed.
+
+   Indicates that an operation was requested that does not make sense. If not
+   trapped, returns :const:`NaN`.  Possible causes include::
+
+      Infinity - Infinity
+      0 * Infinity
+      Infinity / Infinity
+      x % 0
+      Infinity % x
+      x._rescale( non-integer )
+      sqrt(-x) and x > 0
+      0 ** 0
+      x ** (non-integer)
+      x ** Infinity      
+
+
+.. class:: Overflow
+
+   Numerical overflow.
+
+   Indicates the exponent is larger than :attr:`Emax` after rounding has occurred.
+   If not trapped, the result depends on the rounding mode, either pulling inward
+   to the largest representable finite number or rounding outward to
+   :const:`Infinity`.  In either case, :class:`Inexact` and :class:`Rounded` are
+   also signaled.
+
+
+.. class:: Rounded
+
+   Rounding occurred though possibly no information was lost.
+
+   Signaled whenever rounding discards digits; even if those digits are zero (such
+   as rounding :const:`5.00` to :const:`5.0`).   If not trapped, returns the result
+   unchanged.  This signal is used to detect loss of significant digits.
+
+
+.. class:: Subnormal
+
+   Exponent was lower than :attr:`Emin` prior to rounding.
+
+   Occurs when an operation result is subnormal (the exponent is too small). If not
+   trapped, returns the result unchanged.
+
+
+.. class:: Underflow
+
+   Numerical underflow with result rounded to zero.
+
+   Occurs when a subnormal result is pushed to zero by rounding. :class:`Inexact`
+   and :class:`Subnormal` are also signaled.
+
+The following table summarizes the hierarchy of signals::
+
+   exceptions.ArithmeticError(exceptions.Exception)
+       DecimalException
+           Clamped
+           DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
+           Inexact
+               Overflow(Inexact, Rounded)
+               Underflow(Inexact, Rounded, Subnormal)
+           InvalidOperation
+           Rounded
+           Subnormal
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-notes:
+
+Floating Point Notes
+--------------------
+
+
+Mitigating round-off error with increased precision
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The use of decimal floating point eliminates decimal representation error
+(making it possible to represent :const:`0.1` exactly); however, some operations
+can still incur round-off error when non-zero digits exceed the fixed precision.
+
+The effects of round-off error can be amplified by the addition or subtraction
+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::
+
+   # Examples from Seminumerical Algorithms, Section 4.2.2.
+   >>> from decimal import Decimal, getcontext
+   >>> getcontext().prec = 8
+
+   >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
+   >>> (u + v) + w
+   Decimal("9.5111111")
+   >>> u + (v + w)
+   Decimal("10")
+
+   >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
+   >>> (u*v) + (u*w)
+   Decimal("0.01")
+   >>> u * (v+w)
+   Decimal("0.0060000")
+
+The :mod:`decimal` module makes it possible to restore the identities by
+expanding the precision sufficiently to avoid loss of significance::
+
+   >>> getcontext().prec = 20
+   >>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
+   >>> (u + v) + w
+   Decimal("9.51111111")
+   >>> u + (v + w)
+   Decimal("9.51111111")
+   >>> 
+   >>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
+   >>> (u*v) + (u*w)
+   Decimal("0.0060000")
+   >>> u * (v+w)
+   Decimal("0.0060000")
+
+
+Special values
+^^^^^^^^^^^^^^
+
+The number system for the :mod:`decimal` module provides special values
+including :const:`NaN`, :const:`sNaN`, :const:`-Infinity`, :const:`Infinity`,
+and two zeroes, :const:`+0` and :const:`-0`.
+
+Infinities can be constructed directly with:  ``Decimal('Infinity')``. Also,
+they can arise from dividing by zero when the :exc:`DivisionByZero` signal is
+not trapped.  Likewise, when the :exc:`Overflow` signal is not trapped, infinity
+can result from rounding beyond the limits of the largest representable number.
+
+The infinities are signed (affine) and can be used in arithmetic operations
+where they get treated as very large, indeterminate numbers.  For instance,
+adding a constant to infinity gives another infinite result.
+
+Some operations are indeterminate and return :const:`NaN`, or if the
+:exc:`InvalidOperation` signal is trapped, raise an exception.  For example,
+``0/0`` returns :const:`NaN` which means "not a number".  This variety of
+:const:`NaN` is quiet and, once created, will flow through other computations
+always resulting in another :const:`NaN`.  This behavior can be useful for a
+series of computations that occasionally have missing inputs --- it allows the
+calculation to proceed while flagging specific results as invalid.
+
+A variant is :const:`sNaN` which signals rather than remaining quiet after every
+operation.  This is a useful return value when an invalid result needs to
+interrupt a calculation for special handling.
+
+The signed zeros can result from calculations that underflow. They keep the sign
+that would have resulted if the calculation had been carried out to greater
+precision.  Since their magnitude is zero, both positive and negative zeros are
+treated as equal and their sign is informational.
+
+In addition to the two signed zeros which are distinct yet equal, there are
+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::
+
+   >>> 1 / Decimal('Infinity')
+   Decimal("0E-1000000026")
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-threads:
+
+Working with threads
+--------------------
+
+The :func:`getcontext` function accesses a different :class:`Context` object for
+each thread.  Having separate thread contexts means that threads may make
+changes (such as ``getcontext.prec=10``) without interfering with other threads.
+
+Likewise, the :func:`setcontext` function automatically assigns its target to
+the current thread.
+
+If :func:`setcontext` has not been called before :func:`getcontext`, then
+:func:`getcontext` will automatically create a new context for use in the
+current thread.
+
+The new context is copied from a prototype context called *DefaultContext*. To
+control the defaults so that each thread will use the same values throughout the
+application, directly modify the *DefaultContext* object. This should be done
+*before* any threads are started so that there won't be a race condition between
+threads calling :func:`getcontext`. For example::
+
+   # Set applicationwide defaults for all threads about to be launched
+   DefaultContext.prec = 12
+   DefaultContext.rounding = ROUND_DOWN
+   DefaultContext.traps = ExtendedContext.traps.copy()
+   DefaultContext.traps[InvalidOperation] = 1
+   setcontext(DefaultContext)
+
+   # Afterwards, the threads can be started
+   t1.start()
+   t2.start()
+   t3.start()
+    . . .
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-recipes:
+
+Recipes
+-------
+
+Here are a few recipes that serve as utility functions and that demonstrate ways
+to work with the :class:`Decimal` class::
+
+   def moneyfmt(value, places=2, curr='', sep=',', dp='.',
+                pos='', neg='-', trailneg=''):
+       """Convert Decimal to a money formatted string.
+
+       places:  required number of places after the decimal point
+       curr:    optional currency symbol before the sign (may be blank)
+       sep:     optional grouping separator (comma, period, space, or blank)
+       dp:      decimal point indicator (comma or period)
+                only specify as blank when places is zero
+       pos:     optional sign for positive numbers: '+', space or blank
+       neg:     optional sign for negative numbers: '-', '(', space or blank
+       trailneg:optional trailing minus indicator:  '-', ')', space or blank
+
+       >>> d = Decimal('-1234567.8901')
+       >>> moneyfmt(d, curr='$')
+       '-$1,234,567.89'
+       >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')
+       '1.234.568-'
+       >>> moneyfmt(d, curr='$', neg='(', trailneg=')')
+       '($1,234,567.89)'
+       >>> moneyfmt(Decimal(123456789), sep=' ')
+       '123 456 789.00'
+       >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')
+       '<.02>'
+
+       """
+       q = Decimal((0, (1,), -places))    # 2 places --> '0.01'
+       sign, digits, exp = value.quantize(q).as_tuple()
+       assert exp == -places    
+       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(dp)
+       i = 0
+       while digits:
+           build(next())
+           i += 1
+           if i == 3 and digits:
+               i = 0
+               build(sep)
+       build(curr)
+       if sign:
+           build(neg)
+       else:
+           build(pos)
+       result.reverse()
+       return ''.join(result)
+
+   def pi():
+       """Compute Pi to the current precision.
+
+       >>> print pi()
+       3.141592653589793238462643383
+
+       """
+       getcontext().prec += 2  # extra digits for intermediate steps
+       three = Decimal(3)      # substitute "three=3.0" for regular floats
+       lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24
+       while s != lasts:
+           lasts = s
+           n, na = n+na, na+8
+           d, da = d+da, da+32
+           t = (t * n) / d
+           s += t
+       getcontext().prec -= 2
+       return +s               # unary plus applies the new precision
+
+   def exp(x):
+       """Return e raised to the power of x.  Result type matches input type.
+
+       >>> print exp(Decimal(1))
+       2.718281828459045235360287471
+       >>> print exp(Decimal(2))
+       7.389056098930650227230427461
+       >>> print exp(2.0)
+       7.38905609893
+       >>> print exp(2+0j)
+       (7.38905609893+0j)
+
+       """
+       getcontext().prec += 2
+       i, lasts, s, fact, num = 0, 0, 1, 1, 1
+       while s != lasts:
+           lasts = s    
+           i += 1
+           fact *= i
+           num *= x     
+           s += num / fact   
+       getcontext().prec -= 2        
+       return +s
+
+   def cos(x):
+       """Return the cosine of x as measured in radians.
+
+       >>> print cos(Decimal('0.5'))
+       0.8775825618903727161162815826
+       >>> print cos(0.5)
+       0.87758256189
+       >>> print cos(0.5+0j)
+       (0.87758256189+0j)
+
+       """
+       getcontext().prec += 2
+       i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1
+       while s != lasts:
+           lasts = s    
+           i += 2
+           fact *= i * (i-1)
+           num *= x * x
+           sign *= -1
+           s += num / fact * sign 
+       getcontext().prec -= 2        
+       return +s
+
+   def sin(x):
+       """Return the sine of x as measured in radians.
+
+       >>> print sin(Decimal('0.5'))
+       0.4794255386042030002732879352
+       >>> print sin(0.5)
+       0.479425538604
+       >>> print sin(0.5+0j)
+       (0.479425538604+0j)
+
+       """
+       getcontext().prec += 2
+       i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1
+       while s != lasts:
+           lasts = s    
+           i += 2
+           fact *= i * (i-1)
+           num *= x * x
+           sign *= -1
+           s += num / fact * sign 
+       getcontext().prec -= 2        
+       return +s
+
+
+.. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+.. _decimal-faq:
+
+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::
+
+   >>> D = decimal.Decimal
+   >>> D('1.23') + D('3.45')
+   Decimal("4.68")
+
+Q. In a fixed-point application with two decimal places, some inputs have many
+places and need to be rounded.  Others are not supposed to have excess digits
+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::
+
+   >>> TWOPLACES = Decimal(10) ** -2       # same as Decimal('0.01')
+
+   >>> # Round to two places
+   >>> Decimal("3.214").quantize(TWOPLACES)
+   Decimal("3.21")
+
+   >>> # Validate that a number does not exceed two places 
+   >>> Decimal("3.21").quantize(TWOPLACES, context=Context(traps=[Inexact]))
+   Decimal("3.21")
+
+   >>> Decimal("3.214").quantize(TWOPLACES, context=Context(traps=[Inexact]))
+   Traceback (most recent call last):
+      ...
+   Inexact: Changed in rounding
+
+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.
+
+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
+various precisions. Is there a way to transform them to a single recognizable
+canonical value?
+
+A. The :meth:`normalize` method maps all equivalent values to a single
+representative::
+
+   >>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
+   >>> [v.normalize() for v in values]
+   [Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2")]
+
+Q. Some decimal values always print with exponential notation.  Is there a way
+to get a non-exponential representation?
+
+A. For some values, exponential notation is the only way to express the number
+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.
+
+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
+Decimal.  An exact conversion may take more precision than intuition would
+suggest, so trapping :const:`Inexact` will signal a need for more precision::
+
+   def floatToDecimal(f):
+       "Convert a floating point number to a Decimal with no loss of information"
+       # Transform (exactly) a float to a mantissa (0.5 <= abs(m) < 1.0) and an
+       # exponent.  Double the mantissa until it is an integer.  Use the integer
+       # mantissa and exponent to compute an equivalent Decimal.  If this cannot
+       # be done exactly, then retry with more precision.
+
+       mantissa, exponent = math.frexp(f)
+       while mantissa != int(mantissa):
+           mantissa *= 2.0
+           exponent -= 1
+       mantissa = int(mantissa)
+
+       oldcontext = getcontext()
+       setcontext(Context(traps=[Inexact]))
+       try:
+           while True:
+               try:
+                  return mantissa * Decimal(2) ** exponent
+               except Inexact:
+                   getcontext().prec += 1
+       finally:
+           setcontext(oldcontext)
+
+Q. Why isn't the :func:`floatToDecimal` routine included in the module?
+
+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::
+
+   >>> floatToDecimal(1.1)
+   Decimal("1.100000000000000088817841970012523233890533447265625")
+
+Q. Within a complex calculation, how can I make sure that I haven't gotten a
+spurious result because of insufficient precision or rounding anomalies.
+
+A. The decimal module makes it easy to test results.  A best practice is to
+re-run calculations using greater precision and with various rounding modes.
+Widely differing results indicate insufficient precision, rounding mode issues,
+ill-conditioned inputs, or a numerically unstable algorithm.
+
+Q. I noticed that context precision is applied to the results of operations but
+not to the inputs.  Is there anything to watch out for when mixing values of
+different precisions?
+
+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::
+
+   >>> getcontext().prec = 3
+   >>> Decimal('3.104') + D('2.104')
+   Decimal("5.21")
+   >>> Decimal('3.104') + D('0.000') + D('2.104')
+   Decimal("5.20")
+
+The solution is either to increase precision or to force rounding of inputs
+using the unary plus operation::
+
+   >>> 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::
+
+   >>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
+   Decimal("1.2345")
+