Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74210 | georg.brandl | 2009-07-26 16:44:23 +0200 (So, 26 Jul 2009) | 1 line
Move member descriptions inside the classes.
........
r74239 | georg.brandl | 2009-07-28 20:55:32 +0200 (Di, 28 Jul 2009) | 1 line
Clarify quote_plus() usage.
........
r74252 | georg.brandl | 2009-07-29 18:06:31 +0200 (Mi, 29 Jul 2009) | 1 line
#6593: fix link targets.
........
r74253 | georg.brandl | 2009-07-29 18:09:17 +0200 (Mi, 29 Jul 2009) | 1 line
#6591: add reference to ioctl in fcntl module for platforms other than Windows.
........
r74256 | georg.brandl | 2009-07-29 18:32:30 +0200 (Mi, 29 Jul 2009) | 1 line
#6336: Add nb_divide.
........
r74258 | georg.brandl | 2009-07-29 18:57:05 +0200 (Mi, 29 Jul 2009) | 1 line
Add a link to readline, and mention IPython and bpython.
........
r74259 | georg.brandl | 2009-07-29 19:07:21 +0200 (Mi, 29 Jul 2009) | 1 line
Fix some markup and small factual glitches found by M. Markert.
........
r74260 | georg.brandl | 2009-07-29 19:15:20 +0200 (Mi, 29 Jul 2009) | 1 line
Fix a few markup glitches.
........
r74261 | georg.brandl | 2009-07-29 19:50:25 +0200 (Mi, 29 Jul 2009) | 1 line
Rewrite the section about classes a bit; mostly tidbits, and a larger update to the section about "private" variables to reflect the Pythonic consensus better.
........
r74332 | georg.brandl | 2009-08-06 19:23:21 +0200 (Do, 06 Aug 2009) | 1 line
Fix punctuation and one copy-paste error.
........
r74333 | georg.brandl | 2009-08-06 19:43:55 +0200 (Do, 06 Aug 2009) | 1 line
#6658: fix two typos.
........
r74404 | georg.brandl | 2009-08-13 14:05:52 +0200 (Do, 13 Aug 2009) | 1 line
Use locale.format_string() for more than one specifier.
........
r74411 | georg.brandl | 2009-08-13 14:57:25 +0200 (Do, 13 Aug 2009) | 2 lines
Remove potentially confusing sentence in __mangling description.
........
r74445 | vinay.sajip | 2009-08-14 13:33:54 +0200 (Fr, 14 Aug 2009) | 1 line
Added versionchanged notices for optional 'delay' parameter to file handler classes.
........
r74465 | vinay.sajip | 2009-08-16 01:23:12 +0200 (So, 16 Aug 2009) | 1 line
Added section on logging to one file from multiple processes.
........
r74467 | vinay.sajip | 2009-08-16 01:34:47 +0200 (So, 16 Aug 2009) | 1 line
Refined section on logging to one file from multiple processes.
........
r74488 | vinay.sajip | 2009-08-17 15:14:37 +0200 (Mo, 17 Aug 2009) | 1 line
Further refined section on logging to one file from multiple processes.
........
diff --git a/Doc/library/gettext.rst b/Doc/library/gettext.rst
index 405a382..f64631f 100644
--- a/Doc/library/gettext.rst
+++ b/Doc/library/gettext.rst
@@ -208,10 +208,10 @@
This installs the function :func:`_` in Python's builtins namespace, based on
*domain*, *localedir*, and *codeset* which are passed to the function
:func:`translation`. The *unicode* flag is passed to the resulting translation
- object's :meth:`install` method.
+ object's :meth:`~NullTranslations.install` method.
For the *names* parameter, please see the description of the translation
- object's :meth:`install` method.
+ object's :meth:`~NullTranslations.install` method.
As seen below, you usually mark the strings in your application that are
candidates for translation, by wrapping them in a call to the :func:`_`
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 512e105..5ccea13 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -1321,6 +1321,31 @@
The :class:`LoggerAdapter` class was not present in previous versions.
+.. _multiple-processes:
+
+Logging to a single file from multiple processes
+------------------------------------------------
+
+Although logging is thread-safe, and logging to a single file from multiple
+threads in a single process *is* supported, logging to a single file from
+*multiple processes* is *not* supported, because there is no standard way to
+serialize access to a single file across multiple processes in Python. If you
+need to log to a single file from multiple processes, the best way of doing
+this is to have all the processes log to a :class:`SocketHandler`, and have a
+separate process which implements a socket server which reads from the socket
+and logs to file. (If you prefer, you can dedicate one thread in one of the
+existing processes to perform this function.) The following section documents
+this approach in more detail and includes a working socket receiver which can
+be used as a starting point for you to adapt in your own applications.
+
+If you are using a recent version of Python which includes the
+:mod:`multiprocessing` module, you can write your own handler which uses the
+:class:`Lock` class from this module to serialize access to the file from
+your processes. The existing :class:`FileHandler` and subclasses do not make
+use of :mod:`multiprocessing` at present, though they may do so in the future.
+Note that at present, the :mod:`multiprocessing` module does not provide
+working lock functionality on all platforms (see
+http://bugs.python.org/issue3770).
.. _network-logging:
@@ -1613,6 +1638,8 @@
with that encoding. If *delay* is true, then file opening is deferred until the
first call to :meth:`emit`. By default, the file grows indefinitely.
+ .. versionchanged:: 2.6
+ *delay* was added.
.. method:: close()
@@ -1661,6 +1688,9 @@
with that encoding. If *delay* is true, then file opening is deferred until the
first call to :meth:`emit`. By default, the file grows indefinitely.
+ .. versionchanged:: 2.6
+ *delay* was added.
+
.. method:: emit(record)
@@ -1698,6 +1728,8 @@
:file:`app.log.1`, :file:`app.log.2`, etc. exist, then they are renamed to
:file:`app.log.2`, :file:`app.log.3` etc. respectively.
+ .. versionchanged:: 2.6
+ *delay* was added.
.. method:: doRollover()
@@ -1757,6 +1789,11 @@
one is deleted. The deletion logic uses the interval to determine which
files to delete, so changing the interval may leave old files lying around.
+ If *delay* is true, then file opening is deferred until the first call to
+ :meth:`emit`.
+
+ .. versionchanged:: 2.6
+ *delay* was added.
.. method:: doRollover()
diff --git a/Doc/library/select.rst b/Doc/library/select.rst
index 351ecfa..0e6e4af 100644
--- a/Doc/library/select.rst
+++ b/Doc/library/select.rst
@@ -307,7 +307,7 @@
.. attribute:: kevent.filter
- Name of the kernel filter
+ Name of the kernel filter.
+---------------------------+---------------------------------------------+
| Constant | Meaning |
@@ -316,7 +316,7 @@
| | there is data available to read |
+---------------------------+---------------------------------------------+
| :const:`KQ_FILTER_WRITE` | Takes a descriptor and returns whenever |
- | | there is data available to read |
+ | | there is data available to write |
+---------------------------+---------------------------------------------+
| :const:`KQ_FILTER_AIO` | AIO requests |
+---------------------------+---------------------------------------------+
@@ -336,7 +336,7 @@
.. attribute:: kevent.flags
- Filter action
+ Filter action.
+---------------------------+---------------------------------------------+
| Constant | Meaning |
@@ -365,10 +365,9 @@
.. attribute:: kevent.fflags
- Filter specific flags
+ Filter specific flags.
-
- :const:`KQ_FILTER_READ` and :const:`KQ_FILTER_WRITE` filter flags
+ :const:`KQ_FILTER_READ` and :const:`KQ_FILTER_WRITE` filter flags:
+----------------------------+--------------------------------------------+
| Constant | Meaning |
@@ -376,8 +375,7 @@
| :const:`KQ_NOTE_LOWAT` | low water mark of a socket buffer |
+----------------------------+--------------------------------------------+
-
- :const:`KQ_FILTER_VNODE` filter flags
+ :const:`KQ_FILTER_VNODE` filter flags:
+----------------------------+--------------------------------------------+
| Constant | Meaning |
@@ -397,8 +395,7 @@
| :const:`KQ_NOTE_REVOKE` | access to the file was revoked |
+----------------------------+--------------------------------------------+
-
- :const:`KQ_FILTER_PROC` filter flags
+ :const:`KQ_FILTER_PROC` filter flags:
+----------------------------+--------------------------------------------+
| Constant | Meaning |
@@ -421,7 +418,7 @@
| :const:`KQ_NOTE_TRACKERR` | unable to attach to a child |
+----------------------------+--------------------------------------------+
- :const:`KQ_FILTER_NETDEV` filter flags [not available on Mac OS X]
+ :const:`KQ_FILTER_NETDEV` filter flags (not available on Mac OS X):
+----------------------------+--------------------------------------------+
| Constant | Meaning |
@@ -436,9 +433,9 @@
.. attribute:: kevent.data
- Filter specific data
+ Filter specific data.
.. attribute:: kevent.udata
- User defined value
+ User defined value.
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 97fe268..8055ab4 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -604,6 +604,9 @@
The :meth:`ioctl` method is a limited interface to the WSAIoctl system
interface. Please refer to the MSDN documentation for more information.
+ On other platforms, the generic :func:`fcntl.fcntl` and :func:`fcntl.ioctl`
+ functions may be used; they accept a socket object as their first argument.
+
.. versionadded:: 2.6
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 51879a0..412000e 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -231,7 +231,8 @@
.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={})
- This constructor should always be called with keyword arguments. Arguments are:
+ 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.
@@ -239,112 +240,104 @@
*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.
+ *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.
+ 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:: start()
-.. method:: Thread.start()
+ Start the thread's activity.
- 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.
- 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.
- This method will raise a :exc:`RuntimeException` if called more than once on the
- same thread object.
+ .. method:: run()
+ Method representing the thread's activity.
-.. method:: Thread.run()
+ 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 representing the thread's activity.
+ .. method:: join([timeout])
- 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.
+ 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.
-.. method:: Thread.join([timeout])
+ When the *timeout* argument is not present or ``None``, the operation will
+ block until the thread terminates.
- 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.
+ A thread can be :meth:`join`\ ed many times.
- 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.
+ :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.
- When the *timeout* argument is not present or ``None``, the operation will block
- until the thread terminates.
+ .. method:: getName()
+ setName()
- A thread can be :meth:`join`\ ed many times.
+ Old API for :attr:`~Thread.name`.
- :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.
+ .. attribute:: 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.
-.. method:: Thread.getName()
- Thread.setName()
+ .. attribute:: ident
- Old API for :attr:`~Thread.name`.
+ 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
-.. attribute:: Thread.name
+ .. method:: is_alive()
+ isAlive()
- 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.
+ 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.
-.. attribute:: Thread.ident
+ .. method:: isDaemon()
+ setDaemon()
- 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.
+ Old API for :attr:`~Thread.daemon`.
- .. versionadded:: 2.6
+ .. attribute:: daemon
+ A boolean value indicating whether this thread is a daemon thread (True)
+ or not (False). This must be set before :meth:`start` is called,
+ otherwise :exc:`RuntimeError` is raised. Its initial value is inherited
+ from the creating thread; the main thread is not a daemon thread and
+ therefore all threads created in the main thread default to :attr:`daemon`
+ = ``False``.
-.. 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
-
- A boolean value indicating whether this thread is a daemon thread (True) or
- not (False). This must be set before :meth:`start` is called, otherwise
- :exc:`RuntimeError` is raised. Its initial value is inherited from the
- creating thread; the main thread is not a daemon thread and therefore all
- threads created in the main thread default to :attr:`daemon` = ``False``.
-
- The entire Python program exits when no alive non-daemon threads are left.
+ The entire Python program exits when no alive non-daemon threads are left.
.. _lock-objects:
@@ -515,70 +508,66 @@
.. class:: Condition([lock])
- If the *lock* argument is given and not ``None``, it must be a :class:`Lock` or
- :class:`RLock` object, and it is used as the underlying lock. Otherwise, a new
- :class:`RLock` object is created and used as the underlying lock.
+ If the *lock* argument is given and not ``None``, it must be a :class:`Lock`
+ or :class:`RLock` object, and it is used as the underlying lock. Otherwise,
+ a new :class:`RLock` object is created and used as the underlying lock.
+ .. method:: acquire(*args)
-.. method:: Condition.acquire(*args)
+ Acquire the underlying lock. This method calls the corresponding method on
+ the underlying lock; the return value is whatever that method returns.
- Acquire the underlying lock. This method calls the corresponding method on the
- underlying lock; the return value is whatever that method returns.
+ .. method:: release()
+ Release the underlying lock. This method calls the corresponding method on
+ the underlying lock; there is no return value.
-.. method:: Condition.release()
+ .. method:: wait([timeout])
- Release the underlying lock. This method calls the corresponding method on the
- underlying lock; there is no return value.
+ Wait until notified or until a timeout occurs. If the calling thread has not
+ acquired the lock when this method is called, a :exc:`RuntimeError` is raised.
+ This method releases the underlying lock, and then blocks until it is
+ awakened by a :meth:`notify` or :meth:`notifyAll` call for the same
+ condition variable in another thread, or until the optional timeout
+ occurs. Once awakened or timed out, it re-acquires the lock and returns.
-.. method:: Condition.wait([timeout])
+ 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).
- Wait until notified or until a timeout occurs. If the calling thread has not
- acquired the lock when this method is called, a :exc:`RuntimeError` is raised.
+ When the underlying lock is an :class:`RLock`, it is not released using
+ its :meth:`release` method, since this may not actually unlock the lock
+ when it was acquired multiple times recursively. Instead, an internal
+ interface of the :class:`RLock` class is used, which really unlocks it
+ even when it has been recursively acquired several times. Another internal
+ interface is then used to restore the recursion level when the lock is
+ reacquired.
- This method releases the underlying lock, and then blocks until it is awakened
- by a :meth:`notify` or :meth:`notifyAll` call for the same condition variable in
- another thread, or until the optional timeout occurs. Once awakened or timed
- out, it re-acquires the lock and returns.
+ .. method:: notify()
- 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).
+ Wake up a thread waiting on this condition, if any. If the calling thread
+ has not acquired the lock when this method is called, a
+ :exc:`RuntimeError` is raised.
- When the underlying lock is an :class:`RLock`, it is not released using its
- :meth:`release` method, since this may not actually unlock the lock when it was
- acquired multiple times recursively. Instead, an internal interface of the
- :class:`RLock` class is used, which really unlocks it even when it has been
- recursively acquired several times. Another internal interface is then used to
- restore the recursion level when the lock is reacquired.
+ This method wakes up one of the threads waiting for the condition
+ variable, if any are waiting; it is a no-op if no threads are waiting.
+ The current implementation wakes up exactly one thread, if any are
+ waiting. However, it's not safe to rely on this behavior. A future,
+ optimized implementation may occasionally wake up more than one thread.
-.. method:: Condition.notify()
+ Note: the awakened thread does not actually return from its :meth:`wait`
+ call until it can reacquire the lock. Since :meth:`notify` does not
+ release the lock, its caller should.
- Wake up a thread waiting on this condition, if any. If the calling thread
- has not acquired the lock when this method is called, a :exc:`RuntimeError`
- is raised.
+ .. method:: notify_all()
+ notifyAll()
- This method wakes up one of the threads waiting for the condition variable,
- if any are waiting; it is a no-op if no threads are waiting.
-
- The current implementation wakes up exactly one thread, if any are waiting.
- However, it's not safe to rely on this behavior. A future, optimized
- implementation may occasionally wake up more than one thread.
-
- Note: the awakened thread does not actually return from its :meth:`wait` call
- until it can reacquire the lock. Since :meth:`notify` does not release the
- lock, its caller should.
-
-
-.. method:: Condition.notify_all()
- Condition.notifyAll()
-
- Wake up all threads waiting on this condition. This method acts like
- :meth:`notify`, but wakes up all waiting threads instead of one. If the calling
- thread has not acquired the lock when this method is called, a
- :exc:`RuntimeError` is raised.
+ Wake up all threads waiting on this condition. This method acts like
+ :meth:`notify`, but wakes up all waiting threads instead of one. If the
+ calling thread has not acquired the lock when this method is called, a
+ :exc:`RuntimeError` is raised.
.. _semaphore-objects:
@@ -602,33 +591,31 @@
defaults to ``1``. If the *value* given is less than 0, :exc:`ValueError` is
raised.
+ .. method:: acquire([blocking])
-.. method:: Semaphore.acquire([blocking])
+ Acquire a semaphore.
- Acquire a semaphore.
+ When invoked without arguments: if the internal counter is larger than
+ zero on entry, decrement it by one and return immediately. If it is zero
+ on entry, block, waiting until some other thread has called
+ :meth:`release` to make it larger than zero. This is done with proper
+ interlocking so that if multiple :meth:`acquire` calls are blocked,
+ :meth:`release` will wake exactly one of them up. The implementation may
+ pick one at random, so the order in which blocked threads are awakened
+ should not be relied on. There is no return value in this case.
- When invoked without arguments: if the internal counter is larger than zero on
- entry, decrement it by one and return immediately. If it is zero on entry,
- block, waiting until some other thread has called :meth:`release` to make it
- larger than zero. This is done with proper interlocking so that if multiple
- :meth:`acquire` calls are blocked, :meth:`release` will wake exactly one of them
- up. The implementation may pick one at random, so the order in which blocked
- threads are awakened should not be relied on. There is no return value in this
- case.
+ When invoked with *blocking* set to true, do the same thing as when called
+ without arguments, and return true.
- When invoked with *blocking* set to true, do the same thing as when called
- without arguments, and return true.
+ When invoked with *blocking* set to false, do not block. If a call
+ without an argument would block, return false immediately; otherwise, do
+ the same thing as when called without arguments, and return true.
- When invoked with *blocking* set to false, do not block. If a call without an
- argument would block, return false immediately; otherwise, do the same thing as
- when called without arguments, and return true.
+ .. method:: release()
-
-.. method:: Semaphore.release()
-
- Release a semaphore, incrementing the internal counter by one. When it was zero
- on entry and another thread is waiting for it to become larger than zero again,
- wake up that thread.
+ Release a semaphore, incrementing the internal counter by one. When it
+ was zero on entry and another thread is waiting for it to become larger
+ than zero again, wake up that thread.
.. _semaphore-examples:
@@ -675,36 +662,39 @@
The internal flag is initially false.
+ .. method:: is_set()
+ isSet()
-.. method:: Event.is_set()
- Event.isSet()
+ Return true if and only if the internal flag is true.
- Return true if and only if the internal flag is true.
+ .. method:: set()
+ Set the internal flag to true. All threads waiting for it to become true
+ are awakened. Threads that call :meth:`wait` once the flag is true will
+ not block at all.
-.. method:: Event.set()
+ .. method:: clear()
- Set the internal flag to true. All threads waiting for it to become true are
- awakened. Threads that call :meth:`wait` once the flag is true will not block at
- all.
+ Reset the internal flag to false. Subsequently, threads calling
+ :meth:`wait` will block until :meth:`.set` is called to set the internal
+ flag to true again.
+ .. method:: wait([timeout])
-.. method:: Event.clear()
+ Block until the internal flag is true. If the internal flag is true on
+ entry, return immediately. Otherwise, block until another thread calls
+ :meth:`.set` to set the flag to true, or until the optional timeout
+ occurs.
- Reset the internal flag to false. Subsequently, threads calling :meth:`wait`
- will block until :meth:`.set` is called to set the internal flag to true
- again.
+ 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).
+ This method returns the internal flag on exit, so it will always return
+ ``True`` except if a timeout is given and the operation times out.
-.. method:: Event.wait([timeout])
-
- Block until the internal flag is true. If the internal flag is true on
- entry, return immediately. Otherwise, block until another thread calls
- :meth:`.set` to set the flag to true, 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).
+ .. versionchanged:: 2.7
+ Previously, the method always returned ``None``.
.. _timer-objects:
@@ -735,11 +725,10 @@
Create a timer that will run *function* with arguments *args* and keyword
arguments *kwargs*, after *interval* seconds have passed.
+ .. method:: cancel()
-.. method:: Timer.cancel()
-
- Stop the timer, and cancel the execution of the timer's action. This will only
- work if the timer is still in its waiting stage.
+ Stop the timer, and cancel the execution of the timer's action. This will
+ only work if the timer is still in its waiting stage.
.. _with-locks:
diff --git a/Doc/library/urllib.rst b/Doc/library/urllib.rst
index 68b57aa..bd334fa 100644
--- a/Doc/library/urllib.rst
+++ b/Doc/library/urllib.rst
@@ -215,8 +215,9 @@
.. function:: quote_plus(string[, safe])
Like :func:`quote`, but also replaces spaces by plus signs, as required for
- quoting HTML form values. Plus signs in the original string are escaped unless
- they are included in *safe*. It also does not have *safe* default to ``'/'``.
+ quoting HTML form values when building up a query string to go into a URL.
+ Plus signs in the original string are escaped unless they are included in
+ *safe*. It also does not have *safe* default to ``'/'``.
.. function:: unquote(string)