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/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()