[Python-checkins] r86974 - python/branches/py3k/Doc/library/logging.rst
georg.brandl
python-checkins at python.org
Fri Dec 3 16:30:09 CET 2010
Author: georg.brandl
Date: Fri Dec 3 16:30:09 2010
New Revision: 86974
Log:
Markup consistency fixes.
Modified:
python/branches/py3k/Doc/library/logging.rst
Modified: python/branches/py3k/Doc/library/logging.rst
==============================================================================
--- python/branches/py3k/Doc/library/logging.rst (original)
+++ python/branches/py3k/Doc/library/logging.rst Fri Dec 3 16:30:09 2010
@@ -548,10 +548,7 @@
unit tests and deliver logs which suit their requirements.
.. versionadded:: 3.1
-
-The :class:`NullHandler` class was not present in previous versions, but is
-now included, so that it need not be defined in library code.
-
+ The :class:`NullHandler` class.
Logging Levels
@@ -688,12 +685,10 @@
more information.
.. versionadded:: 3.1
-
-The :class:`NullHandler` class was not present in previous versions.
+ The :class:`NullHandler` class.
.. versionadded:: 3.2
-
-The :class:`QueueHandler` class was not present in previous versions.
+ The :class:`QueueHandler` class.
The :class:`NullHandler`, :class:`StreamHandler` and :class:`FileHandler`
classes are defined in the core logging package. The other handlers are
@@ -755,7 +750,6 @@
Return a callable which is used to create a :class:`LogRecord`.
.. versionadded:: 3.2
-
This function has been provided, along with :func:`setLogRecordFactory`,
to allow developers more control over how the :class:`LogRecord`
representing a logging event is constructed.
@@ -986,6 +980,7 @@
function is typically called before any loggers are instantiated by applications
which need to use custom logger behavior.
+
.. function:: setLogRecordFactory(factory)
Set a callable which is used to create a :class:`LogRecord`.
@@ -993,14 +988,13 @@
:param factory: The factory callable to be used to instantiate a log record.
.. versionadded:: 3.2
+ This function has been provided, along with :func:`getLogRecordFactory`, to
+ allow developers more control over how the :class:`LogRecord` representing
+ a logging event is constructed.
- This function has been provided, along with :func:`getLogRecordFactory`, to
- allow developers more control over how the :class:`LogRecord` representing
- a logging event is constructed.
+ The factory has the following signature:
- The factory has the following signature.
-
- factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, \*\*kwargs)
+ ``factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, \*\*kwargs)``
:name: The logger name.
:level: The logging level (numeric).
@@ -1015,6 +1009,7 @@
:func:`traceback.print_stack`, showing the call hierarchy.
:kwargs: Additional keyword arguments.
+
.. seealso::
:pep:`282` - A Logging System
@@ -1253,9 +1248,8 @@
False is found - that will be the last logger which is checked for the
existence of handlers.
-.. versionadded:: 3.2
+ .. versionadded:: 3.2
-The :meth:`hasHandlers` method was not present in previous versions.
.. _minimal-example:
@@ -2239,6 +2233,7 @@
Outputs the record to the file.
+
.. _null-handler:
NullHandler
@@ -2250,12 +2245,10 @@
does not do any formatting or output. It is essentially a "no-op" handler
for use by library developers.
-
.. class:: NullHandler()
Returns a new instance of the :class:`NullHandler` class.
-
.. method:: emit(record)
This method does nothing.
@@ -2849,6 +2842,8 @@
QueueHandler
^^^^^^^^^^^^
+.. versionadded:: 3.2
+
The :class:`QueueHandler` class, located in the :mod:`logging.handlers` module,
supports sending logging messages to a queue, such as those implemented in the
:mod:`queue` or :mod:`multiprocessing` modules.
@@ -2892,15 +2887,14 @@
timeout, or a customised queue implementation.
-.. versionadded:: 3.2
-
-The :class:`QueueHandler` class was not present in previous versions.
.. queue-listener:
QueueListener
^^^^^^^^^^^^^
+.. versionadded:: 3.2
+
The :class:`QueueListener` class, located in the :mod:`logging.handlers`
module, supports receiving logging messages from a queue, such as those
implemented in the :mod:`queue` or :mod:`multiprocessing` modules. The
@@ -2961,9 +2955,6 @@
Note that if you don't call this before your application exits, there
may be some records still left on the queue, which won't be processed.
-.. versionadded:: 3.2
-
-The :class:`QueueListener` class was not present in previous versions.
.. _zeromq-handlers:
@@ -3006,6 +2997,7 @@
def close(self):
self.queue.close()
+
Subclassing QueueListener
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -3023,6 +3015,7 @@
msg = self.queue.recv()
return logging.makeLogRecord(json.loads(msg))
+
.. _formatter-objects:
Formatter Objects
@@ -3291,22 +3284,23 @@
set using :func:`getLogRecordFactory` and :func:`setLogRecordFactory`
(see this for the factory's signature).
- This functionality can be used to inject your own values into a
- LogRecord at creation time. You can use the following pattern::
+ This functionality can be used to inject your own values into a
+ LogRecord at creation time. You can use the following pattern::
+
+ old_factory = logging.getLogRecordFactory()
- old_factory = logging.getLogRecordFactory()
+ def record_factory(*args, **kwargs):
+ record = old_factory(*args, **kwargs)
+ record.custom_attribute = 0xdecafbad
+ return record
+
+ logging.setLogRecordFactory(record_factory)
+
+ With this pattern, multiple factories could be chained, and as long
+ as they don't overwrite each other's attributes or unintentionally
+ overwrite the standard attributes listed above, there should be no
+ surprises.
- def record_factory(*args, **kwargs):
- record = old_factory(*args, **kwargs)
- record.custom_attribute = 0xdecafbad
- return record
-
- logging.setLogRecordFactory(record_factory)
-
- With this pattern, multiple factories could be chained, and as long
- as they don't overwrite each other's attributes or unintentionally
- overwrite the standard attributes listed above, there should be no
- surprises.
.. _logger-adapter:
@@ -3315,22 +3309,21 @@
:class:`LoggerAdapter` instances are used to conveniently pass contextual
information into logging calls. For a usage example , see the section on
-`adding contextual information to your logging output`__.
+:ref:`adding contextual information to your logging output <context-info>`.
-__ context-info_
.. class:: LoggerAdapter(logger, extra)
- Returns an instance of :class:`LoggerAdapter` initialized with an
- underlying :class:`Logger` instance and a dict-like object.
+ Returns an instance of :class:`LoggerAdapter` initialized with an
+ underlying :class:`Logger` instance and a dict-like object.
- .. method:: process(msg, kwargs)
+ .. method:: process(msg, kwargs)
- Modifies the message and/or keyword arguments passed to a logging call in
- order to insert contextual information. This implementation takes the object
- passed as *extra* to the constructor and adds it to *kwargs* using key
- 'extra'. The return value is a (*msg*, *kwargs*) tuple which has the
- (possibly modified) versions of the arguments passed in.
+ Modifies the message and/or keyword arguments passed to a logging call in
+ order to insert contextual information. This implementation takes the object
+ passed as *extra* to the constructor and adds it to *kwargs* using key
+ 'extra'. The return value is a (*msg*, *kwargs*) tuple which has the
+ (possibly modified) versions of the arguments passed in.
In addition to the above, :class:`LoggerAdapter` supports the following
methods of :class:`Logger`, i.e. :meth:`debug`, :meth:`info`, :meth:`warning`,
More information about the Python-checkins
mailing list