Merged revisions 58095-58132,58136-58148,58151-58197 via svnmerge from

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

........
  r58096 | brett.cannon | 2007-09-10 23:38:27 +0200 (Mon, 10 Sep 2007) | 4 lines

  Fix a possible segfault from recursing too deep to get the repr of a list.

  Closes issue #1096.
........
  r58097 | bill.janssen | 2007-09-10 23:51:02 +0200 (Mon, 10 Sep 2007) | 33 lines

  More work on SSL support.

  * Much expanded test suite:

    All protocols tested against all other protocols.
    All protocols tested with all certificate options.
    Tests for bad key and bad cert.
    Test of STARTTLS functionality.
    Test of RAND_* functions.

  * Fixes for threading/malloc bug.

  * Issue 1065 fixed:

    sslsocket class renamed to SSLSocket.
    sslerror class renamed to SSLError.
    Function "wrap_socket" now used to wrap an existing socket.

  * Issue 1583946 finally fixed:

    Support for subjectAltName added.
    Subject name now returned as proper DN list of RDNs.

  * SSLError exported from socket as "sslerror".

  * RAND_* functions properly exported from ssl.py.

  * Documentation improved:

    Example of how to create a self-signed certificate.
    Better indexing.
........
  r58098 | guido.van.rossum | 2007-09-11 00:02:25 +0200 (Tue, 11 Sep 2007) | 9 lines

  Patch # 1140 (my code, approved by Effbot).

  Make sure the type of the return value of re.sub(x, y, z) is the type
  of y+x (i.e. unicode if either is unicode, str if they are both str)
  even if there are no substitutions or if x==z (which triggered various
  special cases in join_list()).

  Could be backported to 2.5; no need to port to 3.0.
........
  r58099 | guido.van.rossum | 2007-09-11 00:36:02 +0200 (Tue, 11 Sep 2007) | 8 lines

  Patch # 1026 by Benjamin Aranguren (with Alex Martelli):
  Backport abc.py and isinstance/issubclass overloading to 2.6.

  I had to backport test_typechecks.py myself, and make one small change
  to abc.py to avoid duplicate work when x.__class__ and type(x) are the
  same.
........
  r58100 | bill.janssen | 2007-09-11 01:41:24 +0200 (Tue, 11 Sep 2007) | 3 lines

  A better way of finding an open port to test with.
........
  r58101 | bill.janssen | 2007-09-11 03:09:19 +0200 (Tue, 11 Sep 2007) | 4 lines

  Make sure test_ssl doesn't reference the ssl module in a
  context where it can't be imported.
........
  r58102 | bill.janssen | 2007-09-11 04:42:07 +0200 (Tue, 11 Sep 2007) | 3 lines

  Fix some documentation bugs.
........
  r58103 | nick.coghlan | 2007-09-11 16:01:18 +0200 (Tue, 11 Sep 2007) | 1 line

  Always use the -E flag when spawning subprocesses in test_cmd_line (Issue 1056)
........
  r58106 | thomas.heller | 2007-09-11 21:17:48 +0200 (Tue, 11 Sep 2007) | 3 lines

  Disable some tests that fail on the 'ppc Debian unstable' buildbot to
  find out if they cause the segfault on the 'alpha Debian' machine.
........
  r58108 | brett.cannon | 2007-09-11 23:02:28 +0200 (Tue, 11 Sep 2007) | 6 lines

  Generators had their throw() method allowing string exceptions.  That's a
  no-no.

  Fixes issue #1147.  Need to fix 2.5 to raise a proper warning if a string
  exception is passed in.
