Merged revisions 67117-67119,67123-67124,67143 via svnmerge from

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

........
  r67117 | georg.brandl | 2008-11-06 11:17:58 +0100 (Thu, 06 Nov 2008) | 2 lines

  #4268: Use correct module for two toplevel functions.
........
  r67118 | georg.brandl | 2008-11-06 11:19:11 +0100 (Thu, 06 Nov 2008) | 2 lines

  #4267: small fixes in sqlite3 docs.
........
  r67119 | georg.brandl | 2008-11-06 11:20:49 +0100 (Thu, 06 Nov 2008) | 2 lines

  #4245: move Thread section to the top.
........
  r67123 | georg.brandl | 2008-11-06 19:49:15 +0100 (Thu, 06 Nov 2008) | 2 lines

  #4247: add "pass" examples to tutorial.
........
  r67124 | andrew.kuchling | 2008-11-06 20:23:02 +0100 (Thu, 06 Nov 2008) | 1 line

  Fix grammar error; reword two paragraphs
........
  r67143 | georg.brandl | 2008-11-07 09:27:39 +0100 (Fri, 07 Nov 2008) | 2 lines

  Fix syntax.
........

5 files changed, 202 insertions, 165 deletions

diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst
index 7a00912..43f0238 100644
--- a/Doc/library/email.parser.rst
+++ b/Doc/library/email.parser.rst
@@ -145,6 +145,7 @@ Since creating a message object structure from a string or a file object is such
 a common task, two functions are provided as a convenience.  They are available
 in the top-level :mod:`email` package namespace.
 
+.. currentmodule:: email
 
 .. function:: message_from_string(s[, _class[, strict]])
 
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 8ffbce3..5a22ae4 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -62,10 +62,10 @@ may use a different placeholder, such as ``%s`` or ``:1``.) For example::
    c.execute('select * from stocks where symbol=?', t)
 
    # Larger example
