diff options
| -rw-r--r-- | Doc/library/email.parser.rst | 1 | ||||
| -rw-r--r-- | Doc/library/sqlite3.rst | 15 | ||||
| -rw-r--r-- | Doc/library/threading.rst | 314 | ||||
| -rw-r--r-- | Doc/tutorial/controlflow.rst | 35 | ||||
| -rw-r--r-- | Doc/using/cmdline.rst | 2 |
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 ~~~~~~~~~~~~~~~ |