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.
........

2 files changed, 469 insertions, 3 deletions

diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst
index f0429ec..497c612 100644
--- a/Doc/whatsnew/2.5.rst
+++ b/Doc/whatsnew/2.5.rst
@@ -637,7 +637,7 @@ precision and rounding characteristics for computations::
        print v.sqrt()
 
 
-.. _context-managers:
+.. _new-25-context-managers:
 
 Writing Context Managers
 ------------------------
diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst
index 154b103..2dc5844 100644
--- a/Doc/whatsnew/2.6.rst
+++ b/Doc/whatsnew/2.6.rst
@@ -2,6 +2,9 @@
   What's New in Python 2.6  
 ****************************
 
+.. % XXX mention switch to reST for documentation
+.. % XXX mention switch to Roundup for bug tracking
+
 :Author: A.M. Kuchling
 :Release: |release|
 :Date: |today|
@@ -67,12 +70,367 @@ new feature.
 .. % sets module deprecated
 .. % ======================================================================
 
+Python 3.0
+================
+
+.. % XXX add general comment about Python 3.0 features in 2.6
+
+.. % XXX mention -3 switch
+
+A new command-line switch, :option:`-3`, enables warnings
+about features that will be removed in Python 3.0.  You can run code
+with this switch to see how much work will be necessary to port
+code to 3.0.
+
+.. seealso::
+
+   The 3xxx series of PEPs, which describes the development process for
+   Python 3.0 and various features that have been accepted, rejected,
+   or are still under consideration.
+
+PEP 343: The 'with' statement
+=============================
+
+The previous version, Python 2.5, added the ':keyword:`with`'
+statement an optional feature, to be enabled by a ``from __future__
+import generators`` directive.  In 2.6 the statement no longer need to
+be specially enabled; this means that :keyword:`with` is now always a
+keyword.  The rest of this section is a copy of the corresponding 
+section from "What's New in Python 2.5" document; if you read
+it back when Python 2.5 came out, you can skip the rest of this
+section.
+
+The ':keyword:`with`' statement clarifies code that previously would use
+``try...finally`` blocks to ensure that clean-up code is executed.  In this
+section, I'll discuss the statement as it will commonly be used.  In the next
+section, I'll examine the implementation details and show how to write objects
+for use with this statement.
+
+The ':keyword:`with`' statement is a new control-flow structure whose basic
+structure is::
+
+   with expression [as variable]:
+       with-block
+
+The expression is evaluated, and it should result in an object that supports the
+context management protocol (that is, has :meth:`__enter__` and :meth:`__exit__`
+methods.
+
+The object's :meth:`__enter__` is called before *with-block* is executed and
+therefore can run set-up code. It also may return a value that is bound to the
+name *variable*, if given.  (Note carefully that *variable* is *not* assigned
+the result of *expression*.)
+
+After execution of the *with-block* is finished, the object's :meth:`__exit__`
+method is called, even if the block raised an exception, and can therefore run
+clean-up code.
+
+Some standard Python objects now support the context management protocol and can
+be used with the ':keyword:`with`' statement. File objects are one example::
+
+   with open('/etc/passwd', 'r') as f:
+       for line in f:
+           print line
+           ... more processing code ...
+
+After this statement has executed, the file object in *f* will have been
+automatically closed, even if the :keyword:`for` loop raised an exception part-
+way through the block.
+
+.. note::
+
+   In this case, *f* is the same object created by :func:`open`, because
+   :meth:`file.__enter__` returns *self*.
+
+The :mod:`threading` module's locks and condition variables  also support the
+':keyword:`with`' statement::
+
+   lock = threading.Lock()
+   with lock:
+       # Critical section of code
+       ...
+
+The lock is acquired before the block is executed and always released once  the
+block is complete.
+
+The new :func:`localcontext` function in the :mod:`decimal` module makes it easy
+to save and restore the current decimal context, which encapsulates the desired
+precision and rounding characteristics for computations::
+
+   from decimal import Decimal, Context, localcontext
+
+   # Displays with default precision of 28 digits
+   v = Decimal('578')
+   print v.sqrt()
+
+   with localcontext(Context(prec=16)):
+       # All code in this block uses a precision of 16 digits.
+       # The original context is restored on exiting the block.
+       print v.sqrt()
+
+
+.. _new-26-context-managers:
+
+Writing Context Managers
+------------------------
+
+Under the hood, the ':keyword:`with`' statement is fairly complicated. Most
+people will only use ':keyword:`with`' in company with existing objects and
+don't need to know these details, so you can skip the rest of this section if
+you like.  Authors of new objects will need to understand the details of the
+underlying implementation and should keep reading.
+
+A high-level explanation of the context management protocol is:
+
+* The expression is evaluated and should result in an object called a "context
+  manager".  The context manager must have :meth:`__enter__` and :meth:`__exit__`
+  methods.
+
+* The context manager's :meth:`__enter__` method is called.  The value returned
+  is assigned to *VAR*.  If no ``'as VAR'`` clause is present, the value is simply
+  discarded.
+
+* The code in *BLOCK* is executed.
+
+* If *BLOCK* raises an exception, the :meth:`__exit__(type, value, traceback)`
+  is called with the exception details, the same values returned by
+  :func:`sys.exc_info`.  The method's return value controls whether the exception
+  is re-raised: any false value re-raises the exception, and ``True`` will result
+  in suppressing it.  You'll only rarely want to suppress the exception, because
+  if you do the author of the code containing the ':keyword:`with`' statement will
+  never realize anything went wrong.
+
+* If *BLOCK* didn't raise an exception,  the :meth:`__exit__` method is still
+  called, but *type*, *value*, and *traceback* are all ``None``.
+
+Let's think through an example.  I won't present detailed code but will only
+sketch the methods necessary for a database that supports transactions.
+
+(For people unfamiliar with database terminology: a set of changes to the
+database are grouped into a transaction.  Transactions can be either committed,
+meaning that all the changes are written into the database, or rolled back,
+meaning that the changes are all discarded and the database is unchanged.  See
+any database textbook for more information.)
+
+Let's assume there's an object representing a database connection. Our goal will
+be to let the user write code like this::
+
+   db_connection = DatabaseConnection()
+   with db_connection as cursor:
+       cursor.execute('insert into ...')
+       cursor.execute('delete from ...')
+       # ... more operations ...
+
+The transaction should be committed if the code in the block runs flawlessly or
+rolled back if there's an exception. Here's the basic interface for
+:class:`DatabaseConnection` that I'll assume::
+
+   class DatabaseConnection:
+       # Database interface
+       def cursor (self):
+           "Returns a cursor object and starts a new transaction"
+       def commit (self):
+           "Commits current transaction"
+       def rollback (self):
+           "Rolls back current transaction"
+
+The :meth:`__enter__` method is pretty easy, having only to start a new
+transaction.  For this application the resulting cursor object would be a useful
+result, so the method will return it.  The user can then add ``as cursor`` to
+their ':keyword:`with`' statement to bind the cursor to a variable name. ::
+
+   class DatabaseConnection:
+       ...
+       def __enter__ (self):
+           # Code to start a new transaction
+           cursor = self.cursor()
+           return cursor
+
+The :meth:`__exit__` method is the most complicated because it's where most of
+the work has to be done.  The method has to check if an exception occurred.  If
+there was no exception, the transaction is committed.  The transaction is rolled
+back if there was an exception.
+
+In the code below, execution will just fall off the end of the function,
+returning the default value of ``None``.  ``None`` is false, so the exception
+will be re-raised automatically.  If you wished, you could be more explicit and
+add a :keyword:`return` statement at the marked location. ::
+
+   class DatabaseConnection:
+       ...
+       def __exit__ (self, type, value, tb):
+           if tb is None:
+               # No exception, so commit
+               self.commit()
+           else:
+               # Exception occurred, so rollback.
+               self.rollback()
+               # return False
+
+
+.. _module-contextlib:
+
+The contextlib module
+---------------------
+
+The new :mod:`contextlib` module provides some functions and a decorator that
+are useful for writing objects for use with the ':keyword:`with`' statement.
+
+The decorator is called :func:`contextmanager`, and lets you write a single
+generator function instead of defining a new class.  The generator should yield
+exactly one value.  The code up to the :keyword:`yield` will be executed as the
+:meth:`__enter__` method, and the value yielded will be the method's return
+value that will get bound to the variable in the ':keyword:`with`' statement's
+:keyword:`as` clause, if any.  The code after the :keyword:`yield` will be
+executed in the :meth:`__exit__` method.  Any exception raised in the block will
+be raised by the :keyword:`yield` statement.
+
+Our database example from the previous section could be written  using this
+decorator as::
+
+   from contextlib import contextmanager
+
+   @contextmanager
+   def db_transaction (connection):
+       cursor = connection.cursor()
+       try:
+           yield cursor
+       except:
+           connection.rollback()
+           raise
+       else:
+           connection.commit()
+
+   db = DatabaseConnection()
+   with db_transaction(db) as cursor:
+       ...
+
+The :mod:`contextlib` module also has a :func:`nested(mgr1, mgr2, ...)` function
+that combines a number of context managers so you don't need to write nested
+':keyword:`with`' statements.  In this example, the single ':keyword:`with`'
+statement both starts a database transaction and acquires a thread lock::
+
+   lock = threading.Lock()
+   with nested (db_transaction(db), lock) as (cursor, locked):
+       ...
+
+Finally, the :func:`closing(object)` function returns *object* so that it can be
+bound to a variable, and calls ``object.close`` at the end of the block. ::
+
+   import urllib, sys
+   from contextlib import closing
+
+   with closing(urllib.urlopen('http://www.yahoo.com')) as f:
+       for line in f:
+           sys.stdout.write(line)
+
+
+.. seealso::
+
+   :pep:`343` - The "with" statement
+      PEP written by Guido van Rossum and Nick Coghlan; implemented by Mike Bland,
+      Guido van Rossum, and Neal Norwitz.  The PEP shows the code generated for a
+      ':keyword:`with`' statement, which can be helpful in learning how the statement
+      works.
+
+   The documentation  for the :mod:`contextlib` module.
+
+.. % ======================================================================
+
+.. _pep-3110:
+
+PEP 3110: Exception-Handling Changes
+=====================================================
+
+One error that Python programmers occasionally make 
+is the following::
+
+    try:
+        ...
+    except TypeError, ValueError:
+        ...
+
+The author is probably trying to catch both 
+:exc:`TypeError` and :exc:`ValueError` exceptions, but this code
+actually does something different: it will catch 
+:exc:`TypeError` and bind the resulting exception object
+to the local name ``"ValueError"``.  The correct code 
+would have specified a tuple::
+
+    try:
+        ...
+    except (TypeError, ValueError):
+        ...
+
+This error is possible because the use of the comma here is ambiguous:
+does it indicate two different nodes in the parse tree, or a single
+node that's a tuple.
+
+Python 3.0 changes the syntax to make this unambiguous by replacing
+the comma with the word "as".  To catch an exception and store the 
+exception object in the variable ``exc``, you must write::
+
+    try:
+        ...
+    except TypeError as exc:
+        ...
+
+Python 3.0 will only support the use of "as", and therefore interprets
+the first example as catching two different exceptions.  Python 2.6
+supports both the comma and "as", so existing code will continue to
+work.
+
+.. seealso::
+
+   :pep:`3110` - Catching Exceptions in Python 3000
+      PEP written and implemented by Collin Winter.
+
+.. % ======================================================================
+
+.. _pep-3119:
+
+PEP 3119: Abstract Base Classes
+=====================================================
+
+XXX
+
+.. seealso::
+
+   :pep:`3119` - Introducing Abstract Base Classes
+      PEP written by Guido van Rossum and Talin.
+      Implemented by XXX.
+      Backported to 2.6 by Benjamin Aranguren (with Alex Martelli).
 
 Other Language Changes
 ======================
 
 Here are all of the changes that Python 2.6 makes to the core Python language.
 
+* Changes to the :class:`Exception` interface
+  as dictated by :pep:`352` continue to be made.  For 2.6, 
+  the :attr:`message` attribute is being deprecated in favor of the
+  :attr:`args` attribute.
+
+* When calling a function using the ``**`` syntax to provide keyword
+  arguments, you are no longer required to use a Python dictionary;
+  any mapping will now work::
+
+    >>> def f(**kw):
+    ...    print sorted(kw)
+    ... 
+    >>> ud=UserDict.UserDict()
+    >>> ud['a'] = 1
+    >>> ud['b'] = 'string'
+    >>> f(**ud)
+    ['a', 'b']
+
+  .. % Patch 1686487
+
+* The :func:`compile` built-in function now accepts keyword arguments
+  as well as positional parameters.  (Contributed by XXX.)
+
+  .. % Patch 1444529
+
 * The :func:`complex` constructor now accepts strings containing 
   parenthesized complex numbers, letting ``complex(repr(cmplx))``
   will now round-trip values.  For example, ``complex('(3+4j)')``
@@ -87,6 +445,15 @@ Here are all of the changes that Python 2.6 makes to the core Python language.
 
   .. % Patch 1193128
 
+* The built-in :func:`dir` function now checks for a :meth:`__dir__`
+  method on the objects it receives.  This method must return a list
+  of strings containing the names of valid attributes for the object,
+  and lets the object control the value that :func:`dir` produces.
+  Objects that have :meth:`__getattr__` or :meth:`__getattribute__` 
+  methods.
+
+  .. % Patch 1591665
+
 * An obscure change: when you use the the :func:`locals` function inside a
   :keyword:`class` statement, the resulting dictionary no longer returns free
   variables.  (Free variables, in this case, are variables referred to in the
@@ -160,6 +527,11 @@ complete list of changes, or look through the CVS logs for all the details.
 
   (Contributed by Raymond Hettinger.)
 
+* An optional ``timeout`` parameter was added to the
+  :class:`httplib.HTTPConnection` and :class:`HTTPSConnection` 
+  class constructors, specifying a timeout measured in seconds.
+  (Added by Facundo Batista.)
+
 * A new function in the :mod:`itertools` module: ``izip_longest(iter1, iter2,
   ...[, fillvalue])`` makes tuples from each of the elements; if some of the
   iterables are shorter than others, the missing values  are set to *fillvalue*.
@@ -176,6 +548,15 @@ complete list of changes, or look through the CVS logs for all the details.
 
   .. % Patch #1490190
 
+* The :func:`os.walk` function now has a "followlinks" parameter. If
+  set to True, it will follow symlinks pointing to directories and
+  visit the directory's contents.  For backward compatibility, the
+  parameter's default value is false.  Note that the function can fall
+  into an infinite recursion if there's a symlink that points to a
+  parent directory.
+       
+  .. % Patch 1273829
+
 * In the :mod:`os.path` module, the :func:`splitext` function
   has been changed to not split on leading period characters.
   This produces better results when operating on Unix's dot-files.
@@ -191,6 +572,12 @@ complete list of changes, or look through the CVS logs for all the details.
 
   .. % Patch 1339796
 
+  On Windows, :func:`os.path.expandvars` will now expand environment variables 
+  in the form "%var%", and "~user" will be expanded into the 
+  user's home directory path.  (Contributed by XXX.)
+
+  .. % Patch 957650
+
 * New functions in the :mod:`posix` module: :func:`chflags` and :func:`lchflags`
   are wrappers for the corresponding system calls (where they're available).
   Constants for the flag values are defined in the :mod:`stat` module; some
@@ -217,13 +604,78 @@ complete list of changes, or look through the CVS logs for all the details.
 
   .. % Patch #957003
 
+* The :mod:`tarfile` module now supports POSIX.1-2001 (pax) and
+  POSIX.1-1988 (ustar) format tarfiles, in addition to the GNU tar
+  format that was already supported.  The default format 
+  is GNU tar; specify the ``format`` parameter to open a file
+  using a different format::
+
+    tar = tarfile.open("output.tar", "w", format=tarfile.PAX_FORMAT)
+
+  The new ``errors`` parameter lets you specify an error handling
+  scheme for character conversions: the three standard ways Python can
+  handle errors ``'strict'``, ``'ignore'``, ``'replace'`` , or the
+  special value ``'utf-8'``, which replaces bad characters with their
+  UTF-8 representation.  Character conversions occur because the PAX
+  format supports Unicode filenames, defaulting to UTF-8 encoding.
+
+  The :meth:`TarFile.add` method now accepts a ``exclude`` argument that's
+  a function that can be used to exclude certain filenames from
+  an archive. 
+  The function must take a filename and return true if the file 
+  should be excluded or false if it should be archived.
+  The function is applied to both the name initially passed to :meth:`add`
+  and to the names of files in recursively-added directories.
+  
+  (All changes contributed by Lars Gustäbel).
+
 * An optional ``timeout`` parameter was added to the
   :class:`telnetlib.Telnet` class constructor, specifying a timeout
   measured in seconds.  (Added by Facundo Batista.)
 
-* The :mod:`test.test_support` module now contains a :func:`EnvironmentVarGuard`
+* The :class:`tempfile.NamedTemporaryFile` class usually deletes 
+  the temporary file it created when the file is closed.  This 
+  behaviour can now be changed by passing ``delete=False`` to the 
+  constructor.  (Contributed by Damien Miller.)
+
+  .. % Patch #1537850
+
+* The :mod:`test.test_support` module now contains a
+  :func:`EnvironmentVarGuard`
   context manager that  supports temporarily changing environment variables and
-  automatically restores them to their old values. (Contributed by Brett Cannon.)
+  automatically restores them to their old values. 
+
+  Another context manager, :class:`TransientResource`, can surround calls
+  to resources that may or may not be available; it will catch and
+  ignore a specified list of exceptions.  For example,
+  a network test may ignore certain failures when connecting to an
+  external web site::
+
+      with test_support.TransientResource(IOError, errno=errno.ETIMEDOUT):
+          f = urllib.urlopen('https://sf.net')                         
+          ...
+
+  (Contributed by Brett Cannon.)
+
+* The :mod:`textwrap` module can now preserve existing whitespace 
+  at the beginnings and ends of the newly-created lines
+  by specifying ``drop_whitespace=False``
+  as an argument::
+
+    >>> S = """This  sentence  has a bunch   of    extra   whitespace."""
+    >>> print textwrap.fill(S, width=15)
+    This  sentence
+    has a bunch
+    of    extra
+    whitespace.
+    >>> print textwrap.fill(S, drop_whitespace=False, width=15)
+    This  sentence
+      has a bunch
+       of    extra
+       whitespace.
+    >>> 
+
+  .. % Patch #1581073
 
 * The :mod:`timeit` module now accepts callables as well as strings 
   for the statement being timed and for the setup code.
@@ -235,6 +687,20 @@ complete list of changes, or look through the CVS logs for all the details.
 
   .. % Patch #1533909
 
+* An optional ``timeout`` parameter was added to the
+  :func:`urllib.urlopen` function and the
+  :class:`urllib.ftpwrapper` class constructor, as well as the 
+  :func:`urllib2.urlopen` function.  The parameter specifies a timeout
+  measured in seconds.   For example::
+
+     >>> u = urllib2.urlopen("http://slow.example.com", timeout=3)
+     Traceback (most recent call last):
+       ...
+     urllib2.URLError: <urlopen error timed out>
+     >>>   
+
+  (Added by Facundo Batista.) 
+
 .. % ======================================================================
 .. % whole new modules get described in \subsections here