........
  r58112 | georg.brandl | 2007-09-12 20:03:51 +0200 (Wed, 12 Sep 2007) | 3 lines

  New documentation page for the bdb module.
  (This doesn't need to be merged to Py3k.)
........
  r58114 | georg.brandl | 2007-09-12 20:05:57 +0200 (Wed, 12 Sep 2007) | 2 lines

  Bug #1152: use non-deprecated name in example.
........
  r58115 | georg.brandl | 2007-09-12 20:08:33 +0200 (Wed, 12 Sep 2007) | 2 lines

  Fix #1122: wrong return type documented for various _Size() functions.
........
  r58117 | georg.brandl | 2007-09-12 20:10:56 +0200 (Wed, 12 Sep 2007) | 2 lines

  Fix #1139: PyFile_Encoding really is PyFile_SetEncoding.
........
  r58119 | georg.brandl | 2007-09-12 20:29:18 +0200 (Wed, 12 Sep 2007) | 2 lines

  bug #1154: release memory allocated by "es" PyArg_ParseTuple format specifier.
........
  r58121 | bill.janssen | 2007-09-12 20:52:05 +0200 (Wed, 12 Sep 2007) | 1 line

  root certificate for https://svn.python.org/, used in test_ssl
........
  r58122 | georg.brandl | 2007-09-12 21:00:07 +0200 (Wed, 12 Sep 2007) | 3 lines

  Bug #1153: repr.repr() now doesn't require set and dictionary items
  to be orderable to properly represent them.
........
  r58125 | georg.brandl | 2007-09-12 21:29:28 +0200 (Wed, 12 Sep 2007) | 4 lines

  #1120: put explicit version in the shebang lines of pydoc, idle
  and smtpd.py scripts that are installed by setup.py. That way, they
  work when only "make altinstall" is used.
........
  r58139 | mark.summerfield | 2007-09-13 16:54:30 +0200 (Thu, 13 Sep 2007) | 9 lines

  Replaced variable o with obj in operator.rst because o is easy to
  confuse.

  Added a note about Python 3's collections.Mapping etc., above section
  that describes isMappingType() etc.

  Added xrefs between os, os.path, fileinput, and open().
........
  r58143 | facundo.batista | 2007-09-13 20:13:15 +0200 (Thu, 13 Sep 2007) | 7 lines


  Merged the decimal-branch (revisions 54886 to 58140). Decimal is now
  fully updated to the latests Decimal Specification (v1.66) and the
  latests test cases (v2.56).

  Thanks to Mark Dickinson for all his help during this process.
........
  r58145 | facundo.batista | 2007-09-13 20:42:09 +0200 (Thu, 13 Sep 2007) | 7 lines


  Put the parameter watchexp back in (changed watchexp from an int
  to a bool).  Also second argument to watchexp is now converted
  to Decimal, just as with all the other two-argument operations.

  Thanks Mark Dickinson.
........
  r58147 | andrew.kuchling | 2007-09-14 00:49:34 +0200 (Fri, 14 Sep 2007) | 1 line

  Add various items
........
  r58148 | andrew.kuchling | 2007-09-14 00:50:10 +0200 (Fri, 14 Sep 2007) | 1 line

  Make target unique
........
  r58154 | facundo.batista | 2007-09-14 20:58:34 +0200 (Fri, 14 Sep 2007) | 3 lines


  Included the new functions, and new descriptions.
........
  r58155 | thomas.heller | 2007-09-14 21:40:35 +0200 (Fri, 14 Sep 2007) | 2 lines

  ctypes.util.find_library uses dump(1) instead of objdump(1) on Solaris.
  Fixes issue #1777530; will backport to release25-maint.
........
  r58159 | facundo.batista | 2007-09-14 23:29:52 +0200 (Fri, 14 Sep 2007) | 3 lines


  Some additions (examples and a bit on the tutorial).
........
  r58160 | georg.brandl | 2007-09-15 18:53:36 +0200 (Sat, 15 Sep 2007) | 2 lines

  Remove bdb from the "undocumented modules" list.
........
  r58164 | bill.janssen | 2007-09-17 00:06:00 +0200 (Mon, 17 Sep 2007) | 15 lines

  Add support for asyncore server-side SSL support.  This requires
  adding the 'makefile' method to ssl.SSLSocket, and importing the
  requisite fakefile class from socket.py, and making the appropriate
  changes to it to make it use the SSL connection.

  Added sample HTTPS server to test_ssl.py, and test that uses it.

  Change SSL tests to use https://svn.python.org/, instead of
  www.sf.net and pop.gmail.com.

  Added utility function to ssl module, get_server_certificate,
  to wrap up the several things to be done to pull a certificate
  from a remote server.
........
  r58173 | bill.janssen | 2007-09-17 01:16:46 +0200 (Mon, 17 Sep 2007) | 1 line

  use binary mode when reading files for testAsyncore to make Windows happy
........
  r58175 | raymond.hettinger | 2007-09-17 02:55:00 +0200 (Mon, 17 Sep 2007) | 7 lines

  Sync-up named tuples with the latest version of the ASPN recipe.
  Allows optional commas in the field-name spec (help when named tuples are used in conjuction with sql queries).
  Adds the __fields__ attribute for introspection and to support conversion to dictionary form.
  Adds a  __replace__() method similar to str.replace() but using a named field as a target.
  Clean-up spelling and presentation in doc-strings.
........
  r58176 | brett.cannon | 2007-09-17 05:28:34 +0200 (Mon, 17 Sep 2007) | 5 lines

  Add a bunch of GIL release/acquire points in tp_print implementations and for
  PyObject_Print().

  Closes issue #1164.
........
  r58177 | sean.reifschneider | 2007-09-17 07:45:04 +0200 (Mon, 17 Sep 2007) | 2 lines

  issue1597011: Fix for bz2 module corner-case error due to error checking bug.
........
  r58180 | facundo.batista | 2007-09-17 18:26:50 +0200 (Mon, 17 Sep 2007) | 3 lines


  Decimal is updated, :)