-   for t in (('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
+   for t in [('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
              ('2006-04-05', 'BUY', 'MSOFT', 1000, 72.00),
              ('2006-04-06', 'SELL', 'IBM', 500, 53.00),
-            ):
+            ]:
        c.execute('insert into stocks values (?,?,?,?,?)', t)
 
 To retrieve data after executing a SELECT statement, you can either treat the
@@ -421,10 +421,9 @@ Connection Objects
       import sqlite3, os
 
       con = sqlite3.connect('existing_db.db')
-      full_dump = os.linesep.join(con.iterdump())
-      f = open('dump.sql', 'w')
-      f.writelines(full_dump)
-      f.close()
+      with open('dump.sql', 'w') as f:
+          for line in con.iterdump():
+              f.write('%s\n' % line)
 
 
 .. _sqlite3-cursor-objects:
@@ -800,8 +799,8 @@ call, or via the :attr:`isolation_level` property of connections.
 If you want **autocommit mode**, then set :attr:`isolation_level` to None.
 
 Otherwise leave it at its default, which will result in a plain "BEGIN"
-statement, or set it to one of SQLite's supported isolation levels: DEFERRED,
-IMMEDIATE or EXCLUSIVE.
+statement, or set it to one of SQLite's supported isolation levels: "DEFERRED",
+"IMMEDIATE" or "EXCLUSIVE".
 
 
 
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 9cc62be..01e7136 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -168,6 +168,163 @@ when implemented, are mapped to module-level functions.
 All of the methods described below are executed atomically.
 
 
+.. _thread-objects:
+
+Thread Objects
+--------------
+
+This class represents an activity that is run in a separate thread of control.
+There are two ways to specify the activity: by passing a callable object to the
+constructor, or by overriding the :meth:`run` method in a subclass.  No other
+methods (except for the constructor) should be overridden in a subclass.  In
+other words,  *only*  override the :meth:`__init__` and :meth:`run` methods of
+this class.
+
+Once a thread object is created, its activity must be started by calling the
+thread's :meth:`start` method.  This invokes the :meth:`run` method in a
+separate thread of control.
+
+Once the thread's activity is started, the thread is considered 'alive'. It
+stops being alive when its :meth:`run` method terminates -- either normally, or
+by raising an unhandled exception.  The :meth:`is_alive` method tests whether the
+thread is alive.
+
+Other threads can call a thread's :meth:`join` method.  This blocks the calling
+thread until the thread whose :meth:`join` method is called is terminated.
+
+A thread has a name.  The name can be passed to the constructor, and read or
+changed through the :attr:`name` attribute.
+
+A thread can be flagged as a "daemon thread".  The significance of this flag is
+that the entire Python program exits when only daemon threads are left.  The
+initial value is inherited from the creating thread.  The flag can be set
+through the :attr:`daemon` attribute.
+
+There is a "main thread" object; this corresponds to the initial thread of
+control in the Python program.  It is not a daemon thread.
+
+There is the possibility that "dummy thread objects" are created. These are
+thread objects corresponding to "alien threads", which are threads of control
+started outside the threading module, such as directly from C code.  Dummy
+thread objects have limited functionality; they are always considered alive and
+daemonic, and cannot be :meth:`join`\ ed.  They are never deleted, since it is
+impossible to detect the termination of alien threads.
+
+
+.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={})
+
+   This constructor should always be called with keyword arguments.  Arguments are:
+
+   *group* should be ``None``; reserved for future extension when a
+   :class:`ThreadGroup` class is implemented.
+
+   *target* is the callable object to be invoked by the :meth:`run` method.
+   Defaults to ``None``, meaning nothing is called.
+
+   *name* is the thread name.  By default, a unique name is constructed of the form
+   "Thread-*N*" where *N* is a small decimal number.
+
+   *args* is the argument tuple for the target invocation.  Defaults to ``()``.
+
+   *kwargs* is a dictionary of keyword arguments for the target invocation.
+   Defaults to ``{}``.
+
+   If the subclass overrides the constructor, it must make sure to invoke the base
+   class constructor (``Thread.__init__()``) before doing anything else to the
+   thread.
+
+
+.. method:: Thread.start()
+
+   Start the thread's activity.
+
+   It must be called at most once per thread object.  It arranges for the object's
+   :meth:`run` method to be invoked in a separate thread of control.
+
+   This method will raise a :exc:`RuntimeException` if called more than once on the
+   same thread object.
+
+
+.. method:: Thread.run()
+
+   Method representing the thread's activity.
+
+   You may override this method in a subclass.  The standard :meth:`run` method
+   invokes the callable object passed to the object's constructor as the *target*
+   argument, if any, with sequential and keyword arguments taken from the *args*
+   and *kwargs* arguments, respectively.
+
+
+.. method:: Thread.join([timeout])
+
+   Wait until the thread terminates. This blocks the calling thread until the
+   thread whose :meth:`join` method is called terminates -- either normally or
+   through an unhandled exception -- or until the optional timeout occurs.
+
+   When the *timeout* argument is present and not ``None``, it should be a floating
+   point number specifying a timeout for the operation in seconds (or fractions
+   thereof). As :meth:`join` always returns ``None``, you must call :meth:`is_alive`
+   after :meth:`join` to decide whether a timeout happened -- if the thread is
+   still alive, the :meth:`join` call timed out.
+
+   When the *timeout* argument is not present or ``None``, the operation will block
+   until the thread terminates.
+
+   A thread can be :meth:`join`\ ed many times.
+
+   :meth:`join` raises a :exc:`RuntimeError` if an attempt is made to join
+   the current thread as that would cause a deadlock. It is also an error to
+   :meth:`join` a thread before it has been started and attempts to do so
+   raises the same exception.
+
+
+.. method:: Thread.getName()
+            Thread.setName()
+
+   Old API for :attr:`~Thread.name`.
+
+
+.. attribute:: Thread.name
+
+   A string used for identification purposes only. It has no semantics.
+   Multiple threads may be given the same name.  The initial name is set by the
+   constructor.
+
+
+.. attribute:: Thread.ident
+
+   The 'thread identifier' of this thread or ``None`` if the thread has not been
+   started.  This is a nonzero integer.  See the :func:`thread.get_ident()`
+   function.  Thread identifiers may be recycled when a thread exits and another
+   thread is created.  The identifier is available even after the thread has
+   exited.
+
+
+.. method:: Thread.is_alive()
+
+   Return whether the thread is alive.
+
+   Roughly, a thread is alive from the moment the :meth:`start` method returns
+   until its :meth:`run` method terminates. The module function :func:`enumerate`
+   returns a list of all alive threads.
+
+
+.. method:: Thread.isDaemon()
+            Thread.setDaemon()
+
+   Old API for :attr:`~Thread.daemon`.
+
+
+.. attribute:: Thread.daemon
+
+   The thread's daemon flag. This must be set before :meth:`start` is called,
+   otherwise :exc:`RuntimeError` is raised.
+
+   The initial value is inherited from the creating thread.
+
+   The entire Python program exits when no alive non-daemon threads are left.
+
+
 .. _lock-objects:
 
 Lock Objects
@@ -525,163 +682,6 @@ An event object manages an internal flag that can be set to true with the
    thereof).
 
 
