From 4b78233cbd845cdd4b49bc5999a2ea9ea028b277 Mon Sep 17 00:00:00 2001 From: Vinay Sajip Date: Mon, 19 Jan 2009 06:49:19 +0000 Subject: [PATCH] Added more cross-reference targets and tidied up list of useful handlers. --- Doc/library/logging.rst | 67 +++++++++++++++++++++++++++-------------- 1 file changed, 45 insertions(+), 22 deletions(-) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 3982c7a9e9b..8226661856f 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -310,7 +310,7 @@ date format string, the default date format is:: with the milliseconds tacked on at the end. The message format string uses ``%()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 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 provided: -#. :class:`StreamHandler` instances send error messages to streams (file-like +#. :ref:`stream-handler` instances send error messages to streams (file-like objects). -#. :class:`FileHandler` instances send error messages to disk files. - -.. module:: logging.handlers +#. :ref:`file-handler` instances send error messages to disk files. #. :class:`BaseRotatingHandler` is the base class for handlers that rotate log files at a certain point. It is not meant to be instantiated - directly. Instead, use :class:`RotatingFileHandler` or - :class:`TimedRotatingFileHandler`. + directly. Instead, use :ref:`rotating-file-handler` or + :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. -#. :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. -#. :class:`SocketHandler` instances send error messages to TCP/IP +#. :ref:`socket-handler` instances send error messages to TCP/IP sockets. -#. :class:`DatagramHandler` instances send error messages to UDP +#. :ref:`datagram-handler` instances send error messages to UDP sockets. -#. :class:`SMTPHandler` instances send error messages to a designated +#. :ref:`smtp-handler` instances send error messages to a designated 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. -#. :class:`NTEventLogHandler` instances send error messages to a +#. :ref:`nt-eventlog-handler` instances send error messages to a 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. -#. :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. -#. :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 name. This handler is only useful on Unix-like systems; Windows does not support the underlying mechanism used. -.. currentmodule:: logging - -#. :class:`NullHandler` instances do nothing with error messages. They are used +#. :ref:`null-handler` instances do nothing with error messages. They are used 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 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 library. +.. _logger: 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. +.. _handler: + Handler Objects --------------- @@ -1577,6 +1576,8 @@ subclasses. However, the :meth:`__init__` method in subclasses needs to call :exc:`NotImplementedError`. +.. _stream-handler: + StreamHandler ^^^^^^^^^^^^^ @@ -1608,6 +1609,8 @@ and :meth:`flush` methods). no output, so an explicit :meth:`flush` call may be needed at times. +.. _file-handler: + FileHandler ^^^^^^^^^^^ @@ -1634,6 +1637,7 @@ sends logging output to a disk file. It inherits the output functionality from Outputs the record to the file. +.. _null-handler: NullHandler ^^^^^^^^^^^ @@ -1657,6 +1661,8 @@ for use by library developers. See :ref:`library-config` for more information on how to use :class:`NullHandler`. +.. _watched-file-handler: + WatchedFileHandler ^^^^^^^^^^^^^^^^^^ @@ -1697,6 +1703,7 @@ this value. changed. If it has, the existing stream is flushed and closed and the file opened again, before outputting the record to the file. +.. _rotating-file-handler: RotatingFileHandler ^^^^^^^^^^^^^^^^^^^ @@ -1737,6 +1744,7 @@ module, supports rotation of disk log files. Outputs the record to the file, catering for rollover as described previously. +.. _timed-rotating-file-handler: TimedRotatingFileHandler ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1795,6 +1803,8 @@ timed intervals. Outputs the record to the file, catering for rollover as described above. +.. _socket-handler: + 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. +.. _datagram-handler: + DatagramHandler ^^^^^^^^^^^^^^^ @@ -1881,6 +1893,8 @@ over UDP sockets. Send a pickled string to a socket. +.. _syslog-handler: + SysLogHandler ^^^^^^^^^^^^^ @@ -1918,6 +1932,8 @@ supports sending logging messages to a remote or local Unix syslog. used to convert them to integers. +.. _nt-eventlog-handler: + NTEventLogHandler ^^^^^^^^^^^^^^^^^ @@ -1983,6 +1999,7 @@ extensions for Python installed. lookup to get the message ID. This version returns 1, which is the base message ID in :file:`win32service.pyd`. +.. _smtp-handler: 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 this method. +.. _memory-handler: 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. +.. _http-handler: + 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. -.. _formatter-objects: +.. _formatter: 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 returned. +.. _filter: 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 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 @@ -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 method. +.. _log-record: 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 user-supplied arguments with the message. +.. _logger-adapter: LoggerAdapter Objects ---------------------