Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

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.
........
This commit is contained in:
Georg Brandl 2008-11-07 09:39:56 +00:00
parent 6570d071fa
commit a971c65f1d
5 changed files with 202 additions and 165 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Doc/library/email.parser.rst
View File

@ -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]])

15
Doc/library/sqlite3.rst
View File

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

314
Doc/library/threading.rst
View File

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

35
Doc/tutorial/controlflow.rst
View File

@ -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:

2
Doc/using/cmdline.rst
View File

@ -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
~~~~~~~~~~~~~~~