[Python-checkins] python/dist/src/Doc/lib liblogging.tex,1.8,1.9

Fri, 27 Jun 2003 14:43:41 -0700

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv31078/Doc/lib

Modified Files:
	liblogging.tex 
Log Message:
SF patch #761519: Fixes for bugs 760703 and 757821
SF bug #760703: SocketHandler and LogRecord don't work well together
SF bug #757821: logging module docs

Applied Vinay Sajip's patch with a few minor fixups and a NEWS item.

Patched __init__.py - added new function 
makeLogRecord (for bug report 760703).

Patched handlers.py - updated some docstrings and 
deleted some old commented-out code.

Patched test_logging.py to make use of makeLogRecord.

Patched liblogging.tex to fill documentation gaps (both 
760703 and bug 757821).

Index: liblogging.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/liblogging.tex,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -d -r1.8 -r1.9
*** liblogging.tex	18 Feb 2003 14:20:05 -0000	1.8
--- liblogging.tex	27 Jun 2003 21:43:39 -0000	1.9
***************
*** 53,57 ****
  message (in the form of a \class{LogRecord}) ends up in a particular
  location (or set of locations) which is useful for the target audience for
! that message (e.g. end users, support desk staff, system administrators,
  developers). Handlers are passed \class{LogRecord} instances intended for
  particular destinations. Each logger can have zero, one or more handlers
--- 53,57 ----
  message (in the form of a \class{LogRecord}) ends up in a particular
  location (or set of locations) which is useful for the target audience for
! that message (such as end users, support desk staff, system administrators,
  developers). Handlers are passed \class{LogRecord} instances intended for
  particular destinations. Each logger can have zero, one or more handlers
***************
*** 205,208 ****
--- 205,215 ----
  \end{funcdesc}

+ \begin{funcdesc}{makeLogRecord}{attrdict}
+ Creates and returns a new \class{LogRecord} instance whose attributes are
+ defined by \var{attrdict}. This function is useful for taking a pickled
+ \class{LogRecord} attribute dictionary, sent over a socket, and reconstituting
+ it as a \class{LogRecord} instance at the receiving end.
+ \end{funcdesc}
+ 
  \begin{funcdesc}{basicConfig}{}
  Does basic configuration for the logging system by creating a
***************
*** 267,271 ****
  \constant{NOTSET} has been set using \method{setLevel()}, it is returned.
  Otherwise, the hierarchy is traversed towards the root until a value
! other than \constant{NOTSET} is found,and that value is returned.
  \end{methoddesc}

--- 274,278 ----
  \constant{NOTSET} has been set using \method{setLevel()}, it is returned.
  Otherwise, the hierarchy is traversed towards the root until a value
! other than \constant{NOTSET} is found, and that value is returned.
  \end{methoddesc}

***************
*** 536,542 ****

  \begin{methoddesc}{emit}{}
! Pickles the record and writes it to the socket in binary format.
! If there is an error with the socket, silently drops the packet.
! If the connection was previously lost, re-establishes the connection.
  \end{methoddesc}

--- 543,551 ----

  \begin{methoddesc}{emit}{}
! Pickles the record's attribute dictionary and writes it to the socket in
! binary format. If there is an error with the socket, silently drops the
! packet. If the connection was previously lost, re-establishes the connection.
! To unpickle the record at the receiving end into a LogRecord, use the
! \function{makeLogRecord} function.
  \end{methoddesc}

***************
*** 554,559 ****

  \begin{methoddesc}{makePickle}{record}
! Pickles the record in binary format with a length prefix, and returns
! it ready for transmission across the socket.
  \end{methoddesc}

--- 563,568 ----

  \begin{methoddesc}{makePickle}{record}
! Pickles the record's attribute dictionary in binary format with a length
! prefix, and returns it ready for transmission across the socket.
  \end{methoddesc}

***************
*** 575,580 ****

  \begin{methoddesc}{emit}{}
! Pickles the record and writes it to the socket in binary format.
! If there is an error with the socket, silently drops the packet.
  \end{methoddesc}

--- 584,592 ----

  \begin{methoddesc}{emit}{}
! Pickles the record's attribute dictionary and writes it to the socket in
! binary format. If there is an error with the socket, silently drops the
! packet.
! To unpickle the record at the receiving end into a LogRecord, use the
! \function{makeLogRecord} function.
  \end{methoddesc}

***************
*** 585,590 ****

  \begin{methoddesc}{send}{s}
! Send a pickled string to a socket. This function allows for
! partial sends which can happen when the network is busy.
  \end{methoddesc}

--- 597,601 ----

  \begin{methoddesc}{send}{s}
! Send a pickled string to a socket.
  \end{methoddesc}

***************
*** 790,795 ****

  A Formatter can be initialized with a format string which makes use of
! knowledge of the \class{LogRecord} attributes - e.g. the default value
! mentioned above makes use of the fact that the user's message and
  arguments are pre- formatted into a LogRecord's \var{message}
  attribute. Currently, the useful attributes in a LogRecord are
--- 801,806 ----

  A Formatter can be initialized with a format string which makes use of
! knowledge of the \class{LogRecord} attributes - such as the default value
! mentioned above making use of the fact that the user's message and
  arguments are pre- formatted into a LogRecord's \var{message}
  attribute. Currently, the useful attributes in a LogRecord are
***************
*** 917,921 ****
  \subsubsection{Configuration functions}

! The following functions allow the logging module to be configured.

  \begin{funcdesc}{fileConfig}{fname\optional{, defaults}}
--- 928,936 ----
  \subsubsection{Configuration functions}

! The following functions allow the logging module to be configured. Before
! they can be used, you must import \module{logging.config}. Their use is optional -
! you can configure the logging module entirely by making calls to the main
! API (defined in \module{logging} itself) and defining handlers which are declared
! either in \module{logging} or \module{logging.handlers}.

  \begin{funcdesc}{fileConfig}{fname\optional{, defaults}}
***************
*** 1014,1018 ****
  messages are \strong{not} propagated to handlers up the hierarchy. The
  \code{qualname} entry is the hierarchical channel name of the logger,
! i.e. the name used by the application to get the logger.

  Sections which specify handler configuration are exemplified by the
--- 1029,1033 ----
  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.

  Sections which specify handler configuration are exemplified by the