Merged revisions 62490 via svnmerge from

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

........
  r62490 | benjamin.peterson | 2008-04-24 20:29:10 -0500 (Thu, 24 Apr 2008) | 2 lines

  reformat some documentation of classes so methods and attributes are under the class directive
........

1 files changed, 361 insertions, 411 deletions

diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst
index 6f4821b..b7dd32f 100644
--- a/Doc/library/decimal.rst
+++ b/Doc/library/decimal.rst
@@ -340,442 +340,394 @@ Decimal objects
 
    Once constructed, :class:`Decimal` objects are immutable.
 
+   Decimal floating point objects share many properties with the other built-in
+   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`).
 
-Decimal floating point objects share many properties with the other built-in
-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 converted to another type (such as :class:`float` or :class:`int`).
+   In addition to the standard numeric properties, decimal floating point
+   objects also have a number of specialized methods:
 
-In addition to the standard numeric properties, decimal floating point objects
-also have a number of specialized methods:
 
+   .. method:: adjusted()
 
-.. 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.
 
-   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:: as_tuple()
 
-.. method:: Decimal.as_tuple()
+      Return a :term:`named tuple` representation of the number:
+      ``DecimalTuple(sign, digits, exponent)``.
 
-   Return a :term:`named tuple` representation of the number:
-   ``DecimalTuple(sign, digits, exponent)``.
 
+   .. method:: canonical()
 
-.. method:: Decimal.canonical()
+      Return the canonical encoding of the argument.  Currently, the encoding of
+      a :class:`Decimal` instance is always canonical, so this operation returns
+      its argument unchanged.
 
-   Return the canonical encoding of the argument.  Currently, the
-   encoding of a :class:`Decimal` instance is always canonical, so
-   this operation returns its argument unchanged.
+   .. method:: compare(other[, context])
 
+      Compare the values of two Decimal instances.  This operation behaves in
+      the same way as the usual comparison method :meth:`__cmp__`, except that
+      :meth:`compare` returns a Decimal instance rather than an integer, and if
+      either operand is a NaN then the result is a NaN::
 
-.. method:: Decimal.compare(other[, context])
+         a or b is a NaN ==> Decimal('NaN')
+         a < b           ==> Decimal('-1')
+         a == b          ==> Decimal('0')
+         a > b           ==> Decimal('1')
 
-   Compare the values of two Decimal instances.  This operation
-   behaves in the same way as the usual comparison method
-   :meth:`__cmp__`, except that :meth:`compare` returns a Decimal
-   instance rather than an integer, and if either operand is a NaN
-   then the result is a NaN::
+   .. method:: compare_signal(other[, context])
 
-      a or b is a NaN ==> Decimal('NaN')
-      a < b           ==> Decimal('-1')
-      a == b          ==> Decimal('0')
-      a > b           ==> Decimal('1')
+      This operation is identical to the :meth:`compare` method, except that all
+      NaNs signal.  That is, if neither operand is a signaling NaN then any
+      quiet NaN operand is treated as though it were a signaling NaN.
 
-.. method:: Decimal.compare_signal(other[, context])
+   .. method:: compare_total(other)
 
-   This operation is identical to the :meth:`compare` method, except
-   that all NaNs signal.  That is, if neither operand is a signaling
-   NaN then any quiet NaN operand is treated as though it were a
-   signaling NaN.
+      Compare two operands using their abstract representation rather than their
+      numerical value.  Similar to the :meth:`compare` method, 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:
 
+         >>> Decimal('12.0').compare_total(Decimal('12'))
+         Decimal('-1')
 
-.. method:: Decimal.compare_total(other)
+      Quiet and signaling NaNs are also included in the total ordering.  The
+      result of this function is ``Decimal('0')`` if both operands have the same
+      representation, ``Decimal('-1')`` if the first operand is lower in the
+      total order than the second, and ``Decimal('1')`` if the first operand is
+      higher in the total order than the second operand.  See the specification
+      for details of the total order.
 
-   Compare two operands using their abstract representation rather
-   than their numerical value.  Similar to the :meth:`compare` method,
-   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:
-   
-      >>> Decimal('12.0').compare_total(Decimal('12'))
-      Decimal('-1')
+   .. method:: compare_total_mag(other)
 
-   Quiet and signaling NaNs are also included in the total ordering.
-   The result of this function is ``Decimal('0')`` if both operands
-   have the same representation, ``Decimal('-1')`` if the first
-   operand is lower in the total order than the second, and
-   ``Decimal('1')`` if the first operand is higher in the total order
-   than the second operand.  See the specification for details of the
-   total order.
+      Compare two operands using their abstract representation rather than their
+      value as in :meth:`compare_total`, but ignoring the sign of each operand.
+      ``x.compare_total_mag(y)`` is equivalent to
+      ``x.copy_abs().compare_total(y.copy_abs())``.
 
+   .. method:: copy_abs()
 
-.. method:: Decimal.compare_total_mag(other)
+      Return the absolute value of the argument.  This operation is unaffected
+      by the context and is quiet: no flags are changed and no rounding is
+      performed.
 
-   Compare two operands using their abstract representation rather
-   than their value as in :meth:`compare_total`, but ignoring the sign
-   of each operand.  ``x.compare_total_mag(y)`` is equivalent to
-   ``x.copy_abs().compare_total(y.copy_abs())``.
+   .. method:: copy_negate()
 
+      Return the negation of the argument.  This operation is unaffected by the
+      context and is quiet: no flags are changed and no rounding is performed.
 
-.. method:: Decimal.copy_abs()
+   .. method:: copy_sign(other)
 
-   Return the absolute value of the argument.  This operation is
-   unaffected by the context and is quiet: no flags are changed and no
-   rounding is performed.
+      Return a copy of the first operand with the sign set to be the same as the
+      sign of the second operand.  For example:
 
+         >>> Decimal('2.3').copy_sign(Decimal('-1.5'))
+         Decimal('-2.3')
 
-.. method:: Decimal.copy_negate()
+      This operation is unaffected by the context and is quiet: no flags are
+      changed and no rounding is performed.
 
-   Return the negation of the argument.  This operation is unaffected
-   by the context and is quiet: no flags are changed and no rounding
-   is performed.
+   .. method:: exp([context])
 
+      Return the value of the (natural) exponential function ``e**x`` at the
+      given number.  The result is correctly rounded using the
+      :const:`ROUND_HALF_EVEN` rounding mode.
 
-.. method:: Decimal.copy_sign(other)
+      >>> Decimal(1).exp()
+      Decimal('2.718281828459045235360287471')
+      >>> Decimal(321).exp()
+      Decimal('2.561702493119680037517373933E+139')
 
-   Return a copy of the first operand with the sign set to be the
-   same as the sign of the second operand.  For example:
+   .. method:: fma(other, third[, context])
 
-      >>> Decimal('2.3').copy_sign(Decimal('-1.5'))
-      Decimal('-2.3')
-   
-   This operation is unaffected by the context and is quiet: no flags
-   are changed and no rounding is performed.
+      Fused multiply-add.  Return self*other+third with no rounding of the
+      intermediate product self*other.
 
+      >>> Decimal(2).fma(3, 5)
+      Decimal('11')
 
-.. method:: Decimal.exp([context])
+   .. method:: is_canonical()
 
-   Return the value of the (natural) exponential function ``e**x`` at the
-   given number.  The result is correctly rounded using the
-   :const:`ROUND_HALF_EVEN` rounding mode.
+      Return :const:`True` if the argument is canonical and :const:`False`
+      otherwise.  Currently, a :class:`Decimal` instance is always canonical, so
+      this operation always returns :const:`True`.
 
-   >>> Decimal(1).exp()
-   Decimal('2.718281828459045235360287471')
-   >>> Decimal(321).exp()
-   Decimal('2.561702493119680037517373933E+139')
-
-
-.. method:: Decimal.fma(other, third[, context])
-
-   Fused multiply-add.  Return self*other+third with no rounding of
-   the intermediate product self*other.
-
-   >>> Decimal(2).fma(3, 5)
-   Decimal('11')
-
-
-.. method:: Decimal.is_canonical()
-
-   Return :const:`True` if the argument is canonical and
-   :const:`False` otherwise.  Currently, a :class:`Decimal` instance
-   is always canonical, so this operation always returns
-   :const:`True`.
-
-
-.. method:: is_finite()
+   .. method:: is_finite()
 
-   Return :const:`True` if the argument is a finite number, and
-   :const:`False` if the argument is an infinity or a NaN.
+      Return :const:`True` if the argument is a finite number, and
+      :const:`False` if the argument is an infinity or a NaN.
 
+   .. method:: is_infinite()
 
-.. method:: is_infinite()
+      Return :const:`True` if the argument is either positive or negative
+      infinity and :const:`False` otherwise.
 
-   Return :const:`True` if the argument is either positive or
-   negative infinity and :const:`False` otherwise.
+   .. method:: is_nan()
 
+      Return :const:`True` if the argument is a (quiet or signaling) NaN and
+      :const:`False` otherwise.
 
-.. method:: is_nan()
+   .. method:: is_normal()
 
-   Return :const:`True` if the argument is a (quiet or signaling)
-   NaN and :const:`False` otherwise.
+      Return :const:`True` if the argument is a *normal* finite number.  Return
+      :const:`False` if the argument is zero, subnormal, infinite or a NaN.
 
+   .. method:: is_qnan()
 
-.. method:: is_normal()
+      Return :const:`True` if the argument is a quiet NaN, and
+      :const:`False` otherwise.
 
-   Return :const:`True` if the argument is a *normal* finite number.
-   Return :const:`False` if the argument is zero, subnormal, infinite
-   or a NaN.
+   .. method:: is_signed()
 
+      Return :const:`True` if the argument has a negative sign and
+      :const:`False` otherwise.  Note that zeros and NaNs can both carry signs.
 
-.. method:: is_qnan()
+   .. method:: is_snan()
 
-   Return :const:`True` if the argument is a quiet NaN, and
-   :const:`False` otherwise.
+      Return :const:`True` if the argument is a signaling NaN and :const:`False`
+      otherwise.
 
+   .. method:: is_subnormal()
 
-.. method:: is_signed()
+      Return :const:`True` if the argument is subnormal, and :const:`False`
+      otherwise.
 
-   Return :const:`True` if the argument has a negative sign and
-   :const:`False` otherwise.  Note that zeros and NaNs can both carry
-   signs.
+   .. method:: is_zero()
 
+      Return :const:`True` if the argument is a (positive or negative) zero and
+      :const:`False` otherwise.
 
-.. method:: is_snan()
+   .. method:: ln([context])
 
-   Return :const:`True` if the argument is a signaling NaN and
-   :const:`False` otherwise.
+      Return the natural (base e) logarithm of the operand.  The result is
+      correctly rounded using the :const:`ROUND_HALF_EVEN` rounding mode.
 
+   .. method:: log10([context])
 
-.. method:: is_subnormal()
+      Return the base ten logarithm of the operand.  The result is correctly
+      rounded using the :const:`ROUND_HALF_EVEN` rounding mode.
 
-   Return :const:`True` if the argument is subnormal, and
-   :const:`False` otherwise.
+   .. method:: logb([context])
 
+      For a nonzero number, return the adjusted exponent of its operand as a
+      :class:`Decimal` instance.  If the operand is a zero then
+      ``Decimal('-Infinity')`` is returned and the :const:`DivisionByZero` flag
+      is raised.  If the operand is an infinity then ``Decimal('Infinity')`` is
+      returned.
 
-.. method:: is_zero()
+   .. method:: logical_and(other[, context])
 
-   Return :const:`True` if the argument is a (positive or negative)
-   zero and :const:`False` otherwise.
+      :meth:`logical_and` is a logical operation which takes two *logical
+      operands* (see :ref:`logical_operands_label`).  The result is the
+      digit-wise ``and`` of the two operands.
 
+   .. method:: logical_invert(other[, context])
 
-.. method:: Decimal.ln([context])
+      :meth:`logical_invert` is a logical operation.  The argument must
+      be a *logical operand* (see :ref:`logical_operands_label`).  The
+      result is the digit-wise inversion of the operand.
 
-   Return the natural (base e) logarithm of the operand.  The result
-   is correctly rounded using the :const:`ROUND_HALF_EVEN` rounding
-   mode.
+   .. method:: logical_or(other[, context])
 
+      :meth:`logical_or` is a logical operation which takes two *logical
+      operands* (see :ref:`logical_operands_label`).  The result is the
+      digit-wise ``or`` of the two operands.
 
-.. method:: Decimal.log10([context])
+   .. method:: logical_xor(other[, context])
 
-   Return the base ten logarithm of the operand.  The result is
-   correctly rounded using the :const:`ROUND_HALF_EVEN` rounding mode.
+      :meth:`logical_xor` is a logical operation which takes two *logical
+      operands* (see :ref:`logical_operands_label`).  The result is the
+      digit-wise exclusive or of the two operands.
 
+   .. method:: max(other[, context])
 
-.. method:: Decimal.logb([context])
+      Like ``max(self, other)`` except that the context rounding rule is applied
+      before returning and that :const:`NaN` values are either signaled or
+      ignored (depending on the context and whether they are signaling or
+      quiet).
 
-   For a nonzero number, return the adjusted exponent of its operand
-   as a :class:`Decimal` instance.  If the operand is a zero then
-   ``Decimal('-Infinity')`` is returned and the
-   :const:`DivisionByZero` flag is raised.  If the operand is an
-   infinity then ``Decimal('Infinity')`` is returned.
+   .. method:: max_mag(other[, context])
 
+      Similar to the :meth:`max` method, but the comparison is done using the
+      absolute values of the operands.
 
-.. method:: Decimal.logical_and(other[, context])
+   .. method:: min(other[, context])
 
-   :meth:`logical_and` is a logical operation which takes two
-   *logical operands* (see :ref:`logical_operands_label`).  The result
-   is the digit-wise ``and`` of the two operands.
+      Like ``min(self, other)`` except that the context rounding rule is applied
+      before returning and that :const:`NaN` values are either signaled or
+      ignored (depending on the context and whether they are signaling or
+      quiet).
 
+   .. method:: min_mag(other[, context])
 
-.. method:: Decimal.logical_invert(other[, context])
+      Similar to the :meth:`min` method, but the comparison is done using the
+      absolute values of the operands.
 
-   :meth:`logical_invert` is a logical operation.  The argument must
-   be a *logical operand* (see :ref:`logical_operands_label`).  The
-   result is the digit-wise inversion of the operand.
+   .. method:: next_minus([context])
 
+      Return the largest number representable in the given context (or in the
+      current thread's context if no context is given) that is smaller than the
+      given operand.
 
-.. method:: Decimal.logical_or(other[, context])
+   .. method:: next_plus([context])
 
-   :meth:`logical_or` is a logical operation which takes two *logical
-   operands* (see :ref:`logical_operands_label`).  The result is the
-   digit-wise ``or`` of the two operands.
+      Return the smallest number representable in the given context (or in the
+      current thread's context if no context is given) that is larger than the
+      given operand.
 
+   .. method:: next_toward(other[, context])
 
-.. method:: Decimal.logical_xor(other[, context])
+      If the two operands are unequal, return the number closest to the first
+      operand in the direction of the second operand.  If both operands are
+      numerically equal, return a copy of the first operand with the sign set to
+      be the same as the sign of the second operand.
 
-   :meth:`logical_xor` is a logical operation which takes two
-   *logical operands* (see :ref:`logical_operands_label`).  The result
-   is the digit-wise exclusive or of the two operands.
+   .. method:: normalize([context])
 
+      Normalize the number by stripping the rightmost trailing zeros 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.max(other[, context])
+   .. method:: number_class([context])
 
-   Like ``max(self, other)`` except that the context rounding rule is applied
-   before returning and that :const:`NaN` values are either signaled or ignored
-   (depending on the context and whether they are signaling or quiet).
+      Return a string describing the *class* of the operand.  The returned value
+      is one of the following ten strings.
 
+      * ``"-Infinity"``, indicating that the operand is negative infinity.
+      * ``"-Normal"``, indicating that the operand is a negative normal number.
+      * ``"-Subnormal"``, indicating that the operand is negative and subnormal.
+      * ``"-Zero"``, indicating that the operand is a negative zero.
+      * ``"+Zero"``, indicating that the operand is a positive zero.
+      * ``"+Subnormal"``, indicating that the operand is positive and subnormal.
+      * ``"+Normal"``, indicating that the operand is a positive normal number.
+      * ``"+Infinity"``, indicating that the operand is positive infinity.
+      * ``"NaN"``, indicating that the operand is a quiet NaN (Not a Number).
+      * ``"sNaN"``, indicating that the operand is a signaling NaN.
 
-.. method:: Decimal.max_mag(other[, context])
+   .. method:: quantize(exp[, rounding[, context[, watchexp]]])
 
-   Similar to the :meth:`max` method, but the comparison is done using
-   the absolute values of the operands.
+      Return a value equal to the first operand after rounding and having the
+      exponent of the second operand.
 
+      >>> Decimal('1.41421356').quantize(Decimal('1.000'))
+      Decimal('1.414')
 
-.. method:: Decimal.min(other[, context])
+      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.
 
-   Like ``min(self, other)`` except that the context rounding rule is applied
-   before returning and that :const:`NaN` values are either signaled or ignored
-   (depending on the context and whether they are signaling or quiet).
+      Also unlike other operations, quantize never signals Underflow, even if
+      the result is subnormal and inexact.
 
-.. method:: Decimal.min_mag(other[, context])
+      If the exponent of the second operand is larger than that of the first
+      then rounding may be necessary.  In this case, the rounding mode is
+      determined by the ``rounding`` argument if given, else by the given
+      ``context`` argument; if neither argument is given the rounding mode of
+      the current thread's context is used.
 
-   Similar to the :meth:`min` method, but the comparison is done using
-   the absolute values of the operands.
+      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:: radix()
 
-.. method:: Decimal.next_minus([context])
+      Return ``Decimal(10)``, the radix (base) in which the :class:`Decimal`
+      class does all its arithmetic.  Included for compatibility with the
+      specification.
 
-   Return the largest number representable in the given context (or
-   in the current thread's context if no context is given) that is smaller
-   than the given operand.
+   .. method:: remainder_near(other[, context])
 
+      Compute 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')``.
 
-.. method:: Decimal.next_plus([context])
+      If both are equally close, the one chosen will have the same sign as
+      *self*.
 
-   Return the smallest number representable in the given context (or
-   in the current thread's context if no context is given) that is
-   larger than the given operand.
+   .. method:: rotate(other[, context])
 
+      Return the result of rotating the digits of the first operand by an amount
+      specified by the second operand.  The second operand must be an integer in
+      the range -precision through precision.  The absolute value of the second
+      operand gives the number of places to rotate.  If the second operand is
+      positive then rotation is to the left; otherwise rotation is to the right.
+      The coefficient of the first operand is padded on the left with zeros to
+      length precision if necessary.  The sign and exponent of the first operand
+      are unchanged.
 
-.. method:: Decimal.next_toward(other[, context])
+   .. method:: same_quantum(other[, context])
 
-   If the two operands are unequal, return the number closest to the
-   first operand in the direction of the second operand.  If both
-   operands are numerically equal, return a copy of the first operand
-   with the sign set to be the same as the sign of the second operand.
+      Test whether self and other have the same exponent or whether both are
+      :const:`NaN`.
 
+   .. method:: scaleb(other[, context])
 
-.. method:: Decimal.normalize([context])
+      Return the first operand with exponent adjusted by the second.
+      Equivalently, return the first operand multiplied by ``10**other``.  The
+      second operand must be an integer.
 
-   Normalize the number by stripping the rightmost trailing zeros 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:: shift(other[, context])
 
+      Return the result of shifting the digits of the first operand by an amount
+      specified by the second operand.  The second operand must be an integer in
+      the range -precision through precision.  The absolute value of the second
+      operand gives the number of places to shift.  If the second operand is
+      positive then the shift is to the left; otherwise the shift is to the
+      right.  Digits shifted into the coefficient are zeros.  The sign and
+      exponent of the first operand are unchanged.
 
-.. method:: Decimal.number_class([context])
+   .. method:: sqrt([context])
 
-   Return a string describing the *class* of the operand.  The
-   returned value is one of the following ten strings.
+      Return the square root of the argument to full precision.
 
-   * ``"-Infinity"``, indicating that the operand is negative infinity.
-   * ``"-Normal"``, indicating that the operand is a negative normal number.
-   * ``"-Subnormal"``, indicating that the operand is negative and subnormal.
-   * ``"-Zero"``, indicating that the operand is a negative zero.
-   * ``"+Zero"``, indicating that the operand is a positive zero.
-   * ``"+Subnormal"``, indicating that the operand is positive and subnormal.
-   * ``"+Normal"``, indicating that the operand is a positive normal number.
-   * ``"+Infinity"``, indicating that the operand is positive infinity.
-   * ``"NaN"``, indicating that the operand is a quiet NaN (Not a Number).
-   * ``"sNaN"``, indicating that the operand is a signaling NaN.
 
+   .. method:: to_eng_string([context])
 
-.. method:: Decimal.quantize(exp[, rounding[, context[, watchexp]]])
+      Convert to an engineering-type string.
 
-   Return a value equal to the first operand after rounding and
-   having the exponent of the second operand.
+      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')``
 
-   >>> Decimal('1.41421356').quantize(Decimal('1.000'))
-   Decimal('1.414')
+   .. method:: to_integral([rounding[, context]])
 
-   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.
+      Identical to the :meth:`to_integral_value` method.  The ``to_integral``
+      name has been kept for compatibility with older versions.
 
-   Also unlike other operations, quantize never signals Underflow,
-   even if the result is subnormal and inexact.
+   .. method:: to_integral_exact([rounding[, context]])
 
-   If the exponent of the second operand is larger than that of the
-   first then rounding may be necessary.  In this case, the rounding
-   mode is determined by the ``rounding`` argument if given, else by
-   the given ``context`` argument; if neither argument is given the
-   rounding mode of the current thread's context is used.
+      Round to the nearest integer, signaling :const:`Inexact` or
+      :const:`Rounded` as appropriate if rounding occurs.  The rounding mode is
+      determined by the ``rounding`` parameter if given, else by the given
+      ``context``.  If neither parameter is given then the rounding mode of the
+      current context is used.
 
-   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:: to_integral_value([rounding[, context]])
 
-.. method:: Decimal.radix()
-
-   Return ``Decimal(10)``, the radix (base) in which the
-   :class:`Decimal` class does all its arithmetic.  Included for
-   compatibility with the specification.
-
-
-.. method:: Decimal.remainder_near(other[, context])
-
-   Compute 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.rotate(other[, context])
-
-   Return the result of rotating the digits of the first operand by
-   an amount specified by the second operand.  The second operand
-   must be an integer in the range -precision through precision.  The
-   absolute value of the second operand gives the number of places to
-   rotate.  If the second operand is positive then rotation is to the
-   left; otherwise rotation is to the right.  The coefficient of the
-   first operand is padded on the left with zeros to length precision
-   if necessary.  The sign and exponent of the first operand are
-   unchanged.
-
-
-.. method:: Decimal.same_quantum(other[, context])
-
-   Test whether self and other have the same exponent or whether both are
-   :const:`NaN`.
+      Round 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.
 
-.. method:: Decimal.scaleb(other[, context])
+   .. method:: trim()
 
-   Return the first operand with exponent adjusted by the second.
-   Equivalently, return the first operand multiplied by ``10**other``.
-   The second operand must be an integer.
-
-
-.. method:: Decimal.shift(other[, context])
-
-   Return the result of shifting the digits of the first operand by
-   an amount specified by the second operand.  The second operand must
-   be an integer in the range -precision through precision.  The
-   absolute value of the second operand gives the number of places to
-   shift.  If the second operand is positive then the shift is to the
-   left; otherwise the shift is to the right.  Digits shifted into the
-   coefficient are zeros.  The sign and exponent of the first operand
-   are unchanged.
-
-
-.. method:: Decimal.sqrt([context])
-
-   Return the square root of the argument 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]])
-
-   Identical to the :meth:`to_integral_value` method.  The ``to_integral``
-   name has been kept for compatibility with older versions.
-
-.. method:: Decimal.to_integral_exact([rounding[, context]])
-
-   Round to the nearest integer, signaling
-   :const:`Inexact` or :const:`Rounded` as appropriate if rounding
-   occurs.  The rounding mode is determined by the ``rounding``
-   parameter if given, else by the given ``context``.  If neither
-   parameter is given then the rounding mode of the current context is
-   used.
-
-
-.. method:: Decimal.to_integral_value([rounding[, context]])
-
-   Round 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.
-
-
-.. method:: Decimal.trim()
-
-   Return the decimal with *insignificant* trailing zeros removed.
-   Here, a trailing zero is considered insignificant either if it
-   follows the decimal point, or if the exponent of the argument (that
-   is, the last element of the :meth:`as_tuple` representation) is
-   positive.
+      Return the decimal with *insignificant* trailing zeros removed.  Here, a
+      trailing zero is considered insignificant either if it follows the decimal
+      point, or if the exponent of the argument (that is, the last element of
+      the :meth:`as_tuple` representation) is positive.
 
 
 .. _logical_operands_label:
@@ -916,150 +868,147 @@ In addition to the three supplied contexts, new contexts can be created with the
    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.  In addition, for each of the :class:`Decimal` methods
-described above (with the exception of the :meth:`adjusted` and
-:meth:`as_tuple` methods) there is a corresponding :class:`Context`
-method.  For example, ``C.exp(x)`` is equivalent to
-``x.exp(context=C)``.
-
-.. method:: Context.clear_flags()
+   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.
+   In addition, for each of the :class:`Decimal` methods described above (with
+   the exception of the :meth:`adjusted` and :meth:`as_tuple` methods) there is
+   a corresponding :class:`Context` method.  For example, ``C.exp(x)`` is
+   equivalent to ``x.exp(context=C)``.
 
-   Resets all of the flags to :const:`0`.
 
+   .. method:: clear_flags()
 
-.. method:: Context.copy()
+      Resets all of the flags to :const:`0`.
 
-   Return a duplicate of the context.
+   .. method:: copy()
 
-.. method:: Context.copy_decimal(num)
+      Return a duplicate of the context.
 
-   Return a copy of the Decimal instance num.
+   .. method:: copy_decimal(num)
 
-.. method:: Context.create_decimal(num)
+      Return a copy of the Decimal instance 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.
+   .. method:: create_decimal(num)
 
-   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:
+      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.
 
-   .. doctest:: newcontext
+      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')
+      .. doctest:: newcontext
 
-   This method implements the to-number operation of the IBM
-   specification.  If the argument is a string, no leading or trailing
-   whitespace is permitted.
+         >>> 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()
+      This method implements the to-number operation of the IBM specification.
+      If the argument is a string, no leading or trailing whitespace is
+      permitted.
 
-   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:: 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``.
+   .. method:: Etop()
 
-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 alternative 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.
+      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 alternative 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:: abs(x)
 
+      Returns the absolute value of *x*.
 
-.. method:: Context.add(x, y)
 
-   Return the sum of *x* and *y*.
+   .. method:: add(x, y)
 
+      Return the sum of *x* and *y*.
 
-.. method:: Context.divide(x, y)
 
-   Return *x* divided by *y*.
+   .. method:: divide(x, y)
 
+      Return *x* divided by *y*.
 
-.. method:: Context.divide_int(x, y)
 
-   Return *x* divided by *y*, truncated to an integer.
+   .. method:: divide_int(x, y)
 
+      Return *x* divided by *y*, truncated to an integer.
 
-.. method:: Context.divmod(x, y)
 
-   Divides two numbers and returns the integer part of the result.
+   .. method:: divmod(x, y)
 
+      Divides two numbers and returns the integer part of the result.
 
-.. method:: Context.minus(x)
 
-   Minus corresponds to the unary prefix minus operator in Python.
+   .. method:: 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:: multiply(x, y)
 
+      Return the product of *x* and *y*.
 
-.. 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:: 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`` to the power of ``y``, reduced modulo ``modulo`` if
-   given.
+   .. method:: power(x, y[, modulo])
 
-   With two arguments, compute ``x**y``.  If ``x`` is negative then
-   ``y`` must be integral.  The result will be inexact unless ``y`` is
-   integral and the result is finite and can be expressed exactly in
-   'precision' digits.  The result should always be correctly rounded,
-   using the rounding mode of the current thread's context.
+      Return ``x`` to the power of ``y``, reduced modulo ``modulo`` if given.
 
-   With three arguments, compute ``(x**y) % modulo``.  For the three
-   argument form, the following restrictions on the arguments hold:
+      With two arguments, compute ``x**y``.  If ``x`` is negative then ``y``
+      must be integral.  The result will be inexact unless ``y`` is integral and
+      the result is finite and can be expressed exactly in 'precision' digits.
+      The result should always be correctly rounded, using the rounding mode of
+      the current thread's context.
 
-      - all three arguments must be integral
-      - ``y`` must be nonnegative
-      - at least one of ``x`` or ``y`` must be nonzero
-      - ``modulo`` must be nonzero and have at most 'precision' digits
+      With three arguments, compute ``(x**y) % modulo``.  For the three argument
+      form, the following restrictions on the arguments hold:
 
-   The result of ``Context.power(x, y, modulo)`` is identical to
-   the result that would be obtained by computing ``(x**y) %
-   modulo`` with unbounded precision, but is computed more
-   efficiently.  It is always exact.
+         - all three arguments must be integral
+         - ``y`` must be nonnegative
+         - at least one of ``x`` or ``y`` must be nonzero
+         - ``modulo`` must be nonzero and have at most 'precision' digits
 
+      The result of ``Context.power(x, y, modulo)`` is identical to the result
+      that would be obtained by computing ``(x**y) % modulo`` with unbounded
+      precision, but is computed more efficiently.  It is always exact.
 
-.. method:: Context.remainder(x, y)
+   .. method:: remainder(x, y)
 
-   Returns the remainder from integer division.
+      Returns the remainder from integer division.
 
-   The sign of the result, if non-zero, is the same as that of the original
-   dividend.
+      The sign of the result, if non-zero, is the same as that of the original
+      dividend.
 
-.. method:: Context.subtract(x, y)
+   .. method:: subtract(x, y)
 
-   Return the difference between *x* and *y*.
+      Return the difference between *x* and *y*.
 
-.. method:: Context.to_sci_string(x)
+   .. method:: to_sci_string(x)
 
-   Converts a number to a string using scientific notation.
+      Converts a number to a string using scientific notation.
 
 .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -1138,28 +1087,29 @@ condition.
 
    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.
+   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.
+   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.
+   Occurs when an operation result is subnormal (the exponent is too small). If
+   not trapped, returns the result unchanged.
 
 
 .. class:: Underflow