\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}, foraccessing 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 areMaildir, 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 andis not intended to be instantiated.  Instead, format-specificsubclasses should inherit from \class{Mailbox} and your codeshould instantiate a particular subclass. The \class{Mailbox} interface is dictionary-like, with small keyscorresponding 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 evenif the corresponding message is modified, such as by replacing it withanother message. Messages may be added to a \class{Mailbox} instance using the set-likemethod \method{add()} and removed using a \code{del} statement or theset-like methods \method{remove()} and \method{discard()}. \class{Mailbox} interface semantics differ from dictionary semantics in somenoteworthy ways. Each time a message is requested, a newrepresentation (typically a \class{Message} instance) is generatedbased upon the current state of the mailbox. Similarly, when a messageis added to a \class{Mailbox} instance, the provided messagerepresentation's contents are copied. In neither case is a referenceto the message representation kept by the \class{Mailbox} instance. The default \class{Mailbox} iterator iterates over message representations, notkeys as the default dictionary iterator does. Moreover, modification of amailbox during iteration is safe and well-defined. Messages added to themailbox after an iterator is created will not be seen by the iterator. Messagesremoved from the mailbox before the iterator yields them will be silentlyskipped, though using a key from an iterator may result in a\exception{KeyError} exception if the corresponding message is subsequentlyremoved. \begin{notice}[warning]Be very cautious when modifying mailboxes that might besimultaneously changed by some other process.  The safest mailboxformat to use for such tasks is Maildir; try to avoid usingsingle-file formats such as mbox for concurrent writing.  If you'remodifying a mailbox, you\emph{must} lock it by calling the \method{lock()} and\method{unlock()} methods \emph{before} reading any messages in the fileor making any changes by adding or deleting a message.  Failing tolock the mailbox runs the risk of losing messages or corrupting the entiremailbox.\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 toit. Parameter \var{message} may be a \class{Message} instance, an\class{email.Message.Message} instance, a string, or a file-like object (whichshould be open in text mode). If \var{message} is an instance of theappropriate format-specific \class{Message} subclass (e.g., if it's an\class{mboxMessage} instance and this is an \class{mbox} instance), itsformat-specific information is used. Otherwise, reasonable defaults forformat-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 themethod was called as \method{remove()} or \method{__delitem__()} but noexception is raised if the method was called as \method{discard()}. Thebehavior of \method{discard()} may be preferred if the underlying mailboxformat 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-likeobject (which should be open in text mode). If \var{message} is an instance ofthe appropriate format-specific \class{Message} subclass (e.g., if it's an\class{mboxMessage} instance and this is an \class{mbox} instance), itsformat-specific information is used. Otherwise, the format-specific informationof 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 alist 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 suchrepresentations if called as \method{values()}. The messages are represented asinstances of the appropriate format-specific \class{Message} subclass unless acustom message factory was specified when the \class{Mailbox} instance wasinitialized. \note{The behavior of \method{__iter__()} is unlike that ofdictionaries, which iterate over keys.}\end{methoddesc} \begin{methoddesc}{iteritems}{}\methodline{items}{}Return an iterator over (\var{key}, \var{message}) pairs, where \var{key} is akey 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 appropriateformat-specific \class{Message} subclass unless a custom message factory wasspecified 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 suchmessage exists, \var{default} is returned if the method was called as\method{get()} and a \exception{KeyError} exception is raised if the method wascalled as \method{__getitem__()}. The message is represented as an instance ofthe appropriate format-specific \class{Message} subclass unless a custommessage factory was specified when the \class{Mailbox} instance wasinitialized.\end{methoddesc} \begin{methoddesc}{get_message}{key}Return a representation of the message corresponding to \var{key} as aninstance of the appropriate format-specific \class{Message} subclass, or raisea \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}, orraise 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. Thefile-like object behaves as if open in binary mode. This file should be closedonce it is no longer needed. \note{Unlike other representations of messages, file-like representations arenot necessarily independent of the \class{Mailbox} instance that created themor of the underlying mailbox. More specific documentation is provided by eachsubclass.}\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 deletethe message. If no such message exists, return \var{default} if it was suppliedor else raise a \exception{KeyError} exception. The message is represented asan instance of the appropriate format-specific \class{Message} subclass unlessa custom message factory was specified when the \class{Mailbox} instance wasinitialized.\end{methoddesc} \begin{methoddesc}{popitem}{}Return an arbitrary (\var{key}, \var{message}) pair, where \var{key} is a keyand \var{message} is a message representation, and delete the correspondingmessage. If the mailbox is empty, raise a \exception{KeyError} exception. Themessage 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 aniterable of (\var{key}, \var{message}) pairs. Updates the mailbox so that, foreach 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 inthe mailbox or else a \exception{KeyError} exception will be raised, so ingeneral 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()} doesnothing, 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 knownot to modify it. An \exception{ExternalClashError} is raised if the lock isnot available. The particular locking mechanisms used depend upon the mailboxformat.  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 messagerepresentation (which behaves as if opened in binary mode) and returns a customrepresentation. If \var{factory} is \code{None}, \class{MaildirMessage} is usedas the default message representation. If \var{create} is \code{True}, themailbox 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 mailtransfer agent and now widely supported by other programs. Messages in aMaildir mailbox are stored in separate files within a common directorystructure. This design allows Maildir mailboxes to be accessed and modified bymultiple unrelated programs without data corruption, so file locking isunnecessary. Maildir mailboxes contain three subdirectories, namely: \file{tmp}, \file{new},and \file{cur}. Messages are created momentarily in the \file{tmp} subdirectoryand then moved to the \file{new} subdirectory to finalize delivery. A mail useragent may subsequently move the message to the \file{cur} subdirectory andstore information about the state of the message in a special "info" sectionappended to its file name. Folders of the style introduced by the Courier mail transfer agent are alsosupported. Any subdirectory of the main mailbox is considered a folder if\character{.} is the first character in its name. Folder names are representedby \class{Maildir} without the leading \character{.}. Each folder is itself aMaildir mailbox but should not contain other folders. Instead, a logicalnesting is indicated using \character{.} to delimit levels, e.g.,"Archived.2005.07". \begin{notice}The Maildir specification requires the use of a colon (\character{:}) incertain message file names. However, some operating systems do not permit thischaracter in file names, If you wish to use a Maildir-like format on such anoperating system, you should specify another character to use instead. Theexclamation point (\character{!}) is a popular choice. For example:\begin{verbatim}import mailboxmailbox.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} inaddition 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 thefolder 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 anymessages, a \exception{NotEmptyError} exception will be raised and the folderwill not be deleted.\end{methoddesc} \begin{methoddesc}{clean}{}Delete temporary files from the mailbox that have not been accessed in thelast 36 hours. The Maildir specification says that mail-reading programsshould do this occasionally.\end{methoddesc} Some \class{Mailbox} methods implemented by \class{Maildir} deserve specialremarks: \begin{methoddesc}{add}{message}\methodline[Maildir]{__setitem__}{key, message}\methodline[Maildir]{update}{arg}\warning{These methods generate unique file names based upon the currentprocess ID. When using multiple threads, undetected name clashes may occur andcause corruption of the mailbox unless threads are coordinated to avoid usingthese methods to manipulate the same mailbox simultaneously.}\end{methoddesc} \begin{methoddesc}{flush}{}All changes to Maildir mailboxes are immediately applied, so this method doesnothing.\end{methoddesc} \begin{methoddesc}{lock}{}\methodline{unlock}{}Maildir mailboxes do not support (or require) locking, so these methods donothing. \end{methoddesc} \begin{methoddesc}{close}{}\class{Maildir} instances do not keep any open files and the underlyingmailboxes 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 removethe 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 messagerepresentation (which behaves as if opened in binary mode) and returns a customrepresentation. If \var{factory} is \code{None}, \class{mboxMessage} is used asthe default message representation. If \var{create} is \code{True}, the mailboxis created if it does not exist.\end{classdesc} The mbox format is the classic format for storing mail on \UNIX{} systems. Allmessages in an mbox mailbox are stored in a single file with the beginning ofeach message indicated by a line whose first five characters are "From~". Several variations of the mbox format exist to address perceived shortcomingsin the original. In the interest of compatibility, \class{mbox} implements theoriginal format, which is sometimes referred to as \dfn{mboxo}. This means thatthe \mailheader{Content-Length} header, if present, is ignored and that anyoccurrences of "From~" at the beginning of a line in a message body aretransformed 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 specialremarks: \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 messagerepresentation (which behaves as if opened in binary mode) and returns a customrepresentation. If \var{factory} is \code{None}, \class{MHMessage} is used asthe default message representation. If \var{create} is \code{True}, the mailboxis created if it does not exist.\end{classdesc} MH is a directory-based mailbox format invented for the MH Message HandlingSystem, a mail user agent. Each message in an MH mailbox resides in its ownfile. An MH mailbox may contain other MH mailboxes (called \dfn{folders}) inaddition to messages. Folders may be nested indefinitely. MH mailboxes alsosupport \dfn{sequences}, which are named lists used to logically group messageswithout 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 toemulate all of \program{mh}'s behaviors. In particular, it does not modify andis not affected by the \file{context} or \file{.mh_profile} files that are usedby \program{mh} to store its state and configuration. \class{MH} instances have all of the methods of \class{Mailbox} in addition tothe 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 thefolder does not exist.\end{methoddesc} \begin{methoddesc}{add_folder}{folder}Create a folder whose name is \var{folder} and return an \class{MH} instancerepresenting it.\end{methoddesc} \begin{methoddesc}{remove_folder}{folder}Delete the folder whose name is \var{folder}. If the folder contains anymessages, a \exception{NotEmptyError} exception will be raised and the folderwill not be deleted.\end{methoddesc} \begin{methoddesc}{get_sequences}{}Return a dictionary of sequence names mapped to key lists. If there are nosequences, 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}, adictionary 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-issuedkeys 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 amessage 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

Lines 1–500 of 1444. Load more