Index: Doc/lib/libmailbox.tex =================================================================== --- Doc/lib/libmailbox.tex (revision 53260) +++ Doc/lib/libmailbox.tex (working copy) @@ -51,6 +51,16 @@ \exception{KeyError} exception if the corresponding message is subsequently removed. +Be very cautious when modifying mailboxes that might also be modified +by some other process such as a mail transport agent or a different +Python process. The safest mailbox format to use for such tasks is +Maildir; avoid using single-file formats such as mbox. If you're +modifying a mailbox, no matter what the format, you must lock it by +calling the \method{lock()} and \method{unlock()} methods before +making any changes. If you don't do this, you run the risk of losing +data because one process makes changes to the mailbox that the other +process is unaware of. + \class{Mailbox} itself is intended to define an interface and to be inherited from by format-specific subclasses but is not intended to be instantiated. Instead, you should instantiate a subclass. @@ -202,15 +212,16 @@ \begin{methoddesc}{flush}{} Write any pending changes to the filesystem. For some \class{Mailbox} -subclasses, changes are always written immediately and this method does -nothing. +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. +format. You should \emph{always} lock the mailbox before making any +modifications to its contents. \end{methoddesc} \begin{methoddesc}{unlock}{} @@ -1373,8 +1384,11 @@ \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} An example of sorting mail from numerous mailing lists, being careful to avoid @@ -1397,12 +1411,19 @@ list_id = message['list-id'] if list_id and name in list_id: box = boxes[name] + # Write copy to disk before removing original. box.lock() box.add(message) - box.flush() # Write copy to disk before removing original. + 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}