-.. _thread-objects:
-
-Thread Objects
---------------
-
-This class represents an activity that is run in a separate thread of control.
-There are two ways to specify the activity: by passing a callable object to the
-constructor, or by overriding the :meth:`run` method in a subclass.  No other
-methods (except for the constructor) should be overridden in a subclass.  In
-other words,  *only*  override the :meth:`__init__` and :meth:`run` methods of
-this class.
-
-Once a thread object is created, its activity must be started by calling the
-thread's :meth:`start` method.  This invokes the :meth:`run` method in a
-separate thread of control.
-
-Once the thread's activity is started, the thread is considered 'alive'. It
-stops being alive when its :meth:`run` method terminates -- either normally, or
-by raising an unhandled exception.  The :meth:`is_alive` method tests whether the
-thread is alive.
-
-Other threads can call a thread's :meth:`join` method.  This blocks the calling
-thread until the thread whose :meth:`join` method is called is terminated.
-
-A thread has a name.  The name can be passed to the constructor, and read or
-changed through the :attr:`name` attribute.
-
-A thread can be flagged as a "daemon thread".  The significance of this flag is
-that the entire Python program exits when only daemon threads are left.  The
-initial value is inherited from the creating thread.  The flag can be set
-through the :attr:`daemon` attribute.
-
-There is a "main thread" object; this corresponds to the initial thread of
-control in the Python program.  It is not a daemon thread.
-
-There is the possibility that "dummy thread objects" are created. These are
-thread objects corresponding to "alien threads", which are threads of control
-started outside the threading module, such as directly from C code.  Dummy
-thread objects have limited functionality; they are always considered alive and
-daemonic, and cannot be :meth:`join`\ ed.  They are never deleted, since it is
-impossible to detect the termination of alien threads.
-
-
-.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={})
-
-   This constructor should always be called with keyword arguments.  Arguments are:
-
-   *group* should be ``None``; reserved for future extension when a
-   :class:`ThreadGroup` class is implemented.
-
-   *target* is the callable object to be invoked by the :meth:`run` method.
-   Defaults to ``None``, meaning nothing is called.
-
-   *name* is the thread name.  By default, a unique name is constructed of the form
-   "Thread-*N*" where *N* is a small decimal number.
-
-   *args* is the argument tuple for the target invocation.  Defaults to ``()``.
-
-   *kwargs* is a dictionary of keyword arguments for the target invocation.
-   Defaults to ``{}``.
-
-   If the subclass overrides the constructor, it must make sure to invoke the base
-   class constructor (``Thread.__init__()``) before doing anything else to the
-   thread.
-
-
-.. method:: Thread.start()
-
-   Start the thread's activity.
-
-   It must be called at most once per thread object.  It arranges for the object's
-   :meth:`run` method to be invoked in a separate thread of control.
-
-   This method will raise a :exc:`RuntimeException` if called more than once on the
-   same thread object.
-
-
-.. method:: Thread.run()
-
-   Method representing the thread's activity.
-
-   You may override this method in a subclass.  The standard :meth:`run` method
-   invokes the callable object passed to the object's constructor as the *target*
-   argument, if any, with sequential and keyword arguments taken from the *args*
-   and *kwargs* arguments, respectively.
-
-
-.. method:: Thread.join([timeout])
-
-   Wait until the thread terminates. This blocks the calling thread until the
-   thread whose :meth:`join` method is called terminates -- either normally or
-   through an unhandled exception -- or until the optional timeout occurs.
-
-   When the *timeout* argument is present and not ``None``, it should be a floating
-   point number specifying a timeout for the operation in seconds (or fractions
-   thereof). As :meth:`join` always returns ``None``, you must call :meth:`is_alive`
-   after :meth:`join` to decide whether a timeout happened -- if the thread is
-   still alive, the :meth:`join` call timed out.
-
-   When the *timeout* argument is not present or ``None``, the operation will block
-   until the thread terminates.
-
-   A thread can be :meth:`join`\ ed many times.
-
-   :meth:`join` raises a :exc:`RuntimeError` if an attempt is made to join
-   the current thread as that would cause a deadlock. It is also an error to
-   :meth:`join` a thread before it has been started and attempts to do so
-   raises the same exception.
-
-
-.. method:: Thread.getName()
-            Thread.setName()
-
-   Old API for :attr:`~Thread.name`.
-
-
-.. attribute:: Thread.name
-
-   A string used for identification purposes only. It has no semantics.
-   Multiple threads may be given the same name.  The initial name is set by the
-   constructor.
-
-
-.. attribute:: Thread.ident
-
-   The 'thread identifier' of this thread or ``None`` if the thread has not been
-   started.  This is a nonzero integer.  See the :func:`thread.get_ident()`
-   function.  Thread identifiers may be recycled when a thread exits and another
-   thread is created.  The identifier is available even after the thread has
-   exited.
-
-
-.. method:: Thread.is_alive()
-
-   Return whether the thread is alive.
-
-   Roughly, a thread is alive from the moment the :meth:`start` method returns
-   until its :meth:`run` method terminates. The module function :func:`enumerate`
-   returns a list of all alive threads.
-
-
-.. method:: Thread.isDaemon()
-            Thread.setDaemon()
-
-   Old API for :attr:`~Thread.daemon`.
-
-
-.. attribute:: Thread.daemon
-
-   The thread's daemon flag. This must be set before :meth:`start` is called,
-   otherwise :exc:`RuntimeError` is raised.
-
-   The initial value is inherited from the creating thread.
-
-   The entire Python program exits when no alive non-daemon threads are left.
-
-
 .. _timer-objects:
 
 Timer Objects
diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst
index 5fdddcb..2a55cf1 100644
--- a/Doc/tutorial/controlflow.rst
+++ b/Doc/tutorial/controlflow.rst
@@ -196,6 +196,41 @@ required syntactically but the program requires no action. For example::
    ...     pass  # Busy-wait for keyboard interrupt (Ctrl+C)
    ... 
 
+This is commonly used for creating minimal classes such as exceptions, or
+for ignoring unwanted exceptions::
+
+   >>> class ParserError(Exception):
+   ...     pass
+   ... 
+   >>> try:
+   ...     import audioop
+   ... except ImportError:
+   ...     pass
+   ... 
+
+Another place :keyword:`pass` can be used is as a place-holder for a function or
+conditional body when you are working on new code, allowing you to keep
+thinking at a more abstract level.  However, as :keyword:`pass` is silently
+ignored, a better choice may be to raise a :exc:`NotImplementedError`
+exception::
+
+   >>> def initlog(*args):
+   ...     raise NotImplementedError   # Open logfile if not already open
+   ...     if not logfp:
+   ...         raise NotImplementedError  # Set up dummy log back-end
+   ...     raise NotImplementedError('Call log initialization handler')
+   ... 
+
+If :keyword:`pass` were used here and you later ran tests, they may fail
+without indicating why.  Using :exc:`NotImplementedError` causes this code
+to raise an exception, telling you exactly where the incomplete code 
+is.  Note the two calling styles of the exceptions above.
+The first style, with no message but with an accompanying comment, 
+lets you easily leave the comment when you remove the exception,
+which ideally would be a good description for
+the block of code the exception is a placeholder for.  However, the 
+third example, providing a message for the exception, will produce 
+a more useful traceback.
 
 .. _tut-functions:
 
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 167dc10..f0e533c 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -135,6 +135,8 @@ If no interface option is given, :option:`-i` is implied, ``sys.argv[0]`` is
 an empty string (``""``) and the current directory will be added to the
 start of :data:`sys.path`.
 
+.. seealso::  :ref:`tut-invoking`
+
 
 Generic options
 ~~~~~~~~~~~~~~~