Add various items

1 files changed, 428 insertions, 0 deletions

diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst
index 6c799fd..0216589 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,10 +604,37 @@ complete list of changes, or look through the CVS logs for all the details.
 
   .. % Patch #957003
 
+* 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
+
 * An optional ``timeout`` parameter was added to the
   :class:`telnetlib.Telnet` class constructor, specifying a timeout
   measured in seconds.  (Added by Facundo Batista.)
 
+* 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.)
@@ -235,6 +649,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