Merged revisions 74861-74863,74876,74896,74930,74933,74952-74953,75015,75019,75260-75263,75265-75266,75289 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74861 | benjamin.peterson | 2009-09-17 05:18:28 +0200 (Do, 17 Sep 2009) | 1 line
pep 8 defaults
........
r74862 | brett.cannon | 2009-09-17 05:24:45 +0200 (Do, 17 Sep 2009) | 1 line
Note in the intro to Extending... that ctypes can be a simpler, more portable solution than custom C code.
........
r74863 | benjamin.peterson | 2009-09-17 05:27:33 +0200 (Do, 17 Sep 2009) | 1 line
rationalize a bit
........
r74876 | georg.brandl | 2009-09-17 18:15:53 +0200 (Do, 17 Sep 2009) | 1 line
#6932: remove paragraph that advises relying on __del__ being called.
........
r74896 | georg.brandl | 2009-09-18 09:22:41 +0200 (Fr, 18 Sep 2009) | 1 line
#6936: for interactive use, quit() is just fine.
........
r74930 | georg.brandl | 2009-09-18 23:21:41 +0200 (Fr, 18 Sep 2009) | 1 line
#6925: rewrite docs for locals() and vars() a bit.
........
r74933 | georg.brandl | 2009-09-18 23:35:59 +0200 (Fr, 18 Sep 2009) | 1 line
#6930: clarify description about byteorder handling in UTF decoder routines.
........
r74952 | georg.brandl | 2009-09-19 12:42:34 +0200 (Sa, 19 Sep 2009) | 1 line
#6946: fix duplicate index entries for datetime classes.
........
r74953 | georg.brandl | 2009-09-19 14:04:16 +0200 (Sa, 19 Sep 2009) | 1 line
Fix references to threading.enumerate().
........
r75015 | georg.brandl | 2009-09-22 12:55:08 +0200 (Di, 22 Sep 2009) | 1 line
Fix encoding name.
........
r75019 | vinay.sajip | 2009-09-22 19:23:41 +0200 (Di, 22 Sep 2009) | 1 line
Fixed a typo, and added sections on optimization and using arbitrary objects as messages.
........
r75260 | andrew.kuchling | 2009-10-05 23:24:20 +0200 (Mo, 05 Okt 2009) | 1 line
Wording fix
........
r75261 | andrew.kuchling | 2009-10-05 23:24:35 +0200 (Mo, 05 Okt 2009) | 1 line
Fix narkup
........
r75262 | andrew.kuchling | 2009-10-05 23:25:03 +0200 (Mo, 05 Okt 2009) | 1 line
Document 'skip' parameter to constructor
........
r75263 | andrew.kuchling | 2009-10-05 23:25:35 +0200 (Mo, 05 Okt 2009) | 1 line
Note side benefit of socket.create_connection()
........
r75265 | andrew.kuchling | 2009-10-06 00:31:11 +0200 (Di, 06 Okt 2009) | 1 line
Reword sentence
........
r75266 | andrew.kuchling | 2009-10-06 00:32:48 +0200 (Di, 06 Okt 2009) | 1 line
Use standard comma punctuation; reword some sentences in the docs
........
r75289 | mark.dickinson | 2009-10-08 22:02:25 +0200 (Do, 08 Okt 2009) | 2 lines
Issue #7051: Clarify behaviour of 'g' and 'G'-style formatting.
........
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index fcc5edd..aea9653 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -59,7 +59,7 @@
import logging
LOG_FILENAME = '/tmp/logging_example.out'
- logging.basicConfig(filename=LOG_FILENAME,level=logging.DEBUG,)
+ logging.basicConfig(filename=LOG_FILENAME,level=logging.DEBUG)
logging.debug('This message should go to the log file')
@@ -1499,6 +1499,53 @@
69 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.
69 myapp.area2 ERROR The five boxing wizards jump quickly.
+Using arbitrary objects as messages
+-----------------------------------
+
+In the preceding sections and examples, it has been assumed that the message
+passed when logging the event is a string. However, this is not the only
+possibility. You can pass an arbitrary object as a message, and its
+:meth:`__str__` method will be called when the logging system needs to convert
+it to a string representation. In fact, if you want to, you can avoid
+computing a string representation altogether - for example, the
+:class:`SocketHandler` emits an event by pickling it and sending it over the
+wire.
+
+Optimization
+------------
+
+Formatting of message arguments is deferred until it cannot be avoided.
+However, computing the arguments passed to the logging method can also be
+expensive, and you may want to avoid doing it if the logger will just throw
+away your event. To decide what to do, you can call the :meth:`isEnabledFor`
+method which takes a level argument and returns true if the event would be
+created by the Logger for that level of call. You can write code like this::
+
+ if logger.isEnabledFor(logging.DEBUG):
+ logger.debug("Message with %s, %s", expensive_func1(),
+ expensive_func2())
+
+so that if the logger's threshold is set above ``DEBUG``, the calls to
+:func:`expensive_func1` and :func:`expensive_func2` are never made.
+
+There are other optimizations which can be made for specific applications which
+need more precise control over what logging information is collected. Here's a
+list of things you can do to avoid processing during logging which you don't
+need:
+
++-----------------------------------------------+----------------------------------------+
+| What you don't want to collect | How to avoid collecting it |
++===============================================+========================================+
+| Information about where calls were made from. | Set ``logging._srcfile`` to ``None``. |
++-----------------------------------------------+----------------------------------------+
+| Threading information. | Set ``logging.logThreads`` to ``0``. |
++-----------------------------------------------+----------------------------------------+
+| Process information. | Set ``logging.logProcesses`` to ``0``. |
++-----------------------------------------------+----------------------------------------+
+
+Also note that the core logging module only includes the basic handlers. If
+you don't import :mod:`logging.handlers` and :mod:`logging.config`, they won't
+take up any memory.
.. _handler: