diff options
Diffstat (limited to 'Doc/lib/libmailbox.tex')
| -rw-r--r-- | Doc/lib/libmailbox.tex | 1443 |
1 files changed, 0 insertions, 1443 deletions
diff --git a/Doc/lib/libmailbox.tex b/Doc/lib/libmailbox.tex deleted file mode 100644 index c3e7ffd..0000000 --- a/Doc/lib/libmailbox.tex +++ /dev/null @@ -1,1443 +0,0 @@ -\section{\module{mailbox} --- - Manipulate mailboxes in various formats} - -\declaremodule{}{mailbox} -\moduleauthor{Gregory K.~Johnson}{gkj@gregorykjohnson.com} -\sectionauthor{Gregory K.~Johnson}{gkj@gregorykjohnson.com} -\modulesynopsis{Manipulate mailboxes in various formats} - - -This module defines two classes, \class{Mailbox} and \class{Message}, for -accessing and manipulating on-disk mailboxes and the messages they contain. -\class{Mailbox} offers a dictionary-like mapping from keys to messages. -\class{Message} extends the \module{email.Message} module's \class{Message} -class with format-specific state and behavior. Supported mailbox formats are -Maildir, mbox, MH, Babyl, and MMDF. - -\begin{seealso} - \seemodule{email}{Represent and manipulate messages.} -\end{seealso} - -\subsection{\class{Mailbox} objects} -\label{mailbox-objects} - -\begin{classdesc*}{Mailbox} -A mailbox, which may be inspected and modified. -\end{classdesc*} - -The \class{Mailbox} class defines an interface and -is not intended to be instantiated. Instead, format-specific -subclasses should inherit from \class{Mailbox} and your code -should instantiate a particular subclass. - -The \class{Mailbox} interface is dictionary-like, with small keys -corresponding to messages. Keys are issued by the \class{Mailbox} -instance with which they will be used and are only meaningful to that -\class{Mailbox} instance. A key continues to identify a message even -if the corresponding message is modified, such as by replacing it with -another message. - -Messages may be added to a \class{Mailbox} instance using the set-like -method \method{add()} and removed using a \code{del} statement or the -set-like methods \method{remove()} and \method{discard()}. - -\class{Mailbox} interface semantics differ from dictionary semantics in some -noteworthy ways. Each time a message is requested, a new -representation (typically a \class{Message} instance) is generated -based upon the current state of the mailbox. Similarly, when a message -is added to a \class{Mailbox} instance, the provided message -representation's contents are copied. In neither case is a reference -to the message representation kept by the \class{Mailbox} instance. - -The default \class{Mailbox} iterator iterates over message representations, not -keys as the default dictionary iterator does. Moreover, modification of a -mailbox during iteration is safe and well-defined. Messages added to the -mailbox after an iterator is created will not be seen by the iterator. Messages -removed from the mailbox before the iterator yields them will be silently -skipped, though using a key from an iterator may result in a -\exception{KeyError} exception if the corresponding message is subsequently -removed. - -\begin{notice}[warning] -Be very cautious when modifying mailboxes that might be -simultaneously changed by some other process. The safest mailbox -format to use for such tasks is Maildir; try to avoid using -single-file formats such as mbox for concurrent writing. If you're -modifying a mailbox, you -\emph{must} lock it by calling the \method{lock()} and -\method{unlock()} methods \emph{before} reading any messages in the file -or making any changes by adding or deleting a message. Failing to -lock the mailbox runs the risk of losing messages or corrupting the entire -mailbox. -\end{notice} - -\class{Mailbox} instances have the following methods: - -\begin{methoddesc}{add}{message} -Add \var{message} to the mailbox and return the key that has been assigned to -it. - -Parameter \var{message} may be a \class{Message} instance, an -\class{email.Message.Message} instance, a string, or a file-like object (which -should be open in text mode). If \var{message} is an instance of the -appropriate format-specific \class{Message} subclass (e.g., if it's an -\class{mboxMessage} instance and this is an \class{mbox} instance), its -format-specific information is used. Otherwise, reasonable defaults for -format-specific information are used. -\end{methoddesc} - -\begin{methoddesc}{remove}{key} -\methodline{__delitem__}{key} -\methodline{discard}{key} -Delete the message corresponding to \var{key} from the mailbox. - -If no such message exists, a \exception{KeyError} exception is raised if the -method was called as \method{remove()} or \method{__delitem__()} but no -exception is raised if the method was called as \method{discard()}. The -behavior of \method{discard()} may be preferred if the underlying mailbox -format supports concurrent modification by other processes. -\end{methoddesc} - -\begin{methoddesc}{__setitem__}{key, message} -Replace the message corresponding to \var{key} with \var{message}. Raise a -\exception{KeyError} exception if no message already corresponds to \var{key}. - -As with \method{add()}, parameter \var{message} may be a \class{Message} -instance, an \class{email.Message.Message} instance, a string, or a file-like -object (which should be open in text mode). If \var{message} is an instance of -the appropriate format-specific \class{Message} subclass (e.g., if it's an -\class{mboxMessage} instance and this is an \class{mbox} instance), its -format-specific information is used. Otherwise, the format-specific information -of the message that currently corresponds to \var{key} is left unchanged. -\end{methoddesc} - -\begin{methoddesc}{iterkeys}{} -\methodline{keys}{} -Return an iterator over all keys if called as \method{iterkeys()} or return a -list of keys if called as \method{keys()}. -\end{methoddesc} - -\begin{methoddesc}{itervalues}{} -\methodline{__iter__}{} -\methodline{values}{} -Return an iterator over representations of all messages if called as -\method{itervalues()} or \method{__iter__()} or return a list of such -representations if called as \method{values()}. The messages are represented as -instances of the appropriate format-specific \class{Message} subclass unless a -custom message factory was specified when the \class{Mailbox} instance was -initialized. \note{The behavior of \method{__iter__()} is unlike that of -dictionaries, which iterate over keys.} -\end{methoddesc} - -\begin{methoddesc}{iteritems}{} -\methodline{items}{} -Return an iterator over (\var{key}, \var{message}) pairs, where \var{key} is a -key and \var{message} is a message representation, if called as -\method{iteritems()} or return a list of such pairs if called as -\method{items()}. The messages are represented as instances of the appropriate -format-specific \class{Message} subclass unless a custom message factory was -specified when the \class{Mailbox} instance was initialized. -\end{methoddesc} - -\begin{methoddesc}{get}{key\optional{, default=None}} -\methodline{__getitem__}{key} -Return a representation of the message corresponding to \var{key}. If no such -message exists, \var{default} is returned if the method was called as -\method{get()} and a \exception{KeyError} exception is raised if the method was -called as \method{__getitem__()}. The message is represented as an instance of -the appropriate format-specific \class{Message} subclass unless a custom -message factory was specified when the \class{Mailbox} instance was -initialized. -\end{methoddesc} - -\begin{methoddesc}{get_message}{key} -Return a representation of the message corresponding to \var{key} as an -instance of the appropriate format-specific \class{Message} subclass, or raise -a \exception{KeyError} exception if no such message exists. -\end{methoddesc} - -\begin{methoddesc}{get_string}{key} -Return a string representation of the message corresponding to \var{key}, or -raise a \exception{KeyError} exception if no such message exists. -\end{methoddesc} - -\begin{methoddesc}{get_file}{key} -Return a file-like representation of the message corresponding to \var{key}, -or raise a \exception{KeyError} exception if no such message exists. The -file-like object behaves as if open in binary mode. This file should be closed -once it is no longer needed. - -\note{Unlike other representations of messages, file-like representations are -not necessarily independent of the \class{Mailbox} instance that created them -or of the underlying mailbox. More specific documentation is provided by each -subclass.} -\end{methoddesc} - -\begin{methoddesc}{has_key}{key} -\methodline{__contains__}{key} -Return \code{True} if \var{key} corresponds to a message, \code{False} -otherwise. -\end{methoddesc} - -\begin{methoddesc}{__len__}{} -Return a count of messages in the mailbox. -\end{methoddesc} - -\begin{methoddesc}{clear}{} -Delete all messages from the mailbox. -\end{methoddesc} - -\begin{methoddesc}{pop}{key\optional{, default}} -Return a representation of the message corresponding to \var{key} and delete -the message. If no such message exists, return \var{default} if it was supplied -or else raise a \exception{KeyError} exception. The message is represented as -an instance of the appropriate format-specific \class{Message} subclass unless -a custom message factory was specified when the \class{Mailbox} instance was -initialized. -\end{methoddesc} - -\begin{methoddesc}{popitem}{} -Return an arbitrary (\var{key}, \var{message}) pair, where \var{key} is a key -and \var{message} is a message representation, and delete the corresponding -message. If the mailbox is empty, raise a \exception{KeyError} exception. The -message is represented as an instance of the appropriate format-specific -\class{Message} subclass unless a custom message factory was specified when the -\class{Mailbox} instance was initialized. -\end{methoddesc} - -\begin{methoddesc}{update}{arg} -Parameter \var{arg} should be a \var{key}-to-\var{message} mapping or an -iterable of (\var{key}, \var{message}) pairs. Updates the mailbox so that, for -each given \var{key} and \var{message}, the message corresponding to \var{key} -is set to \var{message} as if by using \method{__setitem__()}. As with -\method{__setitem__()}, each \var{key} must already correspond to a message in -the mailbox or else a \exception{KeyError} exception will be raised, so in -general it is incorrect for \var{arg} to be a \class{Mailbox} instance. -\note{Unlike with dictionaries, keyword arguments are not supported.} -\end{methoddesc} - -\begin{methoddesc}{flush}{} -Write any pending changes to the filesystem. For some \class{Mailbox} -subclasses, changes are always written immediately and \method{flush()} does -nothing, but you should still make a habit of calling this method. -\end{methoddesc} - -\begin{methoddesc}{lock}{} -Acquire an exclusive advisory lock on the mailbox so that other processes know -not to modify it. An \exception{ExternalClashError} is raised if the lock is -not available. The particular locking mechanisms used depend upon the mailbox -format. You should \emph{always} lock the mailbox before making any -modifications to its contents. -\end{methoddesc} - -\begin{methoddesc}{unlock}{} -Release the lock on the mailbox, if any. -\end{methoddesc} - -\begin{methoddesc}{close}{} -Flush the mailbox, unlock it if necessary, and close any open files. For some -\class{Mailbox} subclasses, this method does nothing. -\end{methoddesc} - - -\subsubsection{\class{Maildir}} -\label{mailbox-maildir} - -\begin{classdesc}{Maildir}{dirname\optional{, factory=rfc822.Message\optional{, -create=True}}} -A subclass of \class{Mailbox} for mailboxes in Maildir format. Parameter -\var{factory} is a callable object that accepts a file-like message -representation (which behaves as if opened in binary mode) and returns a custom -representation. If \var{factory} is \code{None}, \class{MaildirMessage} is used -as the default message representation. If \var{create} is \code{True}, the -mailbox is created if it does not exist. - -It is for historical reasons that \var{factory} defaults to -\class{rfc822.Message} and that \var{dirname} is named as such rather than -\var{path}. For a \class{Maildir} instance that behaves like instances of other -\class{Mailbox} subclasses, set \var{factory} to \code{None}. -\end{classdesc} - -Maildir is a directory-based mailbox format invented for the qmail mail -transfer agent and now widely supported by other programs. Messages in a -Maildir mailbox are stored in separate files within a common directory -structure. This design allows Maildir mailboxes to be accessed and modified by -multiple unrelated programs without data corruption, so file locking is -unnecessary. - -Maildir mailboxes contain three subdirectories, namely: \file{tmp}, \file{new}, -and \file{cur}. Messages are created momentarily in the \file{tmp} subdirectory -and then moved to the \file{new} subdirectory to finalize delivery. A mail user -agent may subsequently move the message to the \file{cur} subdirectory and -store information about the state of the message in a special "info" section -appended to its file name. - -Folders of the style introduced by the Courier mail transfer agent are also -supported. Any subdirectory of the main mailbox is considered a folder if -\character{.} is the first character in its name. Folder names are represented -by \class{Maildir} without the leading \character{.}. Each folder is itself a -Maildir mailbox but should not contain other folders. Instead, a logical -nesting is indicated using \character{.} to delimit levels, e.g., -"Archived.2005.07". - -\begin{notice} -The Maildir specification requires the use of a colon (\character{:}) in -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} -import mailbox -mailbox.Maildir.colon = '!' -\end{verbatim} -The \member{colon} attribute may also be set on a per-instance basis. -\end{notice} - -\class{Maildir} instances have all of the methods of \class{Mailbox} in -addition to the following: - -\begin{methoddesc}{list_folders}{} -Return a list of the names of all folders. -\end{methoddesc} - -\begin{methoddesc}{get_folder}{folder} -Return a \class{Maildir} instance representing the folder whose name is -\var{folder}. A \exception{NoSuchMailboxError} exception is raised if the -folder does not exist. -\end{methoddesc} - -\begin{methoddesc}{add_folder}{folder} -Create a folder whose name is \var{folder} and return a \class{Maildir} -instance representing it. -\end{methoddesc} - -\begin{methoddesc}{remove_folder}{folder} -Delete the folder whose name is \var{folder}. If the folder contains any -messages, a \exception{NotEmptyError} exception will be raised and the folder -will not be deleted. -\end{methoddesc} - -\begin{methoddesc}{clean}{} -Delete temporary files from the mailbox that have not been accessed in the -last 36 hours. The Maildir specification says that mail-reading programs -should do this occasionally. -\end{methoddesc} - -Some \class{Mailbox} methods implemented by \class{Maildir} deserve special -remarks: - -\begin{methoddesc}{add}{message} -\methodline[Maildir]{__setitem__}{key, message} -\methodline[Maildir]{update}{arg} -\warning{These methods generate unique file names based upon the current -process ID. When using multiple threads, undetected name clashes may occur and -cause corruption of the mailbox unless threads are coordinated to avoid using -these methods to manipulate the same mailbox simultaneously.} -\end{methoddesc} - -\begin{methoddesc}{flush}{} -All changes to Maildir mailboxes are immediately applied, so this method does -nothing. -\end{methoddesc} - -\begin{methoddesc}{lock}{} -\methodline{unlock}{} -Maildir mailboxes do not support (or require) locking, so these methods do -nothing. -\end{methoddesc} - -\begin{methoddesc}{close}{} -\class{Maildir} instances do not keep any open files and the underlying -mailboxes do not support locking, so this method does nothing. -\end{methoddesc} - -\begin{methoddesc}{get_file}{key} -Depending upon the host platform, it may not be possible to modify or remove -the underlying message while the returned file remains open. -\end{methoddesc} - -\begin{seealso} - \seelink{http://www.qmail.org/man/man5/maildir.html}{maildir man page from - qmail}{The original specification of the format.} - \seelink{http://cr.yp.to/proto/maildir.html}{Using maildir format}{Notes - on Maildir by its inventor. Includes an updated name-creation scheme and - details on "info" semantics.} - \seelink{http://www.courier-mta.org/?maildir.html}{maildir man page from - Courier}{Another specification of the format. Describes a common extension - for supporting folders.} -\end{seealso} - -\subsubsection{\class{mbox}} -\label{mailbox-mbox} - -\begin{classdesc}{mbox}{path\optional{, factory=None\optional{, create=True}}} -A subclass of \class{Mailbox} for mailboxes in mbox format. Parameter -\var{factory} is a callable object that accepts a file-like message -representation (which behaves as if opened in binary mode) and returns a custom -representation. If \var{factory} is \code{None}, \class{mboxMessage} is used as -the default message representation. If \var{create} is \code{True}, the mailbox -is created if it does not exist. -\end{classdesc} - -The mbox format is the classic format for storing mail on \UNIX{} systems. All -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 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 -">From~" are not transformed to "From~" when reading the message. - -Some \class{Mailbox} methods implemented by \class{mbox} deserve special -remarks: - -\begin{methoddesc}{get_file}{key} -Using the file after calling \method{flush()} or \method{close()} on the -\class{mbox} instance may yield unpredictable results or raise an exception. -\end{methoddesc} - -\begin{methoddesc}{lock}{} -\methodline{unlock}{} -Three locking mechanisms are used---dot locking and, if available, the -\cfunction{flock()} and \cfunction{lockf()} system calls. -\end{methoddesc} - -\begin{seealso} - \seelink{http://www.qmail.org/man/man5/mbox.html}{mbox man page from - qmail}{A specification of the format and its variations.} - \seelink{http://www.tin.org/bin/man.cgi?section=5\&topic=mbox}{mbox man - page from tin}{Another specification of the format, with details on - locking.} - \seelink{http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html} - {Configuring Netscape Mail on \UNIX{}: Why The Content-Length Format is - Bad}{An argument for using the original mbox format rather than a - variation.} - \seelink{http://homepages.tesco.net./\tilde{}J.deBoynePollard/FGA/mail-mbox-formats.html} - {"mbox" is a family of several mutually incompatible mailbox formats}{A - history of mbox variations.} -\end{seealso} - -\subsubsection{\class{MH}} -\label{mailbox-mh} - -\begin{classdesc}{MH}{path\optional{, factory=None\optional{, create=True}}} -A subclass of \class{Mailbox} for mailboxes in MH format. Parameter -\var{factory} is a callable object that accepts a file-like message -representation (which behaves as if opened in binary mode) and returns a custom -representation. If \var{factory} is \code{None}, \class{MHMessage} is used as -the default message representation. If \var{create} is \code{True}, the mailbox -is created if it does not exist. -\end{classdesc} - -MH is a directory-based mailbox format invented for the MH Message Handling -System, a mail user agent. Each message in an MH mailbox resides in its own -file. An MH mailbox may contain other MH mailboxes (called \dfn{folders}) in -addition to messages. Folders may be nested indefinitely. MH mailboxes also -support \dfn{sequences}, which are named lists used to logically group messages -without moving them to sub-folders. Sequences are defined in a file called -\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 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: - -\begin{methoddesc}{list_folders}{} -Return a list of the names of all folders. -\end{methoddesc} - -\begin{methoddesc}{get_folder}{folder} -Return an \class{MH} instance representing the folder whose name is -\var{folder}. A \exception{NoSuchMailboxError} exception is raised if the -folder does not exist. -\end{methoddesc} - -\begin{methoddesc}{add_folder}{folder} -Create a folder whose name is \var{folder} and return an \class{MH} instance -representing it. -\end{methoddesc} - -\begin{methoddesc}{remove_folder}{folder} -Delete the folder whose name is \var{folder}. If the folder contains any -messages, a \exception{NotEmptyError} exception will be raised and the folder -will not be deleted. -\end{methoddesc} - -\begin{methoddesc}{get_sequences}{} -Return a dictionary of sequence names mapped to key lists. If there are no -sequences, the empty dictionary is returned. -\end{methoddesc} - -\begin{methoddesc}{set_sequences}{sequences} -Re-define the sequences that exist in the mailbox based upon \var{sequences}, a -dictionary of names mapped to key lists, like returned by -\method{get_sequences()}. -\end{methoddesc} - -\begin{methoddesc}{pack}{} -Rename messages in the mailbox as necessary to eliminate gaps in numbering. -Entries in the sequences list are updated correspondingly. \note{Already-issued -keys are invalidated by this operation and should not be subsequently used.} -\end{methoddesc} - -Some \class{Mailbox} methods implemented by \class{MH} deserve special remarks: - -\begin{methoddesc}{remove}{key} -\methodline{__delitem__}{key} -\methodline{discard}{key} -These methods immediately delete the message. The MH convention of marking a -message for deletion by prepending a comma to its name is not used. -\end{methoddesc} - -\begin{methoddesc}{lock}{} -\methodline{unlock}{} -Three locking mechanisms are used---dot locking and, if available, the -\cfunction{flock()} and \cfunction{lockf()} system calls. For MH mailboxes, -locking the mailbox means locking the \file{.mh_sequences} file and, only for -the duration of any operations that affect them, locking individual message -files. -\end{methoddesc} - -\begin{methoddesc}{get_file}{key} -Depending upon the host platform, it may not be possible to remove the -underlying message while the returned file remains open. -\end{methoddesc} - -\begin{methoddesc}{flush}{} -All changes to MH mailboxes are immediately applied, so this method does -nothing. -\end{methoddesc} - -\begin{methoddesc}{close}{} -\class{MH} instances do not keep any open files, so this method is equivelant -to \method{unlock()}. -\end{methoddesc} - -\begin{seealso} -\seelink{http://www.nongnu.org/nmh/}{nmh - Message Handling System}{Home page -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.} -\end{seealso} - -\subsubsection{\class{Babyl}} -\label{mailbox-babyl} - -\begin{classdesc}{Babyl}{path\optional{, factory=None\optional{, create=True}}} -A subclass of \class{Mailbox} for mailboxes in Babyl format. Parameter -\var{factory} is a callable object that accepts a file-like message -representation (which behaves as if opened in binary mode) and returns a custom -representation. If \var{factory} is \code{None}, \class{BabylMessage} is used -as the default message representation. If \var{create} is \code{True}, the -mailbox is created if it does not exist. -\end{classdesc} - -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 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 a Control-Underscore -(\character{\textbackslash037}) character. - -Messages in a Babyl mailbox have two sets of headers, original headers and -so-called visible headers. Visible headers are typically a subset of the -original headers that have been reformatted or abridged to be more attractive. -Each message in a Babyl mailbox also has an accompanying list of \dfn{labels}, -or short strings that record extra information about the message, and a list of -all user-defined labels found in the mailbox is kept in the Babyl options -section. - -\class{Babyl} instances have all of the methods of \class{Mailbox} in addition -to the following: - -\begin{methoddesc}{get_labels}{} -Return a list of the names of all user-defined labels used in the mailbox. -\note{The actual messages are inspected to determine which labels exist in the -mailbox rather than consulting the list of labels in the Babyl options section, -but the Babyl section is updated whenever the mailbox is modified.} -\end{methoddesc} - -Some \class{Mailbox} methods implemented by \class{Babyl} deserve special -remarks: - -\begin{methoddesc}{get_file}{key} -In Babyl mailboxes, the headers of a message are not stored contiguously with -the body of the message. To generate a file-like representation, the headers -and body are copied together into a \class{StringIO} instance (from the -\module{StringIO} module), which has an API identical to that of a file. As a -result, the file-like object is truly independent of the underlying mailbox but -does not save memory compared to a string representation. -\end{methoddesc} - -\begin{methoddesc}{lock}{} -\methodline{unlock}{} -Three locking mechanisms are used---dot locking and, if available, the -\cfunction{flock()} and \cfunction{lockf()} system calls. -\end{methoddesc} - -\begin{seealso} -\seelink{http://quimby.gnus.org/notes/BABYL}{Format of Version 5 Babyl Files}{A -specification of the Babyl format.} -\seelink{http://www.gnu.org/software/emacs/manual/html_node/Rmail.html}{Reading -Mail with Rmail}{The Rmail manual, with some information on Babyl semantics.} -\end{seealso} - -\subsubsection{\class{MMDF}} -\label{mailbox-mmdf} - -\begin{classdesc}{MMDF}{path\optional{, factory=None\optional{, create=True}}} -A subclass of \class{Mailbox} for mailboxes in MMDF format. Parameter -\var{factory} is a callable object that accepts a file-like message -representation (which behaves as if opened in binary mode) and returns a custom -representation. If \var{factory} is \code{None}, \class{MMDFMessage} is used as -the default message representation. If \var{create} is \code{True}, the mailbox -is created if it does not exist. -\end{classdesc} - -MMDF is a single-file mailbox format invented for the Multichannel Memorandum -Distribution Facility, a mail transfer agent. Each message is in the same form -as an mbox message but is bracketed before and after by lines containing four -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 extra message -separator lines prevent mistaking such occurrences for the starts of subsequent -messages. - -Some \class{Mailbox} methods implemented by \class{MMDF} deserve special -remarks: - -\begin{methoddesc}{get_file}{key} -Using the file after calling \method{flush()} or \method{close()} on the -\class{MMDF} instance may yield unpredictable results or raise an exception. -\end{methoddesc} - -\begin{methoddesc}{lock}{} -\methodline{unlock}{} -Three locking mechanisms are used---dot locking and, if available, the -\cfunction{flock()} and \cfunction{lockf()} system calls. -\end{methoddesc} - -\begin{seealso} -\seelink{http://www.tin.org/bin/man.cgi?section=5\&topic=mmdf}{mmdf man page -from tin}{A specification of MMDF format from the documentation of tin, a -newsreader.} -\seelink{http://en.wikipedia.org/wiki/MMDF}{MMDF}{A Wikipedia article -describing the Multichannel Memorandum Distribution Facility.} -\end{seealso} - -\subsection{\class{Message} objects} -\label{mailbox-message-objects} - -\begin{classdesc}{Message}{\optional{message}} -A subclass of the \module{email.Message} module's \class{Message}. Subclasses -of \class{mailbox.Message} add mailbox-format-specific state and behavior. - -If \var{message} is omitted, the new instance is created in a default, empty -state. If \var{message} is an \class{email.Message.Message} instance, its -contents are copied; furthermore, any format-specific information is converted -insofar as possible if \var{message} is a \class{Message} instance. If -\var{message} is a string or a file, it should contain an \rfc{2822}-compliant -message, which is read and parsed. -\end{classdesc} - -The format-specific state and behaviors offered by subclasses vary, but in -general it is only the properties that are not specific to a particular mailbox -that are supported (although presumably the properties are specific to a -particular mailbox format). For example, file offsets for single-file mailbox -formats and file names for directory-based mailbox formats are not retained, -because they are only applicable to the original mailbox. But state such as -whether a message has been read by the user or marked as important is retained, -because it applies to the message itself. - -There is no requirement that \class{Message} instances be used to represent -messages retrieved using \class{Mailbox} instances. In some situations, the -time and memory required to generate \class{Message} representations might not -not acceptable. For such situations, \class{Mailbox} instances also offer -string and file-like representations, and a custom message factory may be -specified when a \class{Mailbox} instance is initialized. - -\subsubsection{\class{MaildirMessage}} -\label{mailbox-maildirmessage} - -\begin{classdesc}{MaildirMessage}{\optional{message}} -A message with Maildir-specific behaviors. Parameter \var{message} -has the same meaning as with the \class{Message} constructor. -\end{classdesc} - -Typically, a mail user agent application moves all of the messages in the -\file{new} subdirectory to the \file{cur} subdirectory after the first time the -user opens and closes the mailbox, recording that the messages are old whether -or not they've actually been read. Each message in \file{cur} has an "info" -section added to its file name to store information about its state. (Some mail -readers may also add an "info" section to messages in \file{new}.) The "info" -section may take one of two forms: it may contain "2," followed by a list of -standardized flags (e.g., "2,FR") or it may contain "1," followed by so-called -experimental information. Standard flags for Maildir messages are as follows: - -\begin{tableiii}{l|l|l}{textrm}{Flag}{Meaning}{Explanation} -\lineiii{D}{Draft}{Under composition} -\lineiii{F}{Flagged}{Marked as important} -\lineiii{P}{Passed}{Forwarded, resent, or bounced} -\lineiii{R}{Replied}{Replied to} -\lineiii{S}{Seen}{Read} -\lineiii{T}{Trashed}{Marked for subsequent deletion} -\end{tableiii} - -\class{MaildirMessage} instances offer the following methods: - -\begin{methoddesc}{get_subdir}{} -Return either "new" (if the message should be stored in the \file{new} -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 \code{msg} has been read if \code{"S" not in msg.get_flags()} -is \code{True}.} -\end{methoddesc} - -\begin{methoddesc}{set_subdir}{subdir} -Set the subdirectory the message should be stored in. Parameter \var{subdir} -must be either "new" or "cur". -\end{methoddesc} - -\begin{methoddesc}{get_flags}{} -Return a string specifying the flags that are currently set. If the message -complies with the standard Maildir format, the result is the concatenation in -alphabetical order of zero or one occurrence of each of \character{D}, -\character{F}, \character{P}, \character{R}, \character{S}, and \character{T}. -The empty string is returned if no flags are set or if "info" contains -experimental semantics. -\end{methoddesc} - -\begin{methoddesc}{set_flags}{flags} -Set the flags specified by \var{flags} and unset all others. -\end{methoddesc} - -\begin{methoddesc}{add_flag}{flag} -Set the flag(s) specified by \var{flag} without changing other flags. To add -more than one flag at a time, \var{flag} may be a string of more than one -character. The current "info" is overwritten whether or not it contains -experimental information rather than -flags. -\end{methoddesc} - -\begin{methoddesc}{remove_flag}{flag} -Unset the flag(s) specified by \var{flag} without changing other flags. To -remove more than one flag at a time, \var{flag} maybe a string of more than one -character. If "info" contains experimental information rather than flags, the -current "info" is not modified. -\end{methoddesc} - -\begin{methoddesc}{get_date}{} -Return the delivery date of the message as a floating-point number representing -seconds since the epoch. -\end{methoddesc} - -\begin{methoddesc}{set_date}{date} -Set the delivery date of the message to \var{date}, a floating-point number -representing seconds since the epoch. -\end{methoddesc} - -\begin{methoddesc}{get_info}{} -Return a string containing the "info" for a message. This is useful for -accessing and modifying "info" that is experimental (i.e., not a list of -flags). -\end{methoddesc} - -\begin{methoddesc}{set_info}{info} -Set "info" to \var{info}, which should be a string. -\end{methoddesc} - -When a \class{MaildirMessage} instance is created based upon an -\class{mboxMessage} or \class{MMDFMessage} instance, the \mailheader{Status} -and \mailheader{X-Status} headers are omitted and the following conversions -take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{mboxMessage} or \class{MMDFMessage} state} -\lineii{"cur" subdirectory}{O flag} -\lineii{F flag}{F flag} -\lineii{R flag}{A flag} -\lineii{S flag}{R flag} -\lineii{T flag}{D flag} -\end{tableii} - -When a \class{MaildirMessage} instance is created based upon an -\class{MHMessage} instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MHMessage} state} -\lineii{"cur" subdirectory}{"unseen" sequence} -\lineii{"cur" subdirectory and S flag}{no "unseen" sequence} -\lineii{F flag}{"flagged" sequence} -\lineii{R flag}{"replied" sequence} -\end{tableii} - -When a \class{MaildirMessage} instance is created based upon a -\class{BabylMessage} instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{BabylMessage} state} -\lineii{"cur" subdirectory}{"unseen" label} -\lineii{"cur" subdirectory and S flag}{no "unseen" label} -\lineii{P flag}{"forwarded" or "resent" label} -\lineii{R flag}{"answered" label} -\lineii{T flag}{"deleted" label} -\end{tableii} - -\subsubsection{\class{mboxMessage}} -\label{mailbox-mboxmessage} - -\begin{classdesc}{mboxMessage}{\optional{message}} -A message with mbox-specific behaviors. Parameter \var{message} has the same -meaning as with the \class{Message} constructor. -\end{classdesc} - -Messages in an mbox mailbox are stored together in a single file. The sender's -envelope address and the time of delivery are typically stored in a line -beginning with "From~" that is used to indicate the start of a message, though -there is considerable variation in the exact format of this data among mbox -implementations. Flags that indicate the state of the message, such as whether -it has been read or marked as important, are typically stored in -\mailheader{Status} and \mailheader{X-Status} headers. - -Conventional flags for mbox messages are as follows: - -\begin{tableiii}{l|l|l}{textrm}{Flag}{Meaning}{Explanation} -\lineiii{R}{Read}{Read} -\lineiii{O}{Old}{Previously detected by MUA} -\lineiii{D}{Deleted}{Marked for subsequent deletion} -\lineiii{F}{Flagged}{Marked as important} -\lineiii{A}{Answered}{Replied to} -\end{tableiii} - -The "R" and "O" flags are stored in the \mailheader{Status} header, and the -"D", "F", and "A" flags are stored in the \mailheader{X-Status} header. The -flags and headers typically appear in the order mentioned. - -\class{mboxMessage} instances offer the following methods: - -\begin{methoddesc}{get_from}{} -Return a string representing the "From~" line that marks the start of the -message in an mbox mailbox. The leading "From~" and the trailing newline are -excluded. -\end{methoddesc} - -\begin{methoddesc}{set_from}{from_\optional{, time_=None}} -Set the "From~" line to \var{from_}, which should be specified without a -leading "From~" or trailing newline. For convenience, \var{time_} may be -specified and will be formatted appropriately and appended to \var{from_}. If -\var{time_} is specified, it should be a \class{struct_time} instance, a tuple -suitable for passing to \method{time.strftime()}, or \code{True} (to use -\method{time.gmtime()}). -\end{methoddesc} - -\begin{methoddesc}{get_flags}{} -Return a string specifying the flags that are currently set. If the message -complies with the conventional format, the result is the concatenation in the -following order of zero or one occurrence of each of \character{R}, -\character{O}, \character{D}, \character{F}, and \character{A}. -\end{methoddesc} - -\begin{methoddesc}{set_flags}{flags} -Set the flags specified by \var{flags} and unset all others. Parameter -\var{flags} should be the concatenation in any order of zero or more -occurrences of each of \character{R}, \character{O}, \character{D}, -\character{F}, and \character{A}. -\end{methoddesc} - -\begin{methoddesc}{add_flag}{flag} -Set the flag(s) specified by \var{flag} without changing other flags. To add -more than one flag at a time, \var{flag} may be a string of more than one -character. -\end{methoddesc} - -\begin{methoddesc}{remove_flag}{flag} -Unset the flag(s) specified by \var{flag} without changing other flags. To -remove more than one flag at a time, \var{flag} maybe a string of more than one -character. -\end{methoddesc} - -When an \class{mboxMessage} instance is created based upon a -\class{MaildirMessage} instance, a "From~" line is generated based upon the -\class{MaildirMessage} instance's delivery date, and the following conversions -take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MaildirMessage} state} -\lineii{R flag}{S flag} -\lineii{O flag}{"cur" subdirectory} -\lineii{D flag}{T flag} -\lineii{F flag}{F flag} -\lineii{A flag}{R flag} -\end{tableii} - -When an \class{mboxMessage} instance is created based upon an \class{MHMessage} -instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MHMessage} state} -\lineii{R flag and O flag}{no "unseen" sequence} -\lineii{O flag}{"unseen" sequence} -\lineii{F flag}{"flagged" sequence} -\lineii{A flag}{"replied" sequence} -\end{tableii} - -When an \class{mboxMessage} instance is created based upon a -\class{BabylMessage} instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{BabylMessage} state} -\lineii{R flag and O flag}{no "unseen" label} -\lineii{O flag}{"unseen" label} -\lineii{D flag}{"deleted" label} -\lineii{A flag}{"answered" label} -\end{tableii} - -When a \class{Message} instance is created based upon an \class{MMDFMessage} -instance, the "From~" line is copied and all flags directly correspond: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MMDFMessage} state} -\lineii{R flag}{R flag} -\lineii{O flag}{O flag} -\lineii{D flag}{D flag} -\lineii{F flag}{F flag} -\lineii{A flag}{A flag} -\end{tableii} - -\subsubsection{\class{MHMessage}} -\label{mailbox-mhmessage} - -\begin{classdesc}{MHMessage}{\optional{message}} -A message with MH-specific behaviors. Parameter \var{message} has the same -meaning as with the \class{Message} constructor. -\end{classdesc} - -MH messages do not support marks or flags in the traditional sense, but they do -support sequences, which are logical groupings of arbitrary messages. Some mail -reading programs (although not the standard \program{mh} and \program{nmh}) use -sequences in much the same way flags are used with other formats, as follows: - -\begin{tableii}{l|l}{textrm}{Sequence}{Explanation} -\lineii{unseen}{Not read, but previously detected by MUA} -\lineii{replied}{Replied to} -\lineii{flagged}{Marked as important} -\end{tableii} - -\class{MHMessage} instances offer the following methods: - -\begin{methoddesc}{get_sequences}{} -Return a list of the names of sequences that include this message. -\end{methoddesc} - -\begin{methoddesc}{set_sequences}{sequences} -Set the list of sequences that include this message. -\end{methoddesc} - -\begin{methoddesc}{add_sequence}{sequence} -Add \var{sequence} to the list of sequences that include this message. -\end{methoddesc} - -\begin{methoddesc}{remove_sequence}{sequence} -Remove \var{sequence} from the list of sequences that include this message. -\end{methoddesc} - -When an \class{MHMessage} instance is created based upon a -\class{MaildirMessage} instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MaildirMessage} state} -\lineii{"unseen" sequence}{no S flag} -\lineii{"replied" sequence}{R flag} -\lineii{"flagged" sequence}{F flag} -\end{tableii} - -When an \class{MHMessage} instance is created based upon an \class{mboxMessage} -or \class{MMDFMessage} instance, the \mailheader{Status} and -\mailheader{X-Status} headers are omitted and the following conversions take -place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{mboxMessage} or \class{MMDFMessage} state} -\lineii{"unseen" sequence}{no R flag} -\lineii{"replied" sequence}{A flag} -\lineii{"flagged" sequence}{F flag} -\end{tableii} - -When an \class{MHMessage} instance is created based upon a \class{BabylMessage} -instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{BabylMessage} state} -\lineii{"unseen" sequence}{"unseen" label} -\lineii{"replied" sequence}{"answered" label} -\end{tableii} - -\subsubsection{\class{BabylMessage}} -\label{mailbox-babylmessage} - -\begin{classdesc}{BabylMessage}{\optional{message}} -A message with Babyl-specific behaviors. Parameter \var{message} has the same -meaning as with the \class{Message} constructor. -\end{classdesc} - -Certain message labels, called \dfn{attributes}, are defined by convention to -have special meanings. The attributes are as follows: - -\begin{tableii}{l|l}{textrm}{Label}{Explanation} -\lineii{unseen}{Not read, but previously detected by MUA} -\lineii{deleted}{Marked for subsequent deletion} -\lineii{filed}{Copied to another file or mailbox} -\lineii{answered}{Replied to} -\lineii{forwarded}{Forwarded} -\lineii{edited}{Modified by the user} -\lineii{resent}{Resent} -\end{tableii} - -By default, Rmail displays only -visible headers. The \class{BabylMessage} class, though, uses the original -headers because they are more complete. Visible headers may be accessed -explicitly if desired. - -\class{BabylMessage} instances offer the following methods: - -\begin{methoddesc}{get_labels}{} -Return a list of labels on the message. -\end{methoddesc} - -\begin{methoddesc}{set_labels}{labels} -Set the list of labels on the message to \var{labels}. -\end{methoddesc} - -\begin{methoddesc}{add_label}{label} -Add \var{label} to the list of labels on the message. -\end{methoddesc} - -\begin{methoddesc}{remove_label}{label} -Remove \var{label} from the list of labels on the message. -\end{methoddesc} - -\begin{methoddesc}{get_visible}{} -Return an \class{Message} instance whose headers are the message's visible -headers and whose body is empty. -\end{methoddesc} - -\begin{methoddesc}{set_visible}{visible} -Set the message's visible headers to be the same as the headers in -\var{message}. Parameter \var{visible} should be a \class{Message} instance, an -\class{email.Message.Message} instance, a string, or a file-like object (which -should be open in text mode). -\end{methoddesc} - -\begin{methoddesc}{update_visible}{} -When a \class{BabylMessage} instance's original headers are modified, the -visible headers are not automatically modified to correspond. This method -updates the visible headers as follows: each visible header with a -corresponding original header is set to the value of the original header, each -visible header without a corresponding original header is removed, and any of -\mailheader{Date}, \mailheader{From}, \mailheader{Reply-To}, \mailheader{To}, -\mailheader{CC}, and \mailheader{Subject} that are present in the original -headers but not the visible headers are added to the visible headers. -\end{methoddesc} - -When a \class{BabylMessage} instance is created based upon a -\class{MaildirMessage} instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MaildirMessage} state} -\lineii{"unseen" label}{no S flag} -\lineii{"deleted" label}{T flag} -\lineii{"answered" label}{R flag} -\lineii{"forwarded" label}{P flag} -\end{tableii} - -When a \class{BabylMessage} instance is created based upon an -\class{mboxMessage} or \class{MMDFMessage} instance, the \mailheader{Status} -and \mailheader{X-Status} headers are omitted and the following conversions -take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{mboxMessage} or \class{MMDFMessage} state} -\lineii{"unseen" label}{no R flag} -\lineii{"deleted" label}{D flag} -\lineii{"answered" label}{A flag} -\end{tableii} - -When a \class{BabylMessage} instance is created based upon an \class{MHMessage} -instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MHMessage} state} -\lineii{"unseen" label}{"unseen" sequence} -\lineii{"answered" label}{"replied" sequence} -\end{tableii} - -\subsubsection{\class{MMDFMessage}} -\label{mailbox-mmdfmessage} - -\begin{classdesc}{MMDFMessage}{\optional{message}} -A message with MMDF-specific behaviors. Parameter \var{message} has the same -meaning as with the \class{Message} constructor. -\end{classdesc} - -As with message in an mbox mailbox, MMDF messages are stored with the sender's -address and the delivery date in an initial line beginning with "From ". -Likewise, flags that indicate the state of the message are typically stored in -\mailheader{Status} and \mailheader{X-Status} headers. - -Conventional flags for MMDF messages are identical to those of mbox message and -are as follows: - -\begin{tableiii}{l|l|l}{textrm}{Flag}{Meaning}{Explanation} -\lineiii{R}{Read}{Read} -\lineiii{O}{Old}{Previously detected by MUA} -\lineiii{D}{Deleted}{Marked for subsequent deletion} -\lineiii{F}{Flagged}{Marked as important} -\lineiii{A}{Answered}{Replied to} -\end{tableiii} - -The "R" and "O" flags are stored in the \mailheader{Status} header, and the -"D", "F", and "A" flags are stored in the \mailheader{X-Status} header. The -flags and headers typically appear in the order mentioned. - -\class{MMDFMessage} instances offer the following methods, which are identical -to those offered by \class{mboxMessage}: - -\begin{methoddesc}{get_from}{} -Return a string representing the "From~" line that marks the start of the -message in an mbox mailbox. The leading "From~" and the trailing newline are -excluded. -\end{methoddesc} - -\begin{methoddesc}{set_from}{from_\optional{, time_=None}} -Set the "From~" line to \var{from_}, which should be specified without a -leading "From~" or trailing newline. For convenience, \var{time_} may be -specified and will be formatted appropriately and appended to \var{from_}. If -\var{time_} is specified, it should be a \class{struct_time} instance, a tuple -suitable for passing to \method{time.strftime()}, or \code{True} (to use -\method{time.gmtime()}). -\end{methoddesc} - -\begin{methoddesc}{get_flags}{} -Return a string specifying the flags that are currently set. If the message -complies with the conventional format, the result is the concatenation in the -following order of zero or one occurrence of each of \character{R}, -\character{O}, \character{D}, \character{F}, and \character{A}. -\end{methoddesc} - -\begin{methoddesc}{set_flags}{flags} -Set the flags specified by \var{flags} and unset all others. Parameter -\var{flags} should be the concatenation in any order of zero or more -occurrences of each of \character{R}, \character{O}, \character{D}, -\character{F}, and \character{A}. -\end{methoddesc} - -\begin{methoddesc}{add_flag}{flag} -Set the flag(s) specified by \var{flag} without changing other flags. To add -more than one flag at a time, \var{flag} may be a string of more than one -character. -\end{methoddesc} - -\begin{methoddesc}{remove_flag}{flag} -Unset the flag(s) specified by \var{flag} without changing other flags. To -remove more than one flag at a time, \var{flag} maybe a string of more than one -character. -\end{methoddesc} - -When an \class{MMDFMessage} instance is created based upon a -\class{MaildirMessage} instance, a "From~" line is generated based upon the -\class{MaildirMessage} instance's delivery date, and the following conversions -take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MaildirMessage} state} -\lineii{R flag}{S flag} -\lineii{O flag}{"cur" subdirectory} -\lineii{D flag}{T flag} -\lineii{F flag}{F flag} -\lineii{A flag}{R flag} -\end{tableii} - -When an \class{MMDFMessage} instance is created based upon an \class{MHMessage} -instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MHMessage} state} -\lineii{R flag and O flag}{no "unseen" sequence} -\lineii{O flag}{"unseen" sequence} -\lineii{F flag}{"flagged" sequence} -\lineii{A flag}{"replied" sequence} -\end{tableii} - -When an \class{MMDFMessage} instance is created based upon a -\class{BabylMessage} instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{BabylMessage} state} -\lineii{R flag and O flag}{no "unseen" label} -\lineii{O flag}{"unseen" label} -\lineii{D flag}{"deleted" label} -\lineii{A flag}{"answered" label} -\end{tableii} - -When an \class{MMDFMessage} instance is created based upon an -\class{mboxMessage} instance, the "From~" line is copied and all flags directly -correspond: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{mboxMessage} state} -\lineii{R flag}{R flag} -\lineii{O flag}{O flag} -\lineii{D flag}{D flag} -\lineii{F flag}{F flag} -\lineii{A flag}{A flag} -\end{tableii} - -\subsection{Exceptions} - -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} - -Older versions of the \module{mailbox} module do not support modification of -mailboxes, such as adding or removing message, and do not provide classes to -represent format-specific message properties. For backward compatibility, the -older mailbox classes are still available, but the newer classes should be used -in preference to them. - -Older mailbox objects support only iteration and provide a single public -method: - -\begin{methoddesc}[oldmailbox]{next}{} -Return the next message in the mailbox, created with the optional \var{factory} -argument passed into the mailbox object's constructor. By default 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 of -things like message boundaries if multiple mail messages are contained in a -single file, etc. If no more messages are available, this method returns -\code{None}. -\end{methoddesc} - -Most of the older mailbox classes have names that differ from the current -mailbox class names, except for \class{Maildir}. For this reason, the new -\class{Maildir} class defines a \method{next()} method and its constructor -differs slightly from those of the other new mailbox classes. - -The older mailbox classes whose names are not the same as their newer -counterparts are as follows: - -\begin{classdesc}{UnixMailbox}{fp\optional{, factory}} -Access to a classic \UNIX-style mailbox, where all messages are -contained in a single file and separated by \samp{From } -(a.k.a.\ \samp{From_}) lines. The file object \var{fp} points to the -mailbox file. The optional \var{factory} parameter is a callable that -should create new message objects. \var{factory} is called with one -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). - -\begin{notice} - For reasons of this module's internal implementation, you will - probably want to open the \var{fp} object in binary mode. This is - especially important on Windows. -\end{notice} - -For maximum portability, messages in a \UNIX-style mailbox are -separated by any line that begins exactly with the string \code{'From -'} (note the trailing space) if preceded by exactly two newlines. -Because of the wide-range of variations in practice, nothing else on -the \samp{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 -\samp{From_} line checking, using a regular expression that usually correctly -matched \samp{From_} delimiters. It considers delimiter line to be separated -by \samp{From \var{name} \var{time}} lines. For maximum portability, -use the \class{PortableUnixMailbox} class instead. This class is -identical to \class{UnixMailbox} except that individual messages are -separated by only \samp{From } lines. - -For more information, see -\citetitle[http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html]{Configuring -Netscape Mail on \UNIX: Why the Content-Length Format is Bad}. -\end{classdesc} - -\begin{classdesc}{PortableUnixMailbox}{fp\optional{, factory}} -A less-strict version of \class{UnixMailbox}, which considers only the -\samp{From } at the beginning of the line separating messages. The -``\var{name} \var{time}'' portion of the From line is ignored, to -protect against some variations that are observed in practice. This -works since lines in the message which begin with \code{'From '} are -quoted by mail handling software at delivery-time. -\end{classdesc} - -\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\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}{BabylMailbox}{fp\optional{, factory}} -Access a Babyl mailbox, which is similar to an MMDF mailbox. In -Babyl format, each message has two sets of headers, the -\emph{original} headers and the \emph{visible} headers. The original -headers appear before a line containing only \code{'*** EOOH ***'} -(End-Of-Original-Headers) and the visible headers appear after the -\code{EOOH} line. Babyl-compliant mail readers will show you only the -visible headers, and \class{BabylMailbox} objects will return messages -containing only the visible headers. You'll have to do your own -parsing of the mailbox file to get at the original headers. Mail -messages start with the EOOH line and end with a line containing only -\code{'\e{}037\e{}014'}. \var{factory} is as with the -\class{UnixMailbox} class. -\end{classdesc} - -If you wish to use the older mailbox classes with the \module{email} module -rather than the deprecated \module{rfc822} module, you can do so as follows: - -\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} - -Alternatively, 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} - -\subsection{Examples} -\label{mailbox-examples} - -A simple example of printing the subjects of all messages in a mailbox that -seem interesting: - -\begin{verbatim} -import mailbox -for message in mailbox.mbox('~/mbox'): - subject = message['subject'] # Could possibly be None. - if subject and 'python' in subject.lower(): - print subject -\end{verbatim} - -To copy all mail from a Babyl mailbox to an MH mailbox, converting all -of the format-specific information that can be converted: - -\begin{verbatim} -import mailbox -destination = mailbox.MH('~/Mail') -destination.lock() -for message in mailbox.Babyl('~/RMAIL'): - destination.add(MHMessage(message)) -destination.flush() -destination.unlock() -\end{verbatim} - -This example sorts mail from several mailing lists into different -mailboxes, being careful to avoid mail corruption due to concurrent -modification by other programs, mail loss due to interruption of the -program, or premature termination due to malformed messages in the -mailbox: - -\begin{verbatim} -import mailbox -import email.Errors - -list_names = ('python-list', 'python-dev', 'python-bugs') - -boxes = dict((name, mailbox.mbox('~/email/%s' % name)) for name in list_names) -inbox = mailbox.Maildir('~/Maildir', factory=None) - -for key in inbox.iterkeys(): - try: - message = inbox[key] - except email.Errors.MessageParseError: - continue # The message is malformed. Just leave it. - - for name in list_names: - list_id = message['list-id'] - if list_id and name in list_id: - # Get mailbox to use - box = boxes[name] - - # Write copy to disk before removing original. - # If there's a crash, you might duplicate a message, but - # that's better than losing a message completely. - box.lock() - box.add(message) - box.flush() - box.unlock() - - # Remove original message - inbox.lock() - inbox.discard(key) - inbox.flush() - inbox.unlock() - break # Found destination, so stop looking. - -for box in boxes.itervalues(): - box.close() -\end{verbatim} |