........
  r58181 | facundo.batista | 2007-09-17 19:30:13 +0200 (Mon, 17 Sep 2007) | 5 lines


  The methods always return Decimal classes, even if they're
  executed through a subclass (thanks Mark Dickinson).
  Added a bit of testing for this.
........
  r58183 | sean.reifschneider | 2007-09-17 22:53:21 +0200 (Mon, 17 Sep 2007) | 2 lines

  issue1082: Fixing platform and system for Vista.
........
  r58185 | andrew.kuchling | 2007-09-18 03:36:16 +0200 (Tue, 18 Sep 2007) | 1 line

  Add item; sort properly
........
  r58186 | raymond.hettinger | 2007-09-18 05:33:19 +0200 (Tue, 18 Sep 2007) | 1 line

  Handle corner cased on 0-tuples and 1-tuples.  Add verbose option so people can see how it works.
........
  r58192 | georg.brandl | 2007-09-18 09:24:40 +0200 (Tue, 18 Sep 2007) | 2 lines

  A bit of reordering, also show more subheadings in the lang ref index.
........
  r58193 | facundo.batista | 2007-09-18 18:53:18 +0200 (Tue, 18 Sep 2007) | 4 lines


  Speed up of the various division operations (remainder, divide,
  divideint and divmod). Thanks Mark Dickinson.
........
  r58197 | raymond.hettinger | 2007-09-19 00:18:02 +0200 (Wed, 19 Sep 2007) | 1 line

  Cleanup docs for NamedTuple.
........

1 files changed, 462 insertions, 121 deletions

diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst
index 444b20a..bbac0d4 100644
--- a/Doc/library/decimal.rst
+++ b/Doc/library/decimal.rst
@@ -14,7 +14,7 @@
 
 
 The :mod:`decimal` module provides support for decimal floating point
-arithmetic.  It offers several advantages over the :class:`float()` datatype:
+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
@@ -22,7 +22,7 @@ arithmetic.  It offers several advantages over the :class:`float()` datatype:
   :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
+  + 0.1 + 0.1 - 0.3`` is exactly equal to zero.  In binary floating point, the 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
@@ -36,7 +36,7 @@ arithmetic.  It offers several advantages over the :class:`float()` datatype:
   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
+  alterable precision (defaulting to 28 places) which can be as large as needed for
   a given problem::
 
      >>> getcontext().prec = 6
