From 30dbd1429aa3c6e8854ea575ae7dd188ad000aa0 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Wed, 31 Jan 2001 22:14:01 +0000 Subject: [PATCH] Document the two changes to the mailbox.py module: - All constructors grow an optional argument `factory' which is a callable used when new message instances are created by the next() methods. Defaults to the rfc822.Message class. - A new subclass of UnixMailbox is added, called PortableUnixMailbox. It's identical to UnixMailbox, but uses a more portable test for From_ delimiter lines. With PortableUnixMailbox, any line that starts with "From " is considered a delimiter (this should really check for two newlines before the F, but it doesn't. --- Doc/lib/libmailbox.tex | 48 ++++++++++++++++++++++++++++++++++-------- Misc/NEWS | 7 ++++++ 2 files changed, 46 insertions(+), 9 deletions(-) diff --git a/Doc/lib/libmailbox.tex b/Doc/lib/libmailbox.tex index 082c061d607..07f99f4ae9e 100644 --- a/Doc/lib/libmailbox.tex +++ b/Doc/lib/libmailbox.tex @@ -8,33 +8,61 @@ This module defines a number of classes that allow easy and uniform access to mail messages in a (\UNIX{}) mailbox. -\begin{classdesc}{UnixMailbox}{fp} -Access a classic \UNIX{}-style mailbox, where all messages are contained -in a single file and separated by ``From name time'' lines. -The file object \var{fp} points to the mailbox file. +\begin{classdesc}{UnixMailbox}{fp\optional{, factory}} +Access to a classic \UNIX{}-style mailbox, where all messages are +contained in a single file and separate by ``From '' (a.k.a ``From_'') +lines. The file object \var{fp} points to the mailbox file. Optional +\var{factory} is a callable that should create new message objects. +It is called with one argument, \var{fp} by the \method{next()} +method. The default is the \class{rfc822.Message} class (see the +\refmodule{rfc822} module). + +For maximum portability, messages in a \UNIX{}-style mailbox are +separated by any line that begins exactly with the letters \emph{F}, +\emph{r}, \emph{o}, \emph{m}, \emph{[space]} if preceded by exactly two +newlines. Because of the wide-range of variations in practice, +nothing else on the From_ line should be considered. However, the +current implementation doesn't check for the leading two newlines. +This is usually fine for most applications. + +The \class{UnixMailbox} class implements a more strict version of +From_ line checking, using a regular expression that usually correctly +matched From_ delimiters. It considers delimiter line to be separated +by ``From name time'' lines. For maximum portability, use the +\class{PortableUnixMailbox} class instead. This +class is completely identical to \class{UnixMailbox} except that +individual messages are separated by only ``From '' lines. + +For more +information see +\url{http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html}. \end{classdesc} -\begin{classdesc}{MmdfMailbox}{fp} +\begin{classdesc}{MmdfMailbox}{fp\optional{, factory}} Access an MMDF-style mailbox, where all messages are contained in a single file and separated by lines consisting of 4 control-A characters. The file object \var{fp} points to the mailbox file. +Optional \var{factory} is as with the \class{UnixMailbox} class. \end{classdesc} -\begin{classdesc}{MHMailbox}{dirname} +\begin{classdesc}{MHMailbox}{dirname\optional{, factory}} Access an MH mailbox, a directory with each message in a separate file with a numeric name. The name of the mailbox directory is passed in \var{dirname}. +\var{factory} is as with the \class{UnixMailbox} class. \end{classdesc} -\begin{classdesc}{Maildir}{dirname} +\begin{classdesc}{Maildir}{dirname\optional{, factory}} Access a Qmail mail directory. All new and current mail for the mailbox specified by \var{dirname} is made available. +\var{factory} is as with the \class{UnixMailbox} class. \end{classdesc} -\begin{classdesc}{BabylMailbox}{fp} +\begin{classdesc}{BabylMailbox}{fp\optional{, factory}} Access a Babyl mailbox, which is similar to an MMDF mailbox. Mail messages start with a line containing only \code{'*** EOOH ***'} and end with a line containing only \code{'\e{}037\e{}014'}. +\var{factory} is as with the \class{UnixMailbox} class. \end{classdesc} @@ -44,7 +72,9 @@ All implementations of Mailbox objects have one externally visible method: \begin{methoddesc}[mailbox]{next}{} -Return the next message in the mailbox, as a \class{rfc822.Message} +Return the next message in the mailbox, created with the optional +\var{factory} argument passed into the mailbox object's constructor. +By defaul this is an \class{rfc822.Message} object (see the \refmodule{rfc822} module). Depending on the mailbox implementation the \var{fp} attribute of this object may be a true file object or a class instance simulating a file object, taking care diff --git a/Misc/NEWS b/Misc/NEWS index 2b9bb6645aa..5c633f04786 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -15,6 +15,13 @@ Core language, builtins, and interpreter Standard library +- mailbox.py now has a new class, PortableUnixMailbox which is + identical to UnixMailbox but uses a more portable scheme for + determining From_ separators. Also, the constructors for all the + classes in this module have a new optional `factory' argument, which + is a callable used when new message classes must be instantiated by + the next() method. + - random.py is now self-contained, and offers all the functionality of the now-deprecated whrandom.py. See the docs for details. random.py also supports new functions getstate() and setstate(), for saving