[Python-3000-checkins] r67148 - in python/branches/py3k: Doc/library/email.parser.rst Doc/library/sqlite3.rst Doc/library/threading.rst Doc/tutorial/controlflow.rst Doc/using/cmdline.rst
georg.brandl
python-3000-checkins at python.org
Fri Nov 7 10:39:56 CET 2008
Author: georg.brandl
Date: Fri Nov 7 10:39:56 2008
New Revision: 67148
Log:
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.
........
Modified:
python/branches/py3k/ (props changed)
python/branches/py3k/Doc/library/email.parser.rst
python/branches/py3k/Doc/library/sqlite3.rst
python/branches/py3k/Doc/library/threading.rst
python/branches/py3k/Doc/tutorial/controlflow.rst
python/branches/py3k/Doc/using/cmdline.rst
Modified: python/branches/py3k/Doc/library/email.parser.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.parser.rst (original)
+++ python/branches/py3k/Doc/library/email.parser.rst Fri Nov 7 10:39:56 2008
@@ -145,6 +145,7 @@
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]])
Modified: python/branches/py3k/Doc/library/sqlite3.rst
==============================================================================
--- python/branches/py3k/Doc/library/sqlite3.rst (original)
+++ python/branches/py3k/Doc/library/sqlite3.rst Fri Nov 7 10:39:56 2008
@@ -62,10 +62,10 @@
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 @@
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 @@
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".
Modified: python/branches/py3k/Doc/library/threading.rst
==============================================================================
--- python/branches/py3k/Doc/library/threading.rst (original)
+++ python/branches/py3k/Doc/library/threading.rst Fri Nov 7 10:39:56 2008
@@ -168,6 +168,163 @@
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 @@
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
Modified: python/branches/py3k/Doc/tutorial/controlflow.rst
==============================================================================
--- python/branches/py3k/Doc/tutorial/controlflow.rst (original)
+++ python/branches/py3k/Doc/tutorial/controlflow.rst Fri Nov 7 10:39:56 2008
@@ -196,6 +196,41 @@
... 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:
Modified: python/branches/py3k/Doc/using/cmdline.rst
==============================================================================
--- python/branches/py3k/Doc/using/cmdline.rst (original)
+++ python/branches/py3k/Doc/using/cmdline.rst Fri Nov 7 10:39:56 2008
@@ -135,6 +135,8 @@
an empty string (``""``) and the current directory will be added to the
start of :data:`sys.path`.
+.. seealso:: :ref:`tut-invoking`
+
Generic options
~~~~~~~~~~~~~~~
More information about the Python-3000-checkins
mailing list