@@ -56,7 +56,7 @@ 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
+trailing zeros.  Decimals also include special values such as
 :const:`Infinity`, :const:`-Infinity`, and :const:`NaN`.  The standard also
 differentiates :const:`-0` from :const:`+0`.
 
@@ -65,7 +65,7 @@ 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`.
+:const:`ROUND_HALF_UP`, :const:`ROUND_UP`, and :const:`ROUND_05UP`.
 
 Signals are groups of exceptional conditions arising during the course of
 computation.  Depending on the needs of the application, signals may be ignored,
@@ -82,11 +82,11 @@ 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>`_.
+   * 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>`_.
+   * IEEE standard 854-1987, `Unofficial IEEE 854 Text
+     <http://www.cs.berkeley.edu/~ejr/projects/754/private/drafts/854-1987/dir.html>`_.
 
 .. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -123,6 +123,8 @@ representation error).  Decimal numbers include special values such as
    Decimal("3.14")
    >>> Decimal(str(2.0 ** 0.5))
    Decimal("1.41421356237")
+   >>> Decimal(2) ** Decimal("0.5")
+   Decimal("1.414213562373095048801688724")
    >>> Decimal("NaN")
    Decimal("NaN")
    >>> Decimal("-Infinity")
@@ -172,6 +174,17 @@ floating point flying circus::
    >>> c % a
    Decimal("0.77")
 
+And some mathematic functions are also available to Decimal::
+
+   >>> Decimal(2).sqrt()
+   Decimal("1.414213562373095048801688724")
+   >>> Decimal(1).exp()
+   Decimal("2.718281828459045235360287471")
+   >>> Decimal("10").ln()
+   Decimal("2.302585092994045684017991455")
+   >>> Decimal("10").log10()
+   Decimal("1")
+
 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::
@@ -285,7 +298,7 @@ Decimal objects
 
    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
+   ``Decimal("3.00000")`` records all five zeros even if the context precision is
    only three.
 
    The purpose of the *context* argument is determining what to do if *value* is a
@@ -295,7 +308,7 @@ Decimal objects
 
    Once constructed, :class:`Decimal` objects are immutable.
 
-Decimal floating point objects share many properties with the other builtin
+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,
@@ -315,50 +328,363 @@ also have a number of specialized methods:
 
 .. method:: Decimal.as_tuple()
 
-   Returns a tuple representation of the number: ``(sign, digittuple, exponent)``.
+   Return a tuple representation of the number: ``(sign, digit_tuple, exponent)``.
+
 
+.. 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.
+
+   .. versionadded:: 2.6
 
 .. method:: Decimal.compare(other[, context])
 
-   Compares like :meth:`__cmp__` but returns a decimal instance::
+   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::
 
       a or b is a NaN ==> Decimal("NaN")
       a < b           ==> Decimal("-1")
       a == b          ==> Decimal("0")
       a > b           ==> Decimal("1")
 
