[Python-checkins] python/dist/src/Doc/whatsnew whatsnew23.tex,1.65,1.66

[akuchling@users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/whatsnew
In directory usw-pr-cvs1:/tmp/cvs-serv31309

Modified Files:
	whatsnew23.tex 
Log Message:
Add partial section on the logging package; not finished yet.

Index: whatsnew23.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/whatsnew/whatsnew23.tex,v
retrieving revision 1.65
retrieving revision 1.66
diff -C2 -d -r1.65 -r1.66
*** whatsnew23.tex	13 Nov 2002 14:59:06 -0000	1.65
--- whatsnew23.tex	14 Nov 2002 14:14:16 -0000	1.66
***************
*** 416,419 ****
--- 416,523 ----
  
  %======================================================================
+ \section{PEP 282: The \module{logging} Package}
+ 
+ A standard package for writing logs, the \module{logging} package, was
+ added.  It provides a powerful and flexible way for components to
+ generate logging output which can then be filtered and processed in
+ various ways.  The logging system can parse a configuration file to
+ control its behaviour.  Logs can be written to standard error, a file
+ or a socket, sent to the system log, e-mailed to a particular address,
+ or buffered in memory.  It's also possible to write your own handler
+ classes, of course.
+ 
+ You can have multiple \class{Logger} objects, each one used by a
+ particular subsystem of your code.  Each \class{Logger} is identified
+ by a name, and names are organized into a hierarchy using \samp{.}  as
+ the component separator.  For example, you might have \class{Logger}
+ instances named \samp{server}, \samp{server.auth} and
+ \samp{server.network}.  The latter two instances fall under the
+ \samp{server} \class{Logger} in the hierarchy.  This means that if you 
+ turn up the verbosity for \samp{server}, or direct 
+ \samp{server} messages to a different handler, 
+ the changes will also apply to \samp{server.auth} and
+ \samp{server.network}.
+ There's also a root \class{Logger} with the name \samp{root}, 
+ parent of all other instances.
+ 
+ The \module{logging} package contains some convenience functions
+ that always use the root log:
+ 
+ \begin{verbatim}
+ import logging
+ 
+ logging.debug('Debugging information')
+ logging.info('Informational message')
+ logging.warn('Warning: config file %s not found', 'server.conf')
+ logging.error('Error occurred')
+ logging.critical('Critical error -- shutting down')
+ \end{verbatim}
+ 
+ This produces the following output:
+ 
+ \begin{verbatim}
+ WARN:root:Warning: config file not found
+ ERROR:root:Error occurred
+ CRITICAL:root:Critical error -- shutting down
+ \end{verbatim}
+ 
+ In the default configuration, informational and debugging messages are
+ suppressed and the output is sent to standard error.  Note the
+ \function{warn()} call's use of string formatting operators; all of
+ the functions for logging messages take the arguments 
+ \code{(\var{msg}, \var{arg1}, \var{arg2}, ...)} and log the string resulting from
+ \code{\var{msg} \% (\var{arg1}, \var{arg2}, ...)}.
+ 
+ There's also an \function{exception()} function that records the most
+ recent traceback.  Any of the other functions will also record the
+ traceback by specifying the keyword argument \code{exc_info} as
+ \code{True}.
+ 
+ \begin{verbatim}
+ def f():
+     try:    1/0
+     except: logging.exception('Problem recorded')
+ 
+ f()
+ \end{verbatim}
+ 
+ This produces the following output:
+ 
+ \begin{verbatim}
+ ERROR:root:Problem recorded
+ Traceback (most recent call last):
+   File "t.py", line 6, in f
+     1/0
+ ZeroDivisionError: integer division or modulo by zero
+ \end{verbatim}
+ 
+ The \function{getLogger(\var{name})} is used to get a particular log.
+ 
+ \begin{verbatim}
+ log = logging.getLogger('server')
+  ...
+ log.info('Listening on port %i', port)
+  ...
+ log.critical('Disk full')
+  ...
+ \end{verbatim}
+ 
+ XXX finish this section
+ 
+ This is only a partial overview of the \module{logging} package's
+ features; see the
+ \citetitle[http://www.python.org/dev/doc/devel/lib/module-logging.html]{\module{logging}
+ package's reference documentation} for all of the details.
+ 
+ 
+ \begin{seealso}
+ 
+ \seepep{282}{A Logging System}{Written by Vinay Sajip and Trent Mick;
+ implemented by Vinay Sajip.}
+ 
+ \end{seealso}
+ 
+ 
+ %======================================================================
  \section{PEP 285: The \class{bool} Type\label{section-bool}}
  
***************
*** 685,689 ****
  >>> d.pop(4)
  Traceback (most recent call last):
!   File ``stdin'', line 1, in ?
  KeyError: 4
  >>> d.pop(1)
--- 789,793 ----
  >>> d.pop(4)
  Traceback (most recent call last):
!   File "stdin", line 1, in ?
  KeyError: 4
  >>> d.pop(1)
***************
*** 691,695 ****
  >>> d.pop(1)
  Traceback (most recent call last):
!   File ``stdin'', line 1, in ?
  KeyError: pop(): dictionary is empty
  >>> d
--- 795,799 ----
  >>> d.pop(1)
  Traceback (most recent call last):
!   File "stdin", line 1, in ?
  KeyError: pop(): dictionary is empty
  >>> d
***************
*** 1020,1026 ****
  >>> random.sample(pop, 7)          # Can't choose more than six
  Traceback (most recent call last):
!   File ``<stdin>'', line 1, in ?
!   File ``/home/amk/src/sf/python/dist/src/Lib/random.py'', line 396, in sample
!     raise ValueError, ``sample larger than population''
  ValueError: sample larger than population
  >>>
--- 1124,1130 ----
  >>> random.sample(pop, 7)          # Can't choose more than six
  Traceback (most recent call last):
!   File "<stdin>", line 1, in ?
!   File "random.py", line 396, in sample
!     raise ValueError, "sample larger than population"
  ValueError: sample larger than population
  >>>