[Python-checkins] CVS: python/dist/src/Doc/lib librfc822.tex,1.34,1.35

[Barry Warsaw]

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

Modified Files:
	librfc822.tex 
Log Message:
Updated the documentation in several respects:

- This module, despite its name, now should conform to RFC 2822, the
  update to RFC 822.

- This module doesn't just represent "email headers", but entire email
  messages.

- Added documentation for other useful public functions such as
  quote(), unquote(), praseaddr(), and dump_address_pair().


Index: librfc822.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/librfc822.tex,v
retrieving revision 1.34
retrieving revision 1.35
diff -C2 -r1.34 -r1.35
*** librfc822.tex	2001/05/22 22:00:40	1.34
--- librfc822.tex	2001/07/16 20:47:58	1.35
***************
*** 1,14 ****
  \section{\module{rfc822} ---
!          Parse RFC 822 mail headers}
  
  \declaremodule{standard}{rfc822}
! \modulesynopsis{Parse \rfc{822} style mail headers.}
  
! This module defines a class, \class{Message}, which represents a
! collection of ``email headers'' as defined by the Internet standard
! \rfc{822}.  It is used in various contexts, usually to read such
! headers from a file.  This module also defines a helper class 
! \class{AddressList} for parsing \rfc{822} addresses.  Please refer to
! the RFC for information on the specific syntax of \rfc{822} headers.
  
  The \refmodule{mailbox}\refstmodindex{mailbox} module provides classes 
--- 1,19 ----
  \section{\module{rfc822} ---
!          Parse RFC 2822 mail headers}
  
  \declaremodule{standard}{rfc822}
! \modulesynopsis{Parse \rfc{2822} style mail messages.}
  
! This module defines a class, \class{Message}, which represents an
! ``email message'' as defined by the Internet standard
! \rfc{2822}\footnote{This module originally conformed to \rfc{822},
! hence the name.  Since then, \rfc{2822} has been released as an
! update to \rfc{822}.  This module should be considered
! \rfc{2822}-conformant, especially in cases where the
! syntax or semantics have changed since \rfc{822}.}.  Such messages
! consist of a collection of message headers, and a message body.  This
! module also defines a helper class
! \class{AddressList} for parsing \rfc{2822} addresses.  Please refer to
! the RFC for information on the specific syntax of \rfc{2822} messages.
  
  The \refmodule{mailbox}\refstmodindex{mailbox} module provides classes 
***************
*** 51,63 ****
  \begin{classdesc}{AddressList}{field}
  You may instantiate the \class{AddressList} helper class using a single
! string parameter, a comma-separated list of \rfc{822} addresses to be
  parsed.  (The parameter \code{None} yields an empty list.)
  \end{classdesc}
  
  \begin{funcdesc}{parsedate}{date}
! Attempts to parse a date according to the rules in \rfc{822}.
  however, some mailers don't follow that format as specified, so
  \function{parsedate()} tries to guess correctly in such cases. 
! \var{date} is a string containing an \rfc{822} date, such as 
  \code{'Mon, 20 Nov 1995 19:12:08 -0500'}.  If it succeeds in parsing
  the date, \function{parsedate()} returns a 9-tuple that can be passed
--- 56,95 ----
  \begin{classdesc}{AddressList}{field}
  You may instantiate the \class{AddressList} helper class using a single
! string parameter, a comma-separated list of \rfc{2822} addresses to be
  parsed.  (The parameter \code{None} yields an empty list.)
  \end{classdesc}
  
+ \begin{funcdesc}{quote}{str}
+ Return a new string with backslashes in \var{str} replaced by two
+ backslashes and double quotes replaced by backslash-double quote.
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{unquote}{str}
+ Return a new string which is an \emph{unquoted} version of \var{str}.
+ If \var{str} ends and begins with double quotes, they are stripped
+ off.  Likewise if \var{str} ends and begins with angle brackets, they
+ are stripped off.
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{parseaddr}{address}
+ Parse address -- which should be the value of some address-containing
+ field such as \code{To:} or \code{Cc:} -- into its constituent
+ ``realname'' and ``email address'' parts.  Returns a tuple of that
+ information, unless the parse fails, in which case a 2-tuple of
+ \code{(None, None)} is returned.
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{dump_address_pair}{pair}
+ The inverse of \method{parseaddr()}, this takes a 2-tuple of the form
+ \code{(realname, email_address)} and returns the string value suitable
+ for a \code{To:} or \code{Cc:} header.  If the first element of
+ \var{pair} is false, then the second element is returned unmodified.
+ \end{funcdesc}
+ 
  \begin{funcdesc}{parsedate}{date}
! Attempts to parse a date according to the rules in \rfc{2822}.
  however, some mailers don't follow that format as specified, so
  \function{parsedate()} tries to guess correctly in such cases. 
! \var{date} is a string containing an \rfc{2822} date, such as 
  \code{'Mon, 20 Nov 1995 19:12:08 -0500'}.  If it succeeds in parsing
  the date, \function{parsedate()} returns a 9-tuple that can be passed
***************
*** 75,79 ****
  offset is the opposite of the sign of the \code{time.timezone}
  variable for the same timezone; the latter variable follows the
! \POSIX{} standard while this module follows \rfc{822}.)  If the input
  string has no timezone, the last element of the tuple returned is
  \code{None}.  Note that fields 6, 7, and 8 of the result tuple are not
--- 107,111 ----
  offset is the opposite of the sign of the \code{time.timezone}
  variable for the same timezone; the latter variable follows the
! \POSIX{} standard while this module follows \rfc{2822}.)  If the input
  string has no timezone, the last element of the tuple returned is
  \code{None}.  Note that fields 6, 7, and 8 of the result tuple are not
***************
*** 110,114 ****
  \begin{methoddesc}{isheader}{line}
  Returns a line's canonicalized fieldname (the dictionary key that will
! be used to index it) if the line is a legal \rfc{822} header; otherwise
  returns None (implying that parsing should stop here and the line be
  pushed back on the input stream).  It is sometimes useful to override
--- 142,146 ----
  \begin{methoddesc}{isheader}{line}
  Returns a line's canonicalized fieldname (the dictionary key that will
! be used to index it) if the line is a legal \rfc{2822} header; otherwise
  returns None (implying that parsing should stop here and the line be
  pushed back on the input stream).  It is sometimes useful to override