+.. method:: Decimal.compare_signal(other[, context])
+
+   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.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.compare_total(other)
+
+   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")
+
+   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.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.compare_total_mag(other)
+
+   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())``.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.copy_abs()
+
+   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.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.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.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.copy_sign(other)
+
+   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")
+   
+   This operation is unaffected by the context and is quiet: no flags
+   are changed and no rounding is performed.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.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.
+
+   >>> Decimal(1).exp()
+   Decimal("2.718281828459045235360287471")
+   >>> Decimal(321).exp()
+   Decimal("2.561702493119680037517373933E+139")
+
+   .. versionadded:: 2.6
+
+.. 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")
+
+   .. versionadded:: 2.6
+
+.. 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`.
+
+   .. versionadded:: 2.6
+
+.. 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.
+
+   .. versionadded:: 2.6
+
+.. method:: is_infinite()
+
+   Return :const:`True` if the argument is either positive or
+   negative infinity and :const:`False` otherwise.
+
+   .. versionadded:: 2.6
+
+.. method:: is_nan()
+
+   Return :const:`True` if the argument is a (quiet or signaling)
+   NaN and :const:`False` otherwise.
+
+   .. versionadded:: 2.6
+
+.. method:: is_normal()
+
+   Return :const:`True` if the argument is a *normal* finite number.
+   Return :const:`False` if the argument is zero, subnormal, infinite
+   or a NaN.
+
+   .. versionadded:: 2.6
+
+.. method:: is_qnan()
+
+   Return :const:`True` if the argument is a quiet NaN, and
+   :const:`False` otherwise.
+
+   .. versionadded:: 2.6
+
+.. 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.
+
+   .. versionadded:: 2.6
+
+.. method:: is_snan()
+
+   Return :const:`True` if the argument is a signaling NaN and
+   :const:`False` otherwise.
+
+   .. versionadded:: 2.6
+
+.. method:: is_subnormal()
+
+   Return :const:`True` if the argument is subnormal, and
+   :const:`False` otherwise.
+
+   .. versionadded:: 2.6
+
+.. method:: is_zero()
+
+   Return :const:`True` if the argument is a (positive or negative)
+   zero and :const:`False` otherwise.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.ln([context])
+
+   Return the natural (base e) logarithm of the operand.  The result
+   is correctly rounded using the :const:`ROUND_HALF_EVEN` rounding
+   mode.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.log10([context])
+
+   Return the base ten logarithm of the operand.  The result is
+   correctly rounded using the :const:`ROUND_HALF_EVEN` rounding mode.
+
+   .. versionadded:: 2.6
+
+.. method:  Decimal.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.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.logical_and(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.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.logical_invert(other[, 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.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.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.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.logical_xor(other[, context])
+
+   :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.
+
+   .. versionadded:: 2.6
 
 .. 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
+   before returning and that :const:`NaN` values are either signaled or ignored
    (depending on the context and whether they are signaling or quiet).
 
+.. method:: Decimal.max_mag(other[, context])
+
+   Similar to the :meth:`max` method, but the comparison is done using
+   the absolute values of the operands.
+
+   .. versionadded:: 2.6
 
 .. 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
+   before returning and that :const:`NaN` values are either signaled or ignored
    (depending on the context and whether they are signaling or quiet).
 
+.. method:: Decimal.min_mag(other[, context])
+
+   Similar to the :meth:`min` method, but the comparison is done using
+   the absolute values of the operands.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.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.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.next_plus([context])
+
+   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.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.next_toward(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.
+
+   .. versionadded:: 2.6
 
 .. method:: Decimal.normalize([context])
 
-   Normalize the number by stripping the rightmost trailing zeroes and converting
+   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.number_class([context])
+
+   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.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.quantize(exp[, rounding[, context[, watchexp]]])
+
+   Returns a value equal to the first operand after rounding and
+   having the exponent of the second operand.
 
-.. method:: Decimal.quantize(exp [, rounding[, context[, watchexp]]])
+   >>> Decimal("1.41421356").quantize(Decimal("1.000"))
+   Decimal("1.414")
 
-   Quantize makes the exponent the same as *exp*.  Searches for a rounding method
-   in *rounding*, then in *context*, and then in the current 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.
 
-   If *watchexp* is set (default), then an error is returned whenever the resulting
-   exponent is greater than :attr:`Emax` or less than :attr:`Etiny`.
+   Also unlike other operations, quantize never signals Underflow,
+   even if the result is subnormal and inexact.
 
+   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.
+
+   If watchexp is set (default), then an error is returned whenever 
+   the resulting exponent is greater than Emax or less than Etiny.
+
+.. 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.
+
+   .. versionadded:: 2.6
 
 .. method:: Decimal.remainder_near(other[, context])
 
@@ -368,16 +694,49 @@ also have a number of specialized methods:
 
    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.
+
+   .. versionadded:: 2.6
 
 .. method:: Decimal.same_quantum(other[, context])
 
    Test whether self and other have the same exponent or whether both are
    :const:`NaN`.
 
+.. method:: Decimal.scaleb(other[, 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.
+
+   .. versionadded:: 2.6
+
+.. 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.
+
+   .. versionadded:: 2.6
 
 .. method:: Decimal.sqrt([context])
 
-   Return the square root to full precision.
+   Return the square root of the argument to full precision.
 
 
 .. method:: Decimal.to_eng_string([context])
@@ -388,13 +747,53 @@ also have a number of specialized methods:
    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 the argument 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.
+
+   .. versionadded:: 2.6
+
+.. method:: Decimal.to_integral_value([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.
 
+   .. versionchanged:: 2.6
+      renamed from ``to_integral`` to ``to_integral_value``.  The old name
+      remains valid for compatibility.
+
+.. method:: Decimal.trim()
+
+   Returns its argument 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.
+
+   .. versionadded:: 2.6
+
+.. _logical_operands_label:
+
+Logical operands
+^^^^^^^^^^^^^^^^
+
+The :meth:`logical_and`, :meth:`logical_invert`, :meth:`logical_or`,
+and :meth:`logical_xor` methods expect their arguments to be *logical
+operands*.  A *logical operand* is a :class:`Decimal` instance whose
+exponent and sign are both zero, and whose digits are all either
+:const:`0` or :const:`1`.
+
 .. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
@@ -509,6 +908,8 @@ In addition to the three supplied contexts, new contexts can be created with the
    * :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).
+   * :const:`ROUND_05UP` (away from zero if last digit after rounding towards zero 
+     would have been 0 or 5; otherwise towards zero)
 
    The *traps* and *flags* fields list any signals to be set. Generally, new
    contexts should only set traps and leave the flags clear.
@@ -520,9 +921,16 @@ In addition to the three supplied contexts, new contexts can be created with the
    :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.
+   .. versionchanged:: 2.6
+      The :const:`ROUND_05UP` rounding mode was added.
 
+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()
 
@@ -533,6 +941,9 @@ large number of methods for doing arithmetic directly in a given context.
 
    Return a duplicate of the context.
 
+.. method:: Context.copy_decimal(num)
+
+   Return a copy of the Decimal instance num.
 
 .. method:: Context.create_decimal(num)
 
@@ -581,42 +992,19 @@ those for the :class:`Decimal` class and are only briefly recounted here.
    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)
+.. method:: Context.divide_int(x, y)
 
-   Compare two values numerically and return the maximum.
+   Return *x* divided by *y*, truncated to an integer.
 
-   If they are numerically equal then the left-hand operand is chosen as the
-   result.
 
+.. method:: Context.divmod(x, y)
 
-.. 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.
+   Divides two numbers and returns the integer part of the result.
 
 
 .. method:: Context.minus(x)
@@ -629,14 +1017,6 @@ those for the :class:`Decimal` class and are only briefly recounted here.
    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
@@ -646,33 +1026,31 @@ those for the :class:`Decimal` class and are only briefly recounted here.
 
 .. 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.
+   Return ``x`` to the power of ``y``, reduced modulo ``modulo`` if
+   given.
 
+   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.
 
-.. method:: Context.quantize(x, y)
+   With three arguments, compute ``(x**y) % modulo``.  For the three
+   argument form, the following restrictions on the arguments hold:
 
-   Returns a value equal to *x* after rounding and having the exponent of *y*.
+      - 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
 
-   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.
+   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.
 
-   Also unlike other operations, quantize never signals Underflow, even if the
-   result is subnormal and inexact.
+   .. versionchanged:: 2.6 
+      ``y`` may now be nonintegral in ``x**y``.
+      Stricter requirements for the three-argument version.
 
 
 .. method:: Context.remainder(x, y)
@@ -682,47 +1060,10 @@ those for the :class:`Decimal` class and are only briefly recounted here.
    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.
@@ -755,7 +1096,7 @@ condition.
 
    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.
+   fit by adding zeros to the coefficient.
 
 
 .. class:: DecimalException
@@ -908,7 +1249,7 @@ 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`.
+and two zeros, :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