Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
................
r66801 | andrew.kuchling | 2008-10-04 23:51:59 +0200 (Sat, 04 Oct 2008) | 1 line
Punctuation fix; expand dict.update docstring to be clearer
................
r66803 | benjamin.peterson | 2008-10-05 00:15:31 +0200 (Sun, 05 Oct 2008) | 1 line
fix typo
................
r66804 | andrew.kuchling | 2008-10-05 02:11:56 +0200 (Sun, 05 Oct 2008) | 1 line
#1415508 from Rocky Bernstein: add docstrings for enable_interspersed_args(), disable_interspersed_args()
................
r66813 | andrew.kuchling | 2008-10-06 14:07:04 +0200 (Mon, 06 Oct 2008) | 3 lines
Per Greg Ward, optparse is no longer being externally maintained.
I'll look at the bugs in the Optik bug tracker and copy them to the Python bug
tracker if they're still relevant.
................
r66854 | georg.brandl | 2008-10-08 19:20:20 +0200 (Wed, 08 Oct 2008) | 2 lines
#4059: patch up some sqlite docs.
................
r66855 | georg.brandl | 2008-10-08 19:30:55 +0200 (Wed, 08 Oct 2008) | 2 lines
#4058: fix some whatsnew markup.
................
r66856 | georg.brandl | 2008-10-08 20:47:17 +0200 (Wed, 08 Oct 2008) | 3 lines
#3935: properly support list subclasses in the C impl. of bisect.
Patch reviewed by Raymond.
................
r66866 | benjamin.peterson | 2008-10-09 22:54:43 +0200 (Thu, 09 Oct 2008) | 1 line
update paragraph about __future__ for 2.6
................
r66870 | armin.rigo | 2008-10-10 10:40:44 +0200 (Fri, 10 Oct 2008) | 2 lines
Typo: "ThreadError" is the name in the C source.
................
r66871 | benjamin.peterson | 2008-10-10 22:38:49 +0200 (Fri, 10 Oct 2008) | 1 line
fix a small typo
................
r66872 | benjamin.peterson | 2008-10-10 22:51:37 +0200 (Fri, 10 Oct 2008) | 1 line
talk about how you can unzip with zip
................
r66874 | benjamin.peterson | 2008-10-11 00:23:41 +0200 (Sat, 11 Oct 2008) | 1 line
PyGILState_Acquire -> PyGILState_Ensure
................
r66887 | benjamin.peterson | 2008-10-13 23:51:40 +0200 (Mon, 13 Oct 2008) | 1 line
document how to disable fixers
................
r66903 | benjamin.peterson | 2008-10-15 22:34:09 +0200 (Wed, 15 Oct 2008) | 1 line
don't recurse into directories that start with '.'
................
r66905 | benjamin.peterson | 2008-10-15 23:05:55 +0200 (Wed, 15 Oct 2008) | 1 line
support the optional line argument for idle
................
r66911 | benjamin.peterson | 2008-10-16 01:10:28 +0200 (Thu, 16 Oct 2008) | 41 lines
Merged revisions 66805,66841,66860,66884-66886,66893,66907,66910 via svnmerge from
svn+ssh://pythondev@svn.python.org/sandbox/trunk/2to3/lib2to3
........
r66805 | benjamin.peterson | 2008-10-04 20:11:02 -0500 (Sat, 04 Oct 2008) | 1 line
mention what the fixes directory is for
........
r66841 | benjamin.peterson | 2008-10-07 17:48:12 -0500 (Tue, 07 Oct 2008) | 1 line
use assertFalse and assertTrue
........
r66860 | benjamin.peterson | 2008-10-08 16:05:07 -0500 (Wed, 08 Oct 2008) | 1 line
instead of abusing the pattern matcher, use start_tree to find a next binding
........
r66884 | benjamin.peterson | 2008-10-13 15:50:30 -0500 (Mon, 13 Oct 2008) | 1 line
don't print tokens to stdout when -v is given
........
r66885 | benjamin.peterson | 2008-10-13 16:28:57 -0500 (Mon, 13 Oct 2008) | 1 line
add the -x option to disable fixers
........
r66886 | benjamin.peterson | 2008-10-13 16:33:53 -0500 (Mon, 13 Oct 2008) | 1 line
cut down on some crud
........
r66893 | benjamin.peterson | 2008-10-14 17:16:54 -0500 (Tue, 14 Oct 2008) | 1 line
add an optional set literal fixer
........
r66907 | benjamin.peterson | 2008-10-15 16:59:41 -0500 (Wed, 15 Oct 2008) | 1 line
don't write backup files by default
........
r66910 | benjamin.peterson | 2008-10-15 17:43:10 -0500 (Wed, 15 Oct 2008) | 1 line
add the -n option; it stops backupfiles from being written
........
................
r66913 | benjamin.peterson | 2008-10-16 20:52:14 +0200 (Thu, 16 Oct 2008) | 1 line
document that deque indexing is O(n) #4123
................
r66927 | andrew.kuchling | 2008-10-16 22:15:47 +0200 (Thu, 16 Oct 2008) | 1 line
Fix wording (2.6.1 backport candidate)
................
r66932 | benjamin.peterson | 2008-10-16 23:09:28 +0200 (Thu, 16 Oct 2008) | 1 line
check for error conditions in _json #3623
................
r66938 | benjamin.peterson | 2008-10-16 23:27:54 +0200 (Thu, 16 Oct 2008) | 1 line
fix possible ref leak
................
r66942 | benjamin.peterson | 2008-10-16 23:48:06 +0200 (Thu, 16 Oct 2008) | 1 line
fix more possible ref leaks in _json and use Py_CLEAR
................
r66962 | benjamin.peterson | 2008-10-17 22:01:01 +0200 (Fri, 17 Oct 2008) | 1 line
clarify CALL_FUNCTION #4141
................
r66964 | georg.brandl | 2008-10-17 23:41:49 +0200 (Fri, 17 Oct 2008) | 2 lines
Fix duplicate word.
................
r66973 | armin.ronacher | 2008-10-19 10:27:43 +0200 (Sun, 19 Oct 2008) | 3 lines
Fixed #4067 by implementing _attributes and _fields for the AST root node.
................
r66974 | benjamin.peterson | 2008-10-19 15:59:01 +0200 (Sun, 19 Oct 2008) | 1 line
fix compiler warning
................
r66977 | benjamin.peterson | 2008-10-19 21:39:16 +0200 (Sun, 19 Oct 2008) | 1 line
mention -n
................
r66992 | benjamin.peterson | 2008-10-21 22:51:13 +0200 (Tue, 21 Oct 2008) | 1 line
make sure to call iteritems()
................
r66998 | benjamin.peterson | 2008-10-22 22:57:43 +0200 (Wed, 22 Oct 2008) | 1 line
fix a few typos
................
r66999 | benjamin.peterson | 2008-10-22 23:05:30 +0200 (Wed, 22 Oct 2008) | 1 line
and another typo...
................
r67002 | hirokazu.yamamoto | 2008-10-23 02:37:33 +0200 (Thu, 23 Oct 2008) | 1 line
Issue #4183: Some tests didn't run with pickle.HIGHEST_PROTOCOL.
................
r67005 | walter.doerwald | 2008-10-23 15:11:39 +0200 (Thu, 23 Oct 2008) | 2 lines
Use the correct names of the stateless codec functions (Fixes issue 4178).
................
r67007 | benjamin.peterson | 2008-10-23 23:43:48 +0200 (Thu, 23 Oct 2008) | 1 line
only nonempty __slots__ don't work
................
r67028 | benjamin.peterson | 2008-10-26 01:27:07 +0200 (Sun, 26 Oct 2008) | 1 line
don't use a catch-all
................
r67040 | armin.rigo | 2008-10-28 18:01:21 +0100 (Tue, 28 Oct 2008) | 5 lines
Fix one of the tests: it relied on being present in an "output test" in
order to actually test what it was supposed to test, i.e. that the code
in the __del__ method did not crash. Use instead the new helper
test_support.captured_output().
................
r67041 | benjamin.peterson | 2008-10-29 21:33:00 +0100 (Wed, 29 Oct 2008) | 1 line
mention the version gettempdir() was added
................
r67044 | amaury.forgeotdarc | 2008-10-30 00:15:57 +0100 (Thu, 30 Oct 2008) | 3 lines
Correct error message in io.open():
closefd=True is the only accepted value with a file name.
................
r67070 | benjamin.peterson | 2008-10-31 21:41:44 +0100 (Fri, 31 Oct 2008) | 1 line
rephrase has_key doc
................
r67089 | benjamin.peterson | 2008-11-03 21:43:20 +0100 (Mon, 03 Nov 2008) | 1 line
clarify by splitting into multiple paragraphs
................
r67091 | benjamin.peterson | 2008-11-03 23:34:57 +0100 (Mon, 03 Nov 2008) | 1 line
move a FileIO test to test_fileio
................
r67101 | georg.brandl | 2008-11-04 21:49:35 +0100 (Tue, 04 Nov 2008) | 2 lines
#4167: fix markup glitches.
................
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
................
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 1a43be5..85860e5 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -180,6 +180,166 @@
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:`isAlive`
+ 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.
+
+ .. versionadded:: 2.6
+
+
+.. method:: Thread.is_alive()
+ Thread.isAlive()
+
+ 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
@@ -539,166 +699,6 @@
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:`isAlive`
- 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.
-
- .. versionadded:: 2.6
-
-
-.. method:: Thread.is_alive()
- Thread.isAlive()
-
- 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