Moved example section up to just after the section on Logger objects, and changed it to use the new basicConfig() API
diff --git a/Doc/lib/liblogging.tex b/Doc/lib/liblogging.tex
index c86596d..2e8e16e 100644
--- a/Doc/lib/liblogging.tex
+++ b/Doc/lib/liblogging.tex
@@ -200,8 +200,9 @@
\constant{ERROR}, \constant{WARNING}, \constant{INFO} or \constant{DEBUG}
then you get the corresponding string. If you have associated levels
with names using \function{addLevelName()} then the name you have associated
-with \var{lvl} is returned. Otherwise, the string "Level \%s" \% lvl is
-returned.
+with \var{lvl} is returned. If a numeric value corresponding to one of the
+defined levels is passed in, the corresponding string representation is
+returned. Otherwise, the string "Level \%s" \% lvl is returned.
\end{funcdesc}
\begin{funcdesc}{makeLogRecord}{attrdict}
@@ -243,8 +244,8 @@
{Original Python \module{logging} package}
{This is the original source for the \module{logging}
package. The version of the package available from this
- site is suitable for use with Python 2.1.x and 2.2.x, which
- do not include the \module{logging} package in the standard
+ site is suitable for use with Python 1.5.2, 2.1.x and 2.2.x,
+ which do not include the \module{logging} package in the standard
library.}
\end{seealso}
@@ -363,6 +364,112 @@
specialized \class{LogRecord} instances.
\end{methoddesc}
+\subsection{Basic example \label{minimal-example}}
+
+The \module{logging} package provides a lot of flexibility, and its
+configuration can appear daunting. This section demonstrates that simple
+use of the logging package is possible.
+
+The simplest example shows logging to the console:
+
+\begin{verbatim}
+import logging
+
+logging.debug('A debug message')
+logging.info('Some information')
+logging.warning('A shot across the bows')
+\end{verbatim}
+
+If you run the above script, you'll see this:
+\begin{verbatim}
+WARNING:root:A shot across the bows
+\end{verbatim}
+
+Because no particular logger was specified, the system used the root logger.
+The debug and info messages didn't appear because by default, the root
+logger is configured to only handle messages with a severity of WARNING
+or above. The message format is also a configuration default, as is the output
+destination of the messages - \code{sys.stderr}. The severity level,
+the message format and destination can be easily changed, as shown in
+the example below:
+
+\begin{verbatim}
+import logging
+
+logging.basicConfig(level=logging.DEBUG,
+ format='%(asctime)s %(levelname)s %(message)s',
+ filename='/tmp/myapp.log',
+ filemode='w')
+logging.debug('A debug message')
+logging.info('Some information')
+logging.warning('A shot across the bows')
+\end{verbatim}
+
+The \method{basicConfig()} method is used to change the configuration
+defaults, which results in output (written to \code{/tmp/myapp.log})
+which should look something like the following:
+
+\begin{verbatim}
+2004-07-02 13:00:08,743 DEBUG A debug message
+2004-07-02 13:00:08,743 INFO Some information
+2004-07-02 13:00:08,743 WARNING A shot across the bows
+\end{verbatim}
+
+This time, all messages with a severity of DEBUG or above were handled,
+and the format of the messages was also changed, and output went to the
+specified file rather than the console.
+
+Formatting uses standard Python string formatting - see section
+\ref{typesseq-strings}. The format string takes the following
+common specifiers. For a complete list of specifiers, consult the
+\class{Formatter} documentation.
+
+\begin{tableii}{l|l}{code}{Format}{Description}
+\lineii{\%(name)s} {Name of the logger (logging channel).}
+\lineii{\%(levelname)s}{Text logging level for the message
+ (\code{'DEBUG'}, \code{'INFO'},
+ \code{'WARNING'}, \code{'ERROR'},
+ \code{'CRITICAL'}).}
+\lineii{\%(asctime)s} {Human-readable time when the \class{LogRecord}
+ was created. By default this is of the form
+ ``2003-07-08 16:49:45,896'' (the numbers after the
+ comma are millisecond portion of the time).}
+\lineii{\%(message)s} {The logged message.}
+\end{tableii}
+
+To change the date/time format, you can pass an additional keyword parameter,
+\var{datefmt}, as in the following:
+
+\begin{verbatim}
+import logging
+
+logging.basicConfig(level=logging.DEBUG,
+ format='%(asctime)s %(levelname)-8s %(message)s',
+ datefmt='%a, %d %b %Y %H:%M:%S',
+ filename='/temp/myapp.log',
+ filemode='w')
+logging.debug('A debug message')
+logging.info('Some information')
+logging.warning('A shot across the bows')
+\end{verbatim}
+
+which would result in output like
+
+\begin{verbatim}
+Fri, 02 Jul 2004 13:06:18 DEBUG A debug message
+Fri, 02 Jul 2004 13:06:18 INFO Some information
+Fri, 02 Jul 2004 13:06:18 WARNING A shot across the bows
+\end{verbatim}
+
+The date format string follows the requirements of \function{strftime()} -
+see the documentation for the \refmodule{time} module.
+
+If, instead of sending logging output to the console or a file, you'd rather
+use a file-like object which you have created separately, you can pass it
+to \function{basicConfig()} using the \var{stream} keyword argument. Note
+that if both \var{stream} and \var{filename} keyword arguments are passed,
+the \var{stream} argument is ignored.
+
\subsection{Handler Objects}
Handlers have the following attributes and methods. Note that
@@ -429,14 +536,15 @@
lock.
\end{methoddesc}
-\begin{methoddesc}{handleError}{}
+\begin{methoddesc}{handleError}{record}
This method should be called from handlers when an exception is
-encountered during an emit() call. By default it does nothing,
+encountered during an \method{emit()} call. By default it does nothing,
which means that exceptions get silently ignored. This is what is
mostly wanted for a logging system - most users will not care
about errors in the logging system, they are more interested in
application errors. You could, however, replace this with a custom
-handler if you wish.
+handler if you wish. The specified record is the one which was being
+processed when the exception occurred.
\end{methoddesc}
\begin{methoddesc}{format}{record}
@@ -506,7 +614,7 @@
Returns a new instance of the \class{RotatingFileHandler} class. The
specified file is opened and used as the stream for logging. If
\var{mode} is not specified, \code{'a'} is used. By default, the
-file grows indefinitely.
+file grows indefinitely.
You can use the \var{maxBytes} and
\var{backupCount} values to allow the file to \dfn{rollover} at a
@@ -522,7 +630,7 @@
written to is always \file{app.log}. When this file is filled, it is
closed and renamed to \file{app.log.1}, and if files \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.
+\file{app.log.3} etc. respectively.
\end{classdesc}
\begin{methoddesc}{doRollover}{}
@@ -1051,7 +1159,7 @@
higher up the logger hierarchy from this logger, or 0 to indicate that
messages are \strong{not} propagated to handlers up the hierarchy. The
\code{qualname} entry is the hierarchical channel name of the logger,
-for example, the name used by the application to get the logger.
+that is to say the name used by the application to get the logger.
Sections which specify handler configuration are exemplified by the
following.
@@ -1147,45 +1255,3 @@
The ISO8601 format also specifies milliseconds, which are appended to the
result of using the above format string, with a comma separator. An example
time in ISO8601 format is \code{2003-01-23 00:29:50,411}.
-
-\subsection{Using the logging package}
-
-\subsubsection{Basic example - log to a file}
-
-Here's a simple logging example that just logs to a file. In order,
-it creates a \class{Logger} instance, then a \class{FileHandler}
-and a \class{Formatter}. It attaches the \class{Formatter} to the
-\class{FileHandler}, then the \class{FileHandler} to the \class{Logger}.
-Finally, it sets a debug level for the logger.
-
-\begin{verbatim}
-import logging
-logger = logging.getLogger('myapp')
-hdlr = logging.FileHandler('/var/tmp/myapp.log')
-formatter = logging.Formatter('%(asctime)s %(levelname)s %(message)s')
-hdlr.setFormatter(formatter)
-logger.addHandler(hdlr)
-logger.setLevel(logging.WARNING)
-\end{verbatim}
-
-We can use this logger object now to write entries to the log file:
-
-\begin{verbatim}
-logger.error('We have a problem')
-logger.info('While this is just chatty')
-\end{verbatim}
-
-If we look in the file that was created, we'll see something like this:
-\begin{verbatim}
-2003-07-08 16:49:45,896 ERROR We have a problem
-\end{verbatim}
-
-The info message was not written to the file: we called the
-\method{setLevel()} method to say we only wanted \constant{WARNING} or
-worse, so the info message is discarded.
-
-The timestamp is of the form
-``year-month-day hour:minutes:seconds,milliseconds.''
-Note that despite the three digits of precision in the milliseconds field,
-not all systems provide time with this much precision.
-