Update of /cvsroot/python/python/nondist/sandbox/mailbox
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv2755
Modified Files:
libmailbox.tex mailbox.py
Log Message:
* Add a documentation section on exceptions.
* Make a couple small fixes.
Index: libmailbox.tex
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/mailbox/libmailbox.tex,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -d -r1.15 -r1.16
--- libmailbox.tex 23 Aug 2005 03:43:11 -0000 1.15
+++ libmailbox.tex 23 Aug 2005 19:53:33 -0000 1.16
@@ -265,8 +265,8 @@
\begin{notice}
The Maildir specification requires the use of a colon (\character{:}) in
-certain message file names. Some operating systems do not permit this character
-in file names, however. If you wish to use a Maildir-like format on such an
+certain message file names. However, some operating systems do not permit this
+character in file names, If you wish to use a Maildir-like format on such an
operating system, you should specify another character to use instead. The
exclamation point (\character{!}) is a popular choice. For example:
\begin{verbatim}
@@ -365,12 +365,12 @@
messages in an mbox mailbox are stored in a single file with the beginning of
each message indicated by a line whose first five characters are "From~".
-Several variations of the mbox format exist to address perceived shortcomings.
-In the interest of compatibility, \class{mbox} implements the original format,
-which is sometimes referred to as \dfn{mboxo}. This means that the
-\mailheader{Content-Length} header, if present, is ignored and that any
+Several variations of the mbox format exist to address perceived shortcomings
+in the original. In the interest of compatibility, \class{mbox} implements the
+original format, which is sometimes referred to as \dfn{mboxo}. This means that
+the \mailheader{Content-Length} header, if present, is ignored and that any
occurrences of "From~" at the beginning of a line in a message body are
-transformed to ">From~" when storing the message although occurences of
+transformed to ">From~" when storing the message, although occurences of
">From~" are not transformed to "From~" when reading the message.
Some \class{Mailbox} methods implemented by \class{mbox} deserve special
@@ -423,9 +423,9 @@
\file{.mh_sequences} in each folder.
The \class{MH} class manipulates MH mailboxes, but it does not attempt to
-emulate all of \program{mh}'s behaviors. In particular, it does not access or
-modify the \file{context} or \file{.mh_profile} files that are used by
-\program{mh} to store its state and configuration.
+emulate all of \program{mh}'s behaviors. In particular, it does not modify and
+is not affected by the \file{context} or \file{.mh_profile} files that are used
+by \program{mh} to store its state and configuration.
\class{MH} instances have all of the methods of \class{Mailbox} in addition to
the following:
@@ -503,7 +503,7 @@
\begin{seealso}
\seelink{http://www.nongnu.org/nmh/}{nmh - Message Handling System}{Home page
-of \program{nmh}, a modern version of the original \program{mh}.}
+of \program{nmh}, an updated version of the original \program{mh}.}
\seelink{http://www.ics.uci.edu/\tilde{}mh/book/}{MH \& nmh: Email for Users \&
Programmers}{A GPL-licensed book on \program{mh} and \program{nmh}, with some
information on the mailbox format.}
@@ -521,12 +521,12 @@
mailbox is created if it does not exist.
\end{classdesc}
-Babyl is a single-file mailbox format invented for the Rmail mail user agent
+Babyl is a single-file mailbox format used by the Rmail mail user agent
included with Emacs. The beginning of a message is indicated by a line
-containing exactly the two characters Control-Underscore
+containing the two characters Control-Underscore
(\character{\textbackslash037}) and Control-L (\character{\textbackslash014}).
The end of a message is indicated by the start of the next message or, in the
-case of the last message, a line containing only a Control-Underscore
+case of the last message, a line containing a Control-Underscore
(\character{\textbackslash037}) character.
Messages in a Babyl mailbox have two sets of headers, original headers and
@@ -590,7 +590,7 @@
Control-A (\character{\textbackslash001}) characters. As with the mbox format,
the beginning of each message is indicated by a line whose first five
characters are "From~", but additional occurrences of "From~" are not
-transformed to ">From~" when storing messages because the additional message
+transformed to ">From~" when storing messages because the extra message
separator lines prevent mistaking such occurrences for the starts of subsequent
messages.
@@ -681,7 +681,8 @@
subdirectory) or "cur" (if the message should be stored in the \file{cur}
subdirectory). \note{A message is typically moved from \file{new} to \file{cur}
after its mailbox has been accessed, whether or not the message is has been
-read. A message has been read if \code{"S" not in get_flags()} is \code{True}.}
+read. A message \code{msg} has been read if \code{"S" not in msg.get_flags()}
+is \code{True}.}
\end{methoddesc}
\begin{methoddesc}{set_subdir}{subdir}
@@ -1183,6 +1184,39 @@
\lineii{A flag}{A flag}
\end{tableii}
+\subsection{Exceptions}
+\label{mailbox-deprecated}
+
+The following exception classes are defined in the \module{mailbox} module:
+
+\begin{classdesc}{Error}{}
+The based class for all other module-specific exceptions.
+\end{classdesc}
+
+\begin{classdesc}{NoSuchMailboxError}{}
+Raised when a mailbox is expected but is not found, such as when instantiating
+a \class{Mailbox} subclass with a path that does not exist (and with the
+\var{create} parameter set to \code{False}), or when opening a folder that does
+not exist.
+\end{classdesc}
+
+\begin{classdesc}{NotEmptyErrorError}{}
+Raised when a mailbox is not empty but is expected to be, such as when deleting
+a folder that contains messages.
+\end{classdesc}
+
+\begin{classdesc}{ExternalClashError}{}
+Raised when some mailbox-related condition beyond the control of the program
+causes it to be unable to proceed, such as when failing to acquire a lock that
+another program already holds a lock, or when a uniquely-generated file name
+already exists.
+\end{classdesc}
+
+\begin{classdesc}{FormatError}{}
+Raised when the data in a file cannot be parsed, such as when an \class{MH}
+instance attempts to read a corrupted \file{.mh_sequences} file.
+\end{classdesc}
+
\subsection{Deprecated classes and methods}
\label{mailbox-deprecated}
@@ -1302,8 +1336,8 @@
return email.message_from_file(fp)
except email.Errors.MessageParseError:
# Don't return None since that will
- # stop the mailbox iterator
- return ''
+ # stop the mailbox iterator
+ return ''
mbox = mailbox.UnixMailbox(fp, msgfactory)
\end{verbatim}
Index: mailbox.py
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/mailbox/mailbox.py,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -d -r1.16 -r1.17
--- mailbox.py 23 Aug 2005 03:43:11 -0000 1.16
+++ mailbox.py 23 Aug 2005 19:53:33 -0000 1.17
@@ -347,7 +347,7 @@
"""Lock the mailbox."""
return
- def unlock(self, f=None):
+ def unlock(self):
"""Unlock the mailbox if it is locked."""
return
@@ -1143,7 +1143,8 @@
def get_file(self, key):
"""Return a file-like representation or raise a KeyError."""
- return StringIO.StringIO(self.get_string(key))
+ return StringIO.StringIO(self.get_string(key).replace('\n',
+ os.linesep))
def get_labels(self):
"""Return a list of user-defined labels in the mailbox."""