traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Added more cross-reference targets and tidied up list of useful handlers.

This commit is contained in:
Vinay Sajip 2009-01-19 06:49:19 +00:00
parent 5848d1ff35
commit 4b78233cbd
1 changed files with 45 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
Doc/library/logging.rst
View File

@ -310,7 +310,7 @@ date format string, the default date format is::
with the milliseconds tacked on at the end. with the milliseconds tacked on at the end.
The message format string uses ``%(<dictionary key>)s`` styled string The message format string uses ``%(<dictionary key>)s`` styled string
substitution; the possible keys are documented in :ref:`formatter-objects`. substitution; the possible keys are documented in :ref:`formatter`.
The following message format string will log the time in a human-readable The following message format string will log the time in a human-readable
format, the severity of the message, and the contents of the message, in that format, the severity of the message, and the contents of the message, in that
@ -530,53 +530,49 @@ Useful Handlers
In addition to the base :class:`Handler` class, many useful subclasses are In addition to the base :class:`Handler` class, many useful subclasses are
provided: provided:
#. :class:`StreamHandler` instances send error messages to streams (file-like #. :ref:`stream-handler` instances send error messages to streams (file-like
objects). objects).
#. :class:`FileHandler` instances send error messages to disk files. #. :ref:`file-handler` instances send error messages to disk files.
.. module:: logging.handlers
#. :class:`BaseRotatingHandler` is the base class for handlers that #. :class:`BaseRotatingHandler` is the base class for handlers that
rotate log files at a certain point. It is not meant to be instantiated rotate log files at a certain point. It is not meant to be instantiated
directly. Instead, use :class:`RotatingFileHandler` or directly. Instead, use :ref:`rotating-file-handler` or
:class:`TimedRotatingFileHandler`. :ref:`timed-rotating-file-handler`.
#. :class:`RotatingFileHandler` instances send error messages to disk #. :ref:`rotating-file-handler` instances send error messages to disk
files, with support for maximum log file sizes and log file rotation. files, with support for maximum log file sizes and log file rotation.
#. :class:`TimedRotatingFileHandler` instances send error messages to #. :ref:`timed-rotating-file-handler` instances send error messages to
disk files, rotating the log file at certain timed intervals. disk files, rotating the log file at certain timed intervals.
#. :class:`SocketHandler` instances send error messages to TCP/IP #. :ref:`socket-handler` instances send error messages to TCP/IP
sockets. sockets.
#. :class:`DatagramHandler` instances send error messages to UDP #. :ref:`datagram-handler` instances send error messages to UDP
sockets. sockets.
#. :class:`SMTPHandler` instances send error messages to a designated #. :ref:`smtp-handler` instances send error messages to a designated
email address. email address.
#. :class:`SysLogHandler` instances send error messages to a Unix #. :ref:`syslog-handler` instances send error messages to a Unix
syslog daemon, possibly on a remote machine. syslog daemon, possibly on a remote machine.
#. :class:`NTEventLogHandler` instances send error messages to a #. :ref:`nt-eventlog-handler` instances send error messages to a
Windows NT/2000/XP event log. Windows NT/2000/XP event log.
#. :class:`MemoryHandler` instances send error messages to a buffer #. :ref:`memory-handler` instances send error messages to a buffer
in memory, which is flushed whenever specific criteria are met. in memory, which is flushed whenever specific criteria are met.
#. :class:`HTTPHandler` instances send error messages to an HTTP #. :ref:`http-handler` instances send error messages to an HTTP
server using either ``GET`` or ``POST`` semantics. server using either ``GET`` or ``POST`` semantics.
#. :class:`WatchedFileHandler` instances watch the file they are #. :ref:`watched-file-handler` instances watch the file they are
logging to. If the file changes, it is closed and reopened using the file logging to. If the file changes, it is closed and reopened using the file
name. This handler is only useful on Unix-like systems; Windows does not name. This handler is only useful on Unix-like systems; Windows does not
support the underlying mechanism used. support the underlying mechanism used.
.. currentmodule:: logging #. :ref:`null-handler` instances do nothing with error messages. They are used
#. :class:`NullHandler` instances do nothing with error messages. They are used
by library developers who want to use logging, but want to avoid the "No by library developers who want to use logging, but want to avoid the "No
handlers could be found for logger XXX" message which can be displayed if handlers could be found for logger XXX" message which can be displayed if
the library user has not configured logging. See :ref:`library-config` for the library user has not configured logging. See :ref:`library-config` for
@ -834,6 +830,7 @@ functions.
and 2.2.x, which do not include the :mod:`logging` package in the standard and 2.2.x, which do not include the :mod:`logging` package in the standard
library. library.
.. _logger:
Logger Objects Logger Objects
-------------- --------------
@ -1472,6 +1469,8 @@ printed on the console; on the server side, you should see something like::
69 myapp.area2 ERROR The five boxing wizards jump quickly. 69 myapp.area2 ERROR The five boxing wizards jump quickly.
.. _handler:
Handler Objects Handler Objects
--------------- ---------------
@ -1577,6 +1576,8 @@ subclasses. However, the :meth:`__init__` method in subclasses needs to call
:exc:`NotImplementedError`. :exc:`NotImplementedError`.
.. _stream-handler:
StreamHandler StreamHandler
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
@ -1608,6 +1609,8 @@ and :meth:`flush` methods).
no output, so an explicit :meth:`flush` call may be needed at times. no output, so an explicit :meth:`flush` call may be needed at times.
.. _file-handler:
FileHandler FileHandler
^^^^^^^^^^^ ^^^^^^^^^^^
@ -1634,6 +1637,7 @@ sends logging output to a disk file. It inherits the output functionality from
Outputs the record to the file. Outputs the record to the file.
.. _null-handler:
NullHandler NullHandler
^^^^^^^^^^^ ^^^^^^^^^^^
@ -1657,6 +1661,8 @@ for use by library developers.
See :ref:`library-config` for more information on how to use See :ref:`library-config` for more information on how to use
:class:`NullHandler`. :class:`NullHandler`.
.. _watched-file-handler:
WatchedFileHandler WatchedFileHandler
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
@ -1697,6 +1703,7 @@ this value.
changed. If it has, the existing stream is flushed and closed and the changed. If it has, the existing stream is flushed and closed and the
file opened again, before outputting the record to the file. file opened again, before outputting the record to the file.
.. _rotating-file-handler:
RotatingFileHandler RotatingFileHandler
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
@ -1737,6 +1744,7 @@ module, supports rotation of disk log files.
Outputs the record to the file, catering for rollover as described Outputs the record to the file, catering for rollover as described
previously. previously.
.. _timed-rotating-file-handler:
TimedRotatingFileHandler TimedRotatingFileHandler
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
@ -1795,6 +1803,8 @@ timed intervals.
Outputs the record to the file, catering for rollover as described above. Outputs the record to the file, catering for rollover as described above.
.. _socket-handler:
SocketHandler SocketHandler
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
@ -1848,6 +1858,8 @@ sends logging output to a network socket. The base class uses a TCP socket.
partial sends which can happen when the network is busy. partial sends which can happen when the network is busy.
.. _datagram-handler:
DatagramHandler DatagramHandler
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
@ -1881,6 +1893,8 @@ over UDP sockets.
Send a pickled string to a socket. Send a pickled string to a socket.
.. _syslog-handler:
SysLogHandler SysLogHandler
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
@ -1918,6 +1932,8 @@ supports sending logging messages to a remote or local Unix syslog.
used to convert them to integers. used to convert them to integers.
.. _nt-eventlog-handler:
NTEventLogHandler NTEventLogHandler
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
@ -1983,6 +1999,7 @@ extensions for Python installed.
lookup to get the message ID. This version returns 1, which is the base lookup to get the message ID. This version returns 1, which is the base
message ID in :file:`win32service.pyd`. message ID in :file:`win32service.pyd`.
.. _smtp-handler:
SMTPHandler SMTPHandler
^^^^^^^^^^^ ^^^^^^^^^^^
@ -2014,6 +2031,7 @@ supports sending logging messages to an email address via SMTP.
If you want to specify a subject line which is record-dependent, override If you want to specify a subject line which is record-dependent, override
this method. this method.
.. _memory-handler:
MemoryHandler MemoryHandler
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
@ -2084,6 +2102,8 @@ should, then :meth:`flush` is expected to do the needful.
Checks for buffer full or a record at the *flushLevel* or higher. Checks for buffer full or a record at the *flushLevel* or higher.
.. _http-handler:
HTTPHandler HTTPHandler
^^^^^^^^^^^ ^^^^^^^^^^^
@ -2105,7 +2125,7 @@ supports sending logging messages to a Web server, using either ``GET`` or
Sends the record to the Web server as an URL-encoded dictionary. Sends the record to the Web server as an URL-encoded dictionary.
.. _formatter-objects: .. _formatter:
Formatter Objects Formatter Objects
----------------- -----------------
@ -2229,11 +2249,12 @@ Currently, the useful mapping keys in a :class:`LogRecord` are:
just uses :func:`traceback.print_exception`. The resulting string is just uses :func:`traceback.print_exception`. The resulting string is
returned. returned.
.. _filter:
Filter Objects Filter Objects
-------------- --------------
:class:`Filter`\ s can be used by :class:`Handler`\ s and :class:`Logger`\ s for Filters can be used by :class:`Handler`\ s and :class:`Logger`\ s for
more sophisticated filtering than is provided by levels. The base filter class more sophisticated filtering than is provided by levels. The base filter class
only allows events which are below a certain point in the logger hierarchy. For only allows events which are below a certain point in the logger hierarchy. For
example, a filter initialized with "A.B" will allow events logged by loggers example, a filter initialized with "A.B" will allow events logged by loggers
@ -2254,6 +2275,7 @@ initialized with the empty string, all events are passed.
yes. If deemed appropriate, the record may be modified in-place by this yes. If deemed appropriate, the record may be modified in-place by this
method. method.
.. _log-record:
LogRecord Objects LogRecord Objects
----------------- -----------------
@ -2288,6 +2310,7 @@ made, and any exception information to be logged.
Returns the message for this :class:`LogRecord` instance after merging any Returns the message for this :class:`LogRecord` instance after merging any
user-supplied arguments with the message. user-supplied arguments with the message.
.. _logger-adapter:
LoggerAdapter Objects LoggerAdapter Objects
--------------------- ---------------------