[Python-checkins] python/dist/src/Doc/lib libmailbox.tex,1.25,1.26

[bwarsaw@users.sourceforge.net]

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

Modified Files:
	libmailbox.tex 
Log Message:
Add some documentation which describes how to use the email package
instead of rfc822 as the Message factory.


Index: libmailbox.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libmailbox.tex,v
retrieving revision 1.25
retrieving revision 1.26
diff -C2 -d -r1.25 -r1.26
*** libmailbox.tex	23 Sep 2002 19:32:42 -0000	1.25
--- libmailbox.tex	20 Jun 2003 22:04:03 -0000	1.26
***************
*** 17,21 ****
  argument, \var{fp} by the \method{next()} method of the mailbox
  object.  The default is the \class{rfc822.Message} class (see the
! \refmodule{rfc822} module).
  
  For maximum portability, messages in a \UNIX-style mailbox are
--- 17,21 ----
  argument, \var{fp} by the \method{next()} method of the mailbox
  object.  The default is the \class{rfc822.Message} class (see the
! \refmodule{rfc822} module -- and the note below).
  
  For maximum portability, messages in a \UNIX-style mailbox are
***************
*** 84,87 ****
--- 84,121 ----
  \end{classdesc}
  
+ Note that because the \refmodule{rfc822} module is deprecated, it is
+ recommended that you use the \refmodule{email} package to create
+ message objects from a mailbox.  (The default can't be changed for
+ backwards compatibility reasons.)  The safest way to do this is with
+ bit of code:
+ 
+ \begin{verbatim}
+ import email
+ import email.Errors
+ import mailbox
+ 
+ def msgfactory(fp):
+     try:
+         return email.message_from_file(fp)
+     except email.Errors.MessageParseError:
+         # Don't return None since that will
+ 	# stop the mailbox iterator
+ 	return ''
+ 
+ mbox = mailbox.UnixMailbox(fp, msgfactory)
+ \end{verbatim}
+ 
+ The above wrapper is defensive against ill-formed MIME messages in the
+ mailbox, but you have to be prepared to receive the empty string from
+ the mailbox's \function{next()} method.  On the other hand, if you
+ know your mailbox contains only well-formed MIME messages, you can
+ simplify this to:
+ 
+ \begin{verbatim}
+ import email
+ import mailbox
+ 
+ mbox = mailbox.UnixMailbox(fp, email.message_from_file)
+ \end{verbatim}
  
  \begin{seealso}