blob: 0a1f792a34aec15407f3cb9b90b2aa0fa207ef7c [file] [log] [blame]
Fred Drake295da241998-08-10 19:42:37 +00001\section{\module{mailbox} ---
Andrew M. Kuchling1da4a942006-04-22 02:32:43 +00002 Manipulate mailboxes in various formats}
Fred Drake199b79c1999-02-20 05:04:59 +00003
Andrew M. Kuchling1da4a942006-04-22 02:32:43 +00004\declaremodule{}{mailbox}
5\moduleauthor{Gregory K.~Johnson}{gkj@gregorykjohnson.com}
6\sectionauthor{Gregory K.~Johnson}{gkj@gregorykjohnson.com}
7\modulesynopsis{Manipulate mailboxes in various formats}
Fred Drakeb91e9341998-07-23 17:59:49 +00008
Guido van Rossum39a23cc1997-06-02 21:04:41 +00009
Andrew M. Kuchling1da4a942006-04-22 02:32:43 +000010This module defines two classes, \class{Mailbox} and \class{Message}, for
11accessing and manipulating on-disk mailboxes and the messages they contain.
12\class{Mailbox} offers a dictionary-like mapping from keys to messages.
13\class{Message} extends the \module{email.Message} module's \class{Message}
14class with format-specific state and behavior. Supported mailbox formats are
15Maildir, mbox, MH, Babyl, and MMDF.
16
17\begin{seealso}
18 \seemodule{email}{Represent and manipulate messages.}
19\end{seealso}
20
21\subsection{\class{Mailbox} objects}
22\label{mailbox-objects}
23
24\begin{classdesc*}{Mailbox}
25A mailbox, which may be inspected and modified.
26\end{classdesc*}
27
28The \class{Mailbox} interface is dictionary-like, with small keys
29corresponding to messages. Keys are issued by the \class{Mailbox} instance
30with which they will be used and are only meaningful to that \class{Mailbox}
31instance. A key continues to identify a message even if the corresponding
32message is modified, such as by replacing it with another message. Messages may
33be added to a \class{Mailbox} instance using the set-like method
34\method{add()} and removed using a \code{del} statement or the set-like methods
35\method{remove()} and \method{discard()}.
36
37\class{Mailbox} interface semantics differ from dictionary semantics in some
38noteworthy ways. Each time a message is requested, a new representation
39(typically a \class{Message} instance) is generated, based upon the current
40state of the mailbox. Similarly, when a message is added to a \class{Mailbox}
41instance, the provided message representation's contents are copied. In neither
42case is a reference to the message representation kept by the \class{Mailbox}
43instance.
44
45The default \class{Mailbox} iterator iterates over message representations, not
46keys as the default dictionary iterator does. Moreover, modification of a
47mailbox during iteration is safe and well-defined. Messages added to the
48mailbox after an iterator is created will not be seen by the iterator. Messages
49removed from the mailbox before the iterator yields them will be silently
50skipped, though using a key from an iterator may result in a
51\exception{KeyError} exception if the corresponding message is subsequently
52removed.
53
54\class{Mailbox} itself is intended to define an interface and to be inherited
55from by format-specific subclasses but is not intended to be instantiated.
56Instead, you should instantiate a subclass.
57
58\class{Mailbox} instances have the following methods:
59
60\begin{methoddesc}{add}{message}
61Add \var{message} to the mailbox and return the key that has been assigned to
62it.
63
64Parameter \var{message} may be a \class{Message} instance, an
65\class{email.Message.Message} instance, a string, or a file-like object (which
66should be open in text mode). If \var{message} is an instance of the
67appropriate format-specific \class{Message} subclass (e.g., if it's an
68\class{mboxMessage} instance and this is an \class{mbox} instance), its
69format-specific information is used. Otherwise, reasonable defaults for
70format-specific information are used.
71\end{methoddesc}
72
73\begin{methoddesc}{remove}{key}
74\methodline{__delitem__}{key}
75\methodline{discard}{key}
76Delete the message corresponding to \var{key} from the mailbox.
77
78If no such message exists, a \exception{KeyError} exception is raised if the
79method was called as \method{remove()} or \method{__delitem__()} but no
80exception is raised if the method was called as \method{discard()}. The
81behavior of \method{discard()} may be preferred if the underlying mailbox
82format supports concurrent modification by other processes.
83\end{methoddesc}
84
85\begin{methoddesc}{__setitem__}{key, message}
86Replace the message corresponding to \var{key} with \var{message}. Raise a
87\exception{KeyError} exception if no message already corresponds to \var{key}.
88
89As with \method{add()}, parameter \var{message} may be a \class{Message}
90instance, an \class{email.Message.Message} instance, a string, or a file-like
91object (which should be open in text mode). If \var{message} is an instance of
92the appropriate format-specific \class{Message} subclass (e.g., if it's an
93\class{mboxMessage} instance and this is an \class{mbox} instance), its
94format-specific information is used. Otherwise, the format-specific information
95of the message that currently corresponds to \var{key} is left unchanged.
96\end{methoddesc}
97
98\begin{methoddesc}{iterkeys}{}
99\methodline{keys}{}
100Return an iterator over all keys if called as \method{iterkeys()} or return a
101list of keys if called as \method{keys()}.
102\end{methoddesc}
103
104\begin{methoddesc}{itervalues}{}
105\methodline{__iter__}{}
106\methodline{values}{}
107Return an iterator over representations of all messages if called as
108\method{itervalues()} or \method{__iter__()} or return a list of such
109representations if called as \method{values()}. The messages are represented as
110instances of the appropriate format-specific \class{Message} subclass unless a
111custom message factory was specified when the \class{Mailbox} instance was
112initialized. \note{The behavior of \method{__iter__()} is unlike that of
113dictionaries, which iterate over keys.}
114\end{methoddesc}
115
116\begin{methoddesc}{iteritems}{}
117\methodline{items}{}
118Return an iterator over (\var{key}, \var{message}) pairs, where \var{key} is a
119key and \var{message} is a message representation, if called as
120\method{iteritems()} or return a list of such pairs if called as
121\method{items()}. The messages are represented as instances of the appropriate
122format-specific \class{Message} subclass unless a custom message factory was
123specified when the \class{Mailbox} instance was initialized.
124\end{methoddesc}
125
126\begin{methoddesc}{get}{key\optional{, default=None}}
127\methodline{__getitem__}{key}
128Return a representation of the message corresponding to \var{key}. If no such
129message exists, \var{default} is returned if the method was called as
130\method{get()} and a \exception{KeyError} exception is raised if the method was
131called as \method{__getitem__()}. The message is represented as an instance of
132the appropriate format-specific \class{Message} subclass unless a custom
133message factory was specified when the \class{Mailbox} instance was
134initialized.
135\end{methoddesc}
136
137\begin{methoddesc}{get_message}{key}
138Return a representation of the message corresponding to \var{key} as an
139instance of the appropriate format-specific \class{Message} subclass, or raise
140a \exception{KeyError} exception if no such message exists.
141\end{methoddesc}
142
143\begin{methoddesc}{get_string}{key}
144Return a string representation of the message corresponding to \var{key}, or
145raise a \exception{KeyError} exception if no such message exists.
146\end{methoddesc}
147
148\begin{methoddesc}{get_file}{key}
149Return a file-like representation of the message corresponding to \var{key},
150or raise a \exception{KeyError} exception if no such message exists. The
151file-like object behaves as if open in binary mode. This file should be closed
152once it is no longer needed.
153
154\note{Unlike other representations of messages, file-like representations are
155not necessarily independent of the \class{Mailbox} instance that created them
156or of the underlying mailbox. More specific documentation is provided by each
157subclass.}
158\end{methoddesc}
159
160\begin{methoddesc}{has_key}{key}
161\methodline{__contains__}{key}
162Return \code{True} if \var{key} corresponds to a message, \code{False}
163otherwise.
164\end{methoddesc}
165
166\begin{methoddesc}{__len__}{}
167Return a count of messages in the mailbox.
168\end{methoddesc}
169
170\begin{methoddesc}{clear}{}
171Delete all messages from the mailbox.
172\end{methoddesc}
173
174\begin{methoddesc}{pop}{key\optional{, default}}
175Return a representation of the message corresponding to \var{key} and delete
176the message. If no such message exists, return \var{default} if it was supplied
177or else raise a \exception{KeyError} exception. The message is represented as
178an instance of the appropriate format-specific \class{Message} subclass unless
179a custom message factory was specified when the \class{Mailbox} instance was
180initialized.
181\end{methoddesc}
182
183\begin{methoddesc}{popitem}{}
184Return an arbitrary (\var{key}, \var{message}) pair, where \var{key} is a key
185and \var{message} is a message representation, and delete the corresponding
186message. If the mailbox is empty, raise a \exception{KeyError} exception. The
187message is represented as an instance of the appropriate format-specific
188\class{Message} subclass unless a custom message factory was specified when the
189\class{Mailbox} instance was initialized.
190\end{methoddesc}
191
192\begin{methoddesc}{update}{arg}
193Parameter \var{arg} should be a \var{key}-to-\var{message} mapping or an
194iterable of (\var{key}, \var{message}) pairs. Updates the mailbox so that, for
195each given \var{key} and \var{message}, the message corresponding to \var{key}
196is set to \var{message} as if by using \method{__setitem__()}. As with
197\method{__setitem__()}, each \var{key} must already correspond to a message in
198the mailbox or else a \exception{KeyError} exception will be raised, so in
199general it is incorrect for \var{arg} to be a \class{Mailbox} instance.
200\note{Unlike with dictionaries, keyword arguments are not supported.}
201\end{methoddesc}
202
203\begin{methoddesc}{flush}{}
204Write any pending changes to the filesystem. For some \class{Mailbox}
205subclasses, changes are always written immediately and this method does
206nothing.
207\end{methoddesc}
208
209\begin{methoddesc}{lock}{}
210Acquire an exclusive advisory lock on the mailbox so that other processes know
211not to modify it. An \exception{ExternalClashError} is raised if the lock is
212not available. The particular locking mechanisms used depend upon the mailbox
213format.
214\end{methoddesc}
215
216\begin{methoddesc}{unlock}{}
217Release the lock on the mailbox, if any.
218\end{methoddesc}
219
220\begin{methoddesc}{close}{}
221Flush the mailbox, unlock it if necessary, and close any open files. For some
222\class{Mailbox} subclasses, this method does nothing.
223\end{methoddesc}
224
225
226\subsubsection{\class{Maildir}}
227\label{mailbox-maildir}
228
229\begin{classdesc}{Maildir}{dirname\optional{, factory=rfc822.Message\optional{,
230create=True}}}
231A subclass of \class{Mailbox} for mailboxes in Maildir format. Parameter
232\var{factory} is a callable object that accepts a file-like message
Andrew M. Kuchling09019652006-05-07 17:14:53 +0000233representation (which behaves as if opened in binary mode) and returns a custom
Andrew M. Kuchling1da4a942006-04-22 02:32:43 +0000234representation. If \var{factory} is \code{None}, \class{MaildirMessage} is used
235as the default message representation. If \var{create} is \code{True}, the
236mailbox is created if it does not exist.
237
238It is for historical reasons that \var{factory} defaults to
239\class{rfc822.Message} and that \var{dirname} is named as such rather than
240\var{path}. For a \class{Maildir} instance that behaves like instances of other
241\class{Mailbox} subclasses, set \var{factory} to \code{None}.
242\end{classdesc}
243
244Maildir is a directory-based mailbox format invented for the qmail mail
245transfer agent and now widely supported by other programs. Messages in a
246Maildir mailbox are stored in separate files within a common directory
247structure. This design allows Maildir mailboxes to be accessed and modified by
248multiple unrelated programs without data corruption, so file locking is
249unnecessary.
250
251Maildir mailboxes contain three subdirectories, namely: \file{tmp}, \file{new},
252and \file{cur}. Messages are created momentarily in the \file{tmp} subdirectory
253and then moved to the \file{new} subdirectory to finalize delivery. A mail user
254agent may subsequently move the message to the \file{cur} subdirectory and
255store information about the state of the message in a special "info" section
256appended to its file name.
257
258Folders of the style introduced by the Courier mail transfer agent are also
259supported. Any subdirectory of the main mailbox is considered a folder if
260\character{.} is the first character in its name. Folder names are represented
261by \class{Maildir} without the leading \character{.}. Each folder is itself a
262Maildir mailbox but should not contain other folders. Instead, a logical
263nesting is indicated using \character{.} to delimit levels, e.g.,
264"Archived.2005.07".
265
266\begin{notice}
267The Maildir specification requires the use of a colon (\character{:}) in
268certain message file names. However, some operating systems do not permit this
269character in file names, If you wish to use a Maildir-like format on such an
270operating system, you should specify another character to use instead. The
271exclamation point (\character{!}) is a popular choice. For example:
272\begin{verbatim}
273import mailbox
274mailbox.Maildir.colon = '!'
275\end{verbatim}
276The \member{colon} attribute may also be set on a per-instance basis.
277\end{notice}
278
279\class{Maildir} instances have all of the methods of \class{Mailbox} in
280addition to the following:
281
282\begin{methoddesc}{list_folders}{}
283Return a list of the names of all folders.
284\end{methoddesc}
285
286\begin{methoddesc}{get_folder}{folder}
287Return a \class{Maildir} instance representing the folder whose name is
288\var{folder}. A \exception{NoSuchMailboxError} exception is raised if the
289folder does not exist.
290\end{methoddesc}
291
292\begin{methoddesc}{add_folder}{folder}
293Create a folder whose name is \var{folder} and return a \class{Maildir}
294instance representing it.
295\end{methoddesc}
296
297\begin{methoddesc}{remove_folder}{folder}
298Delete the folder whose name is \var{folder}. If the folder contains any
299messages, a \exception{NotEmptyError} exception will be raised and the folder
300will not be deleted.
301\end{methoddesc}
302
303\begin{methoddesc}{clean}{}
304Delete temporary files from the mailbox that have not been accessed in the
305last 36 hours. The Maildir specification says that mail-reading programs
306should do this occasionally.
307\end{methoddesc}
308
309Some \class{Mailbox} methods implemented by \class{Maildir} deserve special
310remarks:
311
312\begin{methoddesc}{add}{message}
313\methodline[Maildir]{__setitem__}{key, message}
314\methodline[Maildir]{update}{arg}
315\warning{These methods generate unique file names based upon the current
316process ID. When using multiple threads, undetected name clashes may occur and
317cause corruption of the mailbox unless threads are coordinated to avoid using
318these methods to manipulate the same mailbox simultaneously.}
319\end{methoddesc}
320
321\begin{methoddesc}{flush}{}
322All changes to Maildir mailboxes are immediately applied, so this method does
323nothing.
324\end{methoddesc}
325
326\begin{methoddesc}{lock}{}
327\methodline{unlock}{}
328Maildir mailboxes do not support (or require) locking, so these methods do
329nothing.
330\end{methoddesc}
331
332\begin{methoddesc}{close}{}
333\class{Maildir} instances do not keep any open files and the underlying
334mailboxes do not support locking, so this method does nothing.
335\end{methoddesc}
336
337\begin{methoddesc}{get_file}{key}
338Depending upon the host platform, it may not be possible to modify or remove
339the underlying message while the returned file remains open.
340\end{methoddesc}
341
342\begin{seealso}
343 \seelink{http://www.qmail.org/man/man5/maildir.html}{maildir man page from
344 qmail}{The original specification of the format.}
345 \seelink{http://cr.yp.to/proto/maildir.html}{Using maildir format}{Notes
346 on Maildir by its inventor. Includes an updated name-creation scheme and
347 details on "info" semantics.}
348 \seelink{http://www.courier-mta.org/?maildir.html}{maildir man page from
349 Courier}{Another specification of the format. Describes a common extension
350 for supporting folders.}
351\end{seealso}
352
353\subsubsection{\class{mbox}}
354\label{mailbox-mbox}
355
356\begin{classdesc}{mbox}{path\optional{, factory=None\optional{, create=True}}}
357A subclass of \class{Mailbox} for mailboxes in mbox format. Parameter
358\var{factory} is a callable object that accepts a file-like message
Andrew M. Kuchling09019652006-05-07 17:14:53 +0000359representation (which behaves as if opened in binary mode) and returns a custom
Andrew M. Kuchling1da4a942006-04-22 02:32:43 +0000360representation. If \var{factory} is \code{None}, \class{mboxMessage} is used as
361the default message representation. If \var{create} is \code{True}, the mailbox
362is created if it does not exist.
363\end{classdesc}
364
365The mbox format is the classic format for storing mail on \UNIX{} systems. All
366messages in an mbox mailbox are stored in a single file with the beginning of
367each message indicated by a line whose first five characters are "From~".
368
369Several variations of the mbox format exist to address perceived shortcomings
370in the original. In the interest of compatibility, \class{mbox} implements the
371original format, which is sometimes referred to as \dfn{mboxo}. This means that
372the \mailheader{Content-Length} header, if present, is ignored and that any
373occurrences of "From~" at the beginning of a line in a message body are
374transformed to ">From~" when storing the message, although occurences of
375">From~" are not transformed to "From~" when reading the message.
376
377Some \class{Mailbox} methods implemented by \class{mbox} deserve special
378remarks:
379
380\begin{methoddesc}{get_file}{key}
381Using the file after calling \method{flush()} or \method{close()} on the
382\class{mbox} instance may yield unpredictable results or raise an exception.
383\end{methoddesc}
384
385\begin{methoddesc}{lock}{}
386\methodline{unlock}{}
387Three locking mechanisms are used---dot locking and, if available, the
388\cfunction{flock()} and \cfunction{lockf()} system calls.
389\end{methoddesc}
390
391\begin{seealso}
392 \seelink{http://www.qmail.org/man/man5/mbox.html}{mbox man page from
393 qmail}{A specification of the format and its variations.}
394 \seelink{http://www.tin.org/bin/man.cgi?section=5\&topic=mbox}{mbox man
395 page from tin}{Another specification of the format, with details on
396 locking.}
397 \seelink{http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html}
398 {Configuring Netscape Mail on \UNIX{}: Why The Content-Length Format is
399 Bad}{An argument for using the original mbox format rather than a
400 variation.}
401 \seelink{http://homepages.tesco.net./\tilde{}J.deBoynePollard/FGA/mail-mbox-formats.html}
402 {"mbox" is a family of several mutually incompatible mailbox formats}{A
403 history of mbox variations.}
404\end{seealso}
405
406\subsubsection{\class{MH}}
407\label{mailbox-mh}
408
409\begin{classdesc}{MH}{path\optional{, factory=None\optional{, create=True}}}
410A subclass of \class{Mailbox} for mailboxes in MH format. Parameter
411\var{factory} is a callable object that accepts a file-like message
Andrew M. Kuchling09019652006-05-07 17:14:53 +0000412representation (which behaves as if opened in binary mode) and returns a custom
Andrew M. Kuchling1da4a942006-04-22 02:32:43 +0000413representation. If \var{factory} is \code{None}, \class{MHMessage} is used as
414the default message representation. If \var{create} is \code{True}, the mailbox
415is created if it does not exist.
416\end{classdesc}
417
418MH is a directory-based mailbox format invented for the MH Message Handling
419System, a mail user agent. Each message in an MH mailbox resides in its own
420file. An MH mailbox may contain other MH mailboxes (called \dfn{folders}) in
421addition to messages. Folders may be nested indefinitely. MH mailboxes also
422support \dfn{sequences}, which are named lists used to logically group messages
423without moving them to sub-folders. Sequences are defined in a file called
424\file{.mh_sequences} in each folder.
425
426The \class{MH} class manipulates MH mailboxes, but it does not attempt to
427emulate all of \program{mh}'s behaviors. In particular, it does not modify and
428is not affected by the \file{context} or \file{.mh_profile} files that are used
429by \program{mh} to store its state and configuration.
430
431\class{MH} instances have all of the methods of \class{Mailbox} in addition to
432the following:
433
434\begin{methoddesc}{list_folders}{}
435Return a list of the names of all folders.
436\end{methoddesc}
437
438\begin{methoddesc}{get_folder}{folder}
439Return an \class{MH} instance representing the folder whose name is
440\var{folder}. A \exception{NoSuchMailboxError} exception is raised if the
441folder does not exist.
442\end{methoddesc}
443
444\begin{methoddesc}{add_folder}{folder}
445Create a folder whose name is \var{folder} and return an \class{MH} instance
446representing it.
447\end{methoddesc}
448
449\begin{methoddesc}{remove_folder}{folder}
450Delete the folder whose name is \var{folder}. If the folder contains any
451messages, a \exception{NotEmptyError} exception will be raised and the folder
452will not be deleted.
453\end{methoddesc}
454
455\begin{methoddesc}{get_sequences}{}
456Return a dictionary of sequence names mapped to key lists. If there are no
457sequences, the empty dictionary is returned.
458\end{methoddesc}
459
460\begin{methoddesc}{set_sequences}{sequences}
461Re-define the sequences that exist in the mailbox based upon \var{sequences}, a
462dictionary of names mapped to key lists, like returned by
463\method{get_sequences()}.
464\end{methoddesc}
465
466\begin{methoddesc}{pack}{}
467Rename messages in the mailbox as necessary to eliminate gaps in numbering.
468Entries in the sequences list are updated correspondingly. \note{Already-issued
469keys are invalidated by this operation and should not be subsequently used.}
470\end{methoddesc}
471
472Some \class{Mailbox} methods implemented by \class{MH} deserve special remarks:
473
474\begin{methoddesc}{remove}{key}
475\methodline{__delitem__}{key}
476\methodline{discard}{key}
477These methods immediately delete the message. The MH convention of marking a
478message for deletion by prepending a comma to its name is not used.
479\end{methoddesc}
480
481\begin{methoddesc}{lock}{}
482\methodline{unlock}{}
483Three locking mechanisms are used---dot locking and, if available, the
484\cfunction{flock()} and \cfunction{lockf()} system calls. For MH mailboxes,
485locking the mailbox means locking the \file{.mh_sequences} file and, only for
486the duration of any operations that affect them, locking individual message
487files.
488\end{methoddesc}
489
490\begin{methoddesc}{get_file}{key}
491Depending upon the host platform, it may not be possible to remove the
492underlying message while the returned file remains open.
493\end{methoddesc}
494
495\begin{methoddesc}{flush}{}
496All changes to MH mailboxes are immediately applied, so this method does
497nothing.
498\end{methoddesc}
499
500\begin{methoddesc}{close}{}
501\class{MH} instances do not keep any open files, so this method is equivelant
502to \method{unlock()}.
503\end{methoddesc}
504
505\begin{seealso}
506\seelink{http://www.nongnu.org/nmh/}{nmh - Message Handling System}{Home page
507of \program{nmh}, an updated version of the original \program{mh}.}
508\seelink{http://www.ics.uci.edu/\tilde{}mh/book/}{MH \& nmh: Email for Users \&
509Programmers}{A GPL-licensed book on \program{mh} and \program{nmh}, with some
510information on the mailbox format.}
511\end{seealso}
512
513\subsubsection{\class{Babyl}}
514\label{mailbox-babyl}
515
516\begin{classdesc}{Babyl}{path\optional{, factory=None\optional{, create=True}}}
517A subclass of \class{Mailbox} for mailboxes in Babyl format. Parameter
518\var{factory} is a callable object that accepts a file-like message
Andrew M. Kuchling09019652006-05-07 17:14:53 +0000519representation (which behaves as if opened in binary mode) and returns a custom
Andrew M. Kuchling1da4a942006-04-22 02:32:43 +0000520representation. If \var{factory} is \code{None}, \class{BabylMessage} is used
521as the default message representation. If \var{create} is \code{True}, the
522mailbox is created if it does not exist.
523\end{classdesc}
524
525Babyl is a single-file mailbox format used by the Rmail mail user agent
526included with Emacs. The beginning of a message is indicated by a line
527containing the two characters Control-Underscore
528(\character{\textbackslash037}) and Control-L (\character{\textbackslash014}).
529The end of a message is indicated by the start of the next message or, in the
530case of the last message, a line containing a Control-Underscore
531(\character{\textbackslash037}) character.
532
533Messages in a Babyl mailbox have two sets of headers, original headers and
534so-called visible headers. Visible headers are typically a subset of the
535original headers that have been reformatted or abridged to be more attractive.
536Each message in a Babyl mailbox also has an accompanying list of \dfn{labels},
537or short strings that record extra information about the message, and a list of
538all user-defined labels found in the mailbox is kept in the Babyl options
539section.
540
541\class{Babyl} instances have all of the methods of \class{Mailbox} in addition
542to the following:
543
544\begin{methoddesc}{get_labels}{}
545Return a list of the names of all user-defined labels used in the mailbox.
546\note{The actual messages are inspected to determine which labels exist in the
547mailbox rather than consulting the list of labels in the Babyl options section,
548but the Babyl section is updated whenever the mailbox is modified.}
549\end{methoddesc}
550
551Some \class{Mailbox} methods implemented by \class{Babyl} deserve special
552remarks:
553
554\begin{methoddesc}{get_file}{key}
555In Babyl mailboxes, the headers of a message are not stored contiguously with
556the body of the message. To generate a file-like representation, the headers
557and body are copied together into a \class{StringIO} instance (from the
558\module{StringIO} module), which has an API identical to that of a file. As a
559result, the file-like object is truly independent of the underlying mailbox but
560does not save memory compared to a string representation.
561\end{methoddesc}
562
563\begin{methoddesc}{lock}{}
564\methodline{unlock}{}
565Three locking mechanisms are used---dot locking and, if available, the
566\cfunction{flock()} and \cfunction{lockf()} system calls.
567\end{methoddesc}
568
569\begin{seealso}
570\seelink{http://quimby.gnus.org/notes/BABYL}{Format of Version 5 Babyl Files}{A
571specification of the Babyl format.}
572\seelink{http://www.gnu.org/software/emacs/manual/html_node/Rmail.html}{Reading
573Mail with Rmail}{The Rmail manual, with some information on Babyl semantics.}
574\end{seealso}
575
576\subsubsection{\class{MMDF}}
577\label{mailbox-mmdf}
578
579\begin{classdesc}{MMDF}{path\optional{, factory=None\optional{, create=True}}}
580A subclass of \class{Mailbox} for mailboxes in MMDF format. Parameter
581\var{factory} is a callable object that accepts a file-like message
Andrew M. Kuchling09019652006-05-07 17:14:53 +0000582representation (which behaves as if opened in binary mode) and returns a custom
Andrew M. Kuchling1da4a942006-04-22 02:32:43 +0000583representation. If \var{factory} is \code{None}, \class{MMDFMessage} is used as
584the default message representation. If \var{create} is \code{True}, the mailbox
585is created if it does not exist.
586\end{classdesc}
587
588MMDF is a single-file mailbox format invented for the Multichannel Memorandum
589Distribution Facility, a mail transfer agent. Each message is in the same form
590as an mbox message but is bracketed before and after by lines containing four
591Control-A (\character{\textbackslash001}) characters. As with the mbox format,
592the beginning of each message is indicated by a line whose first five
593characters are "From~", but additional occurrences of "From~" are not
594transformed to ">From~" when storing messages because the extra message
595separator lines prevent mistaking such occurrences for the starts of subsequent
596messages.
597
598Some \class{Mailbox} methods implemented by \class{MMDF} deserve special
599remarks:
600
601\begin{methoddesc}{get_file}{key}
602Using the file after calling \method{flush()} or \method{close()} on the
603\class{MMDF} instance may yield unpredictable results or raise an exception.
604\end{methoddesc}
605
606\begin{methoddesc}{lock}{}
607\methodline{unlock}{}
608Three locking mechanisms are used---dot locking and, if available, the
609\cfunction{flock()} and \cfunction{lockf()} system calls.
610\end{methoddesc}
611
612\begin{seealso}
613\seelink{http://www.tin.org/bin/man.cgi?section=5\&topic=mmdf}{mmdf man page
614from tin}{A specification of MMDF format from the documentation of tin, a
615newsreader.}
616\seelink{http://en.wikipedia.org/wiki/MMDF}{MMDF}{A Wikipedia article
617describing the Multichannel Memorandum Distribution Facility.}
618\end{seealso}
619
620\subsection{\class{Message} objects}
621\label{mailbox-message-objects}
622
623\begin{classdesc}{Message}{\optional{message}}
624A subclass of the \module{email.Message} module's \class{Message}. Subclasses
625of \class{mailbox.Message} add mailbox-format-specific state and behavior.
626
627If \var{message} is omitted, the new instance is created in a default, empty
628state. If \var{message} is an \class{email.Message.Message} instance, its
629contents are copied; furthermore, any format-specific information is converted
630insofar as possible if \var{message} is a \class{Message} instance. If
631\var{message} is a string or a file, it should contain an \rfc{2822}-compliant
632message, which is read and parsed.
633\end{classdesc}
634
635The format-specific state and behaviors offered by subclasses vary, but in
636general it is only the properties that are not specific to a particular mailbox
637that are supported (although presumably the properties are specific to a
638particular mailbox format). For example, file offsets for single-file mailbox
639formats and file names for directory-based mailbox formats are not retained,
640because they are only applicable to the original mailbox. But state such as
641whether a message has been read by the user or marked as important is retained,
642because it applies to the message itself.
643
644There is no requirement that \class{Message} instances be used to represent
645messages retrieved using \class{Mailbox} instances. In some situations, the
646time and memory required to generate \class{Message} representations might not
647not acceptable. For such situations, \class{Mailbox} instances also offer
648string and file-like representations, and a custom message factory may be
649specified when a \class{Mailbox} instance is initialized.
650
651\subsubsection{\class{MaildirMessage}}
652\label{mailbox-maildirmessage}
653
654\begin{classdesc}{MaildirMessage}{\optional{message}}
655A message with Maildir-specific behaviors. Parameter \var{message}
656has the same meaning as with the \class{Message} constructor.
657\end{classdesc}
658
659Typically, a mail user agent application moves all of the messages in the
660\file{new} subdirectory to the \file{cur} subdirectory after the first time the
661user opens and closes the mailbox, recording that the messages are old whether
662or not they've actually been read. Each message in \file{cur} has an "info"
663section added to its file name to store information about its state. (Some mail
664readers may also add an "info" section to messages in \file{new}.) The "info"
665section may take one of two forms: it may contain "2," followed by a list of
666standardized flags (e.g., "2,FR") or it may contain "1," followed by so-called
667experimental information. Standard flags for Maildir messages are as follows:
668
669\begin{tableiii}{l|l|l}{textrm}{Flag}{Meaning}{Explanation}
670\lineiii{D}{Draft}{Under composition}
671\lineiii{F}{Flagged}{Marked as important}
672\lineiii{P}{Passed}{Forwarded, resent, or bounced}
673\lineiii{R}{Replied}{Replied to}
674\lineiii{S}{Seen}{Read}
675\lineiii{T}{Trashed}{Marked for subsequent deletion}
676\end{tableiii}
677
678\class{MaildirMessage} instances offer the following methods:
679
680\begin{methoddesc}{get_subdir}{}
681Return either "new" (if the message should be stored in the \file{new}
682subdirectory) or "cur" (if the message should be stored in the \file{cur}
683subdirectory). \note{A message is typically moved from \file{new} to \file{cur}
684after its mailbox has been accessed, whether or not the message is has been
685read. A message \code{msg} has been read if \code{"S" not in msg.get_flags()}
686is \code{True}.}
687\end{methoddesc}
688
689\begin{methoddesc}{set_subdir}{subdir}
690Set the subdirectory the message should be stored in. Parameter \var{subdir}
691must be either "new" or "cur".
692\end{methoddesc}
693
694\begin{methoddesc}{get_flags}{}
695Return a string specifying the flags that are currently set. If the message
696complies with the standard Maildir format, the result is the concatenation in
697alphabetical order of zero or one occurrence of each of \character{D},
698\character{F}, \character{P}, \character{R}, \character{S}, and \character{T}.
699The empty string is returned if no flags are set or if "info" contains
700experimental semantics.
701\end{methoddesc}
702
703\begin{methoddesc}{set_flags}{flags}
704Set the flags specified by \var{flags} and unset all others.
705\end{methoddesc}
706
707\begin{methoddesc}{add_flag}{flag}
708Set the flag(s) specified by \var{flag} without changing other flags. To add
709more than one flag at a time, \var{flag} may be a string of more than one
710character. The current "info" is overwritten whether or not it contains
711experimental information rather than
712flags.
713\end{methoddesc}
714
715\begin{methoddesc}{remove_flag}{flag}
716Unset the flag(s) specified by \var{flag} without changing other flags. To
717remove more than one flag at a time, \var{flag} maybe a string of more than one
718character. If "info" contains experimental information rather than flags, the
719current "info" is not modified.
720\end{methoddesc}
721
722\begin{methoddesc}{get_date}{}
723Return the delivery date of the message as a floating-point number representing
724seconds since the epoch.
725\end{methoddesc}
726
727\begin{methoddesc}{set_date}{date}
728Set the delivery date of the message to \var{date}, a floating-point number
729representing seconds since the epoch.
730\end{methoddesc}
731
732\begin{methoddesc}{get_info}{}
733Return a string containing the "info" for a message. This is useful for
734accessing and modifying "info" that is experimental (i.e., not a list of
735flags).
736\end{methoddesc}
737
738\begin{methoddesc}{set_info}{info}
739Set "info" to \var{info}, which should be a string.
740\end{methoddesc}
741
742When a \class{MaildirMessage} instance is created based upon an
743\class{mboxMessage} or \class{MMDFMessage} instance, the \mailheader{Status}
744and \mailheader{X-Status} headers are omitted and the following conversions
745take place:
746
747\begin{tableii}{l|l}{textrm}
748 {Resulting state}{\class{mboxMessage} or \class{MMDFMessage} state}
749\lineii{"cur" subdirectory}{O flag}
750\lineii{F flag}{F flag}
751\lineii{R flag}{A flag}
752\lineii{S flag}{R flag}
753\lineii{T flag}{D flag}
754\end{tableii}
755
756When a \class{MaildirMessage} instance is created based upon an
757\class{MHMessage} instance, the following conversions take place:
758
759\begin{tableii}{l|l}{textrm}
760 {Resulting state}{\class{MHMessage} state}
761\lineii{"cur" subdirectory}{"unseen" sequence}
762\lineii{"cur" subdirectory and S flag}{no "unseen" sequence}
763\lineii{F flag}{"flagged" sequence}
764\lineii{R flag}{"replied" sequence}
765\end{tableii}
766
767When a \class{MaildirMessage} instance is created based upon a
768\class{BabylMessage} instance, the following conversions take place:
769
770\begin{tableii}{l|l}{textrm}
771 {Resulting state}{\class{BabylMessage} state}
772\lineii{"cur" subdirectory}{"unseen" label}
773\lineii{"cur" subdirectory and S flag}{no "unseen" label}
774\lineii{P flag}{"forwarded" or "resent" label}
775\lineii{R flag}{"answered" label}
776\lineii{T flag}{"deleted" label}
777\end{tableii}
778
779\subsubsection{\class{mboxMessage}}
780\label{mailbox-mboxmessage}
781
782\begin{classdesc}{mboxMessage}{\optional{message}}
783A message with mbox-specific behaviors. Parameter \var{message} has the same
784meaning as with the \class{Message} constructor.
785\end{classdesc}
786
787Messages in an mbox mailbox are stored together in a single file. The sender's
788envelope address and the time of delivery are typically stored in a line
789beginning with "From~" that is used to indicate the start of a message, though
790there is considerable variation in the exact format of this data among mbox
791implementations. Flags that indicate the state of the message, such as whether
792it has been read or marked as important, are typically stored in
793\mailheader{Status} and \mailheader{X-Status} headers.
794
795Conventional flags for mbox messages are as follows:
796
797\begin{tableiii}{l|l|l}{textrm}{Flag}{Meaning}{Explanation}
798\lineiii{R}{Read}{Read}
799\lineiii{O}{Old}{Previously detected by MUA}
800\lineiii{D}{Deleted}{Marked for subsequent deletion}
801\lineiii{F}{Flagged}{Marked as important}
802\lineiii{A}{Answered}{Replied to}
803\end{tableiii}
804
805The "R" and "O" flags are stored in the \mailheader{Status} header, and the
806"D", "F", and "A" flags are stored in the \mailheader{X-Status} header. The
807flags and headers typically appear in the order mentioned.
808
809\class{mboxMessage} instances offer the following methods:
810
811\begin{methoddesc}{get_from}{}
812Return a string representing the "From~" line that marks the start of the
813message in an mbox mailbox. The leading "From~" and the trailing newline are
814excluded.
815\end{methoddesc}
816
817\begin{methoddesc}{set_from}{from_\optional{, time_=None}}
818Set the "From~" line to \var{from_}, which should be specified without a
819leading "From~" or trailing newline. For convenience, \var{time_} may be
820specified and will be formatted appropriately and appended to \var{from_}. If
821\var{time_} is specified, it should be a \class{struct_time} instance, a tuple
822suitable for passing to \method{time.strftime()}, or \code{True} (to use
823\method{time.gmtime()}).
824\end{methoddesc}
825
826\begin{methoddesc}{get_flags}{}
827Return a string specifying the flags that are currently set. If the message
828complies with the conventional format, the result is the concatenation in the
829following order of zero or one occurrence of each of \character{R},
830\character{O}, \character{D}, \character{F}, and \character{A}.
831\end{methoddesc}
832
833\begin{methoddesc}{set_flags}{flags}
834Set the flags specified by \var{flags} and unset all others. Parameter
835\var{flags} should be the concatenation in any order of zero or more
836occurrences of each of \character{R}, \character{O}, \character{D},
837\character{F}, and \character{A}.
838\end{methoddesc}
839
840\begin{methoddesc}{add_flag}{flag}
841Set the flag(s) specified by \var{flag} without changing other flags. To add
842more than one flag at a time, \var{flag} may be a string of more than one
843character.
844\end{methoddesc}
845
846\begin{methoddesc}{remove_flag}{flag}
847Unset the flag(s) specified by \var{flag} without changing other flags. To
848remove more than one flag at a time, \var{flag} maybe a string of more than one
849character.
850\end{methoddesc}
851
852When an \class{mboxMessage} instance is created based upon a
853\class{MaildirMessage} instance, a "From~" line is generated based upon the
854\class{MaildirMessage} instance's delivery date, and the following conversions
855take place:
856
857\begin{tableii}{l|l}{textrm}
858 {Resulting state}{\class{MaildirMessage} state}
859\lineii{R flag}{S flag}
860\lineii{O flag}{"cur" subdirectory}
861\lineii{D flag}{T flag}
862\lineii{F flag}{F flag}
863\lineii{A flag}{R flag}
864\end{tableii}
865
866When an \class{mboxMessage} instance is created based upon an \class{MHMessage}
867instance, the following conversions take place:
868
869\begin{tableii}{l|l}{textrm}
870 {Resulting state}{\class{MHMessage} state}
871\lineii{R flag and O flag}{no "unseen" sequence}
872\lineii{O flag}{"unseen" sequence}
873\lineii{F flag}{"flagged" sequence}
874\lineii{A flag}{"replied" sequence}
875\end{tableii}
876
877When an \class{mboxMessage} instance is created based upon a
878\class{BabylMessage} instance, the following conversions take place:
879
880\begin{tableii}{l|l}{textrm}
881 {Resulting state}{\class{BabylMessage} state}
882\lineii{R flag and O flag}{no "unseen" label}
883\lineii{O flag}{"unseen" label}
884\lineii{D flag}{"deleted" label}
885\lineii{A flag}{"answered" label}
886\end{tableii}
887
888When a \class{Message} instance is created based upon an \class{MMDFMessage}
889instance, the "From~" line is copied and all flags directly correspond:
890
891\begin{tableii}{l|l}{textrm}
892 {Resulting state}{\class{MMDFMessage} state}
893\lineii{R flag}{R flag}
894\lineii{O flag}{O flag}
895\lineii{D flag}{D flag}
896\lineii{F flag}{F flag}
897\lineii{A flag}{A flag}
898\end{tableii}
899
900\subsubsection{\class{MHMessage}}
901\label{mailbox-mhmessage}
902
903\begin{classdesc}{MHMessage}{\optional{message}}
904A message with MH-specific behaviors. Parameter \var{message} has the same
905meaning as with the \class{Message} constructor.
906\end{classdesc}
907
908MH messages do not support marks or flags in the traditional sense, but they do
909support sequences, which are logical groupings of arbitrary messages. Some mail
910reading programs (although not the standard \program{mh} and \program{nmh}) use
911sequences in much the same way flags are used with other formats, as follows:
912
913\begin{tableii}{l|l}{textrm}{Sequence}{Explanation}
914\lineii{unseen}{Not read, but previously detected by MUA}
915\lineii{replied}{Replied to}
916\lineii{flagged}{Marked as important}
917\end{tableii}
918
919\class{MHMessage} instances offer the following methods:
920
921\begin{methoddesc}{get_sequences}{}
922Return a list of the names of sequences that include this message.
923\end{methoddesc}
924
925\begin{methoddesc}{set_sequences}{sequences}
926Set the list of sequences that include this message.
927\end{methoddesc}
928
929\begin{methoddesc}{add_sequence}{sequence}
930Add \var{sequence} to the list of sequences that include this message.
931\end{methoddesc}
932
933\begin{methoddesc}{remove_sequence}{sequence}
934Remove \var{sequence} from the list of sequences that include this message.
935\end{methoddesc}
936
937When an \class{MHMessage} instance is created based upon a
938\class{MaildirMessage} instance, the following conversions take place:
939
940\begin{tableii}{l|l}{textrm}
941 {Resulting state}{\class{MaildirMessage} state}
942\lineii{"unseen" sequence}{no S flag}
943\lineii{"replied" sequence}{R flag}
944\lineii{"flagged" sequence}{F flag}
945\end{tableii}
946
947When an \class{MHMessage} instance is created based upon an \class{mboxMessage}
948or \class{MMDFMessage} instance, the \mailheader{Status} and
949\mailheader{X-Status} headers are omitted and the following conversions take
950place:
951
952\begin{tableii}{l|l}{textrm}
953 {Resulting state}{\class{mboxMessage} or \class{MMDFMessage} state}
954\lineii{"unseen" sequence}{no R flag}
955\lineii{"replied" sequence}{A flag}
956\lineii{"flagged" sequence}{F flag}
957\end{tableii}
958
959When an \class{MHMessage} instance is created based upon a \class{BabylMessage}
960instance, the following conversions take place:
961
962\begin{tableii}{l|l}{textrm}
963 {Resulting state}{\class{BabylMessage} state}
964\lineii{"unseen" sequence}{"unseen" label}
965\lineii{"replied" sequence}{"answered" label}
966\end{tableii}
967
968\subsubsection{\class{BabylMessage}}
969\label{mailbox-babylmessage}
970
971\begin{classdesc}{BabylMessage}{\optional{message}}
972A message with Babyl-specific behaviors. Parameter \var{message} has the same
973meaning as with the \class{Message} constructor.
974\end{classdesc}
975
976Certain message labels, called \dfn{attributes}, are defined by convention to
977have special meanings. The attributes are as follows:
978
979\begin{tableii}{l|l}{textrm}{Label}{Explanation}
980\lineii{unseen}{Not read, but previously detected by MUA}
981\lineii{deleted}{Marked for subsequent deletion}
982\lineii{filed}{Copied to another file or mailbox}
983\lineii{answered}{Replied to}
984\lineii{forwarded}{Forwarded}
985\lineii{edited}{Modified by the user}
986\lineii{resent}{Resent}
987\end{tableii}
988
989By default, Rmail displays only
990visible headers. The \class{BabylMessage} class, though, uses the original
991headers because they are more complete. Visible headers may be accessed
992explicitly if desired.
993
994\class{BabylMessage} instances offer the following methods:
995
996\begin{methoddesc}{get_labels}{}
997Return a list of labels on the message.
998\end{methoddesc}
999
1000\begin{methoddesc}{set_labels}{labels}
1001Set the list of labels on the message to \var{labels}.
1002\end{methoddesc}
1003
1004\begin{methoddesc}{add_label}{label}
1005Add \var{label} to the list of labels on the message.
1006\end{methoddesc}
1007
1008\begin{methoddesc}{remove_label}{label}
1009Remove \var{label} from the list of labels on the message.
1010\end{methoddesc}
1011
1012\begin{methoddesc}{get_visible}{}
1013Return an \class{Message} instance whose headers are the message's visible
1014headers and whose body is empty.
1015\end{methoddesc}
1016
1017\begin{methoddesc}{set_visible}{visible}
1018Set the message's visible headers to be the same as the headers in
1019\var{message}. Parameter \var{visible} should be a \class{Message} instance, an
1020\class{email.Message.Message} instance, a string, or a file-like object (which
1021should be open in text mode).
1022\end{methoddesc}
1023
1024\begin{methoddesc}{update_visible}{}
1025When a \class{BabylMessage} instance's original headers are modified, the
1026visible headers are not automatically modified to correspond. This method
1027updates the visible headers as follows: each visible header with a
1028corresponding original header is set to the value of the original header, each
1029visible header without a corresponding original header is removed, and any of
1030\mailheader{Date}, \mailheader{From}, \mailheader{Reply-To}, \mailheader{To},
1031\mailheader{CC}, and \mailheader{Subject} that are present in the original
1032headers but not the visible headers are added to the visible headers.
1033\end{methoddesc}
1034
1035When a \class{BabylMessage} instance is created based upon a
1036\class{MaildirMessage} instance, the following conversions take place:
1037
1038\begin{tableii}{l|l}{textrm}
1039 {Resulting state}{\class{MaildirMessage} state}
1040\lineii{"unseen" label}{no S flag}
1041\lineii{"deleted" label}{T flag}
1042\lineii{"answered" label}{R flag}
1043\lineii{"forwarded" label}{P flag}
1044\end{tableii}
1045
1046When a \class{BabylMessage} instance is created based upon an
1047\class{mboxMessage} or \class{MMDFMessage} instance, the \mailheader{Status}
1048and \mailheader{X-Status} headers are omitted and the following conversions
1049take place:
1050
1051\begin{tableii}{l|l}{textrm}
1052 {Resulting state}{\class{mboxMessage} or \class{MMDFMessage} state}
1053\lineii{"unseen" label}{no R flag}
1054\lineii{"deleted" label}{D flag}
1055\lineii{"answered" label}{A flag}
1056\end{tableii}
1057
1058When a \class{BabylMessage} instance is created based upon an \class{MHMessage}
1059instance, the following conversions take place:
1060
1061\begin{tableii}{l|l}{textrm}
1062 {Resulting state}{\class{MHMessage} state}
1063\lineii{"unseen" label}{"unseen" sequence}
1064\lineii{"answered" label}{"replied" sequence}
1065\end{tableii}
1066
1067\subsubsection{\class{MMDFMessage}}
1068\label{mailbox-mmdfmessage}
1069
1070\begin{classdesc}{MMDFMessage}{\optional{message}}
1071A message with MMDF-specific behaviors. Parameter \var{message} has the same
1072meaning as with the \class{Message} constructor.
1073\end{classdesc}
1074
1075As with message in an mbox mailbox, MMDF messages are stored with the sender's
1076address and the delivery date in an initial line beginning with "From ".
1077Likewise, flags that indicate the state of the message are typically stored in
1078\mailheader{Status} and \mailheader{X-Status} headers.
1079
1080Conventional flags for MMDF messages are identical to those of mbox message and
1081are as follows:
1082
1083\begin{tableiii}{l|l|l}{textrm}{Flag}{Meaning}{Explanation}
1084\lineiii{R}{Read}{Read}
1085\lineiii{O}{Old}{Previously detected by MUA}
1086\lineiii{D}{Deleted}{Marked for subsequent deletion}
1087\lineiii{F}{Flagged}{Marked as important}
1088\lineiii{A}{Answered}{Replied to}
1089\end{tableiii}
1090
1091The "R" and "O" flags are stored in the \mailheader{Status} header, and the
1092"D", "F", and "A" flags are stored in the \mailheader{X-Status} header. The
1093flags and headers typically appear in the order mentioned.
1094
1095\class{MMDFMessage} instances offer the following methods, which are identical
1096to those offered by \class{mboxMessage}:
1097
1098\begin{methoddesc}{get_from}{}
1099Return a string representing the "From~" line that marks the start of the
1100message in an mbox mailbox. The leading "From~" and the trailing newline are
1101excluded.
1102\end{methoddesc}
1103
1104\begin{methoddesc}{set_from}{from_\optional{, time_=None}}
1105Set the "From~" line to \var{from_}, which should be specified without a
1106leading "From~" or trailing newline. For convenience, \var{time_} may be
1107specified and will be formatted appropriately and appended to \var{from_}. If
1108\var{time_} is specified, it should be a \class{struct_time} instance, a tuple
1109suitable for passing to \method{time.strftime()}, or \code{True} (to use
1110\method{time.gmtime()}).
1111\end{methoddesc}
1112
1113\begin{methoddesc}{get_flags}{}
1114Return a string specifying the flags that are currently set. If the message
1115complies with the conventional format, the result is the concatenation in the
1116following order of zero or one occurrence of each of \character{R},
1117\character{O}, \character{D}, \character{F}, and \character{A}.
1118\end{methoddesc}
1119
1120\begin{methoddesc}{set_flags}{flags}
1121Set the flags specified by \var{flags} and unset all others. Parameter
1122\var{flags} should be the concatenation in any order of zero or more
1123occurrences of each of \character{R}, \character{O}, \character{D},
1124\character{F}, and \character{A}.
1125\end{methoddesc}
1126
1127\begin{methoddesc}{add_flag}{flag}
1128Set the flag(s) specified by \var{flag} without changing other flags. To add
1129more than one flag at a time, \var{flag} may be a string of more than one
1130character.
1131\end{methoddesc}
1132
1133\begin{methoddesc}{remove_flag}{flag}
1134Unset the flag(s) specified by \var{flag} without changing other flags. To
1135remove more than one flag at a time, \var{flag} maybe a string of more than one
1136character.
1137\end{methoddesc}
1138
1139When an \class{MMDFMessage} instance is created based upon a
1140\class{MaildirMessage} instance, a "From~" line is generated based upon the
1141\class{MaildirMessage} instance's delivery date, and the following conversions
1142take place:
1143
1144\begin{tableii}{l|l}{textrm}
1145 {Resulting state}{\class{MaildirMessage} state}
1146\lineii{R flag}{S flag}
1147\lineii{O flag}{"cur" subdirectory}
1148\lineii{D flag}{T flag}
1149\lineii{F flag}{F flag}
1150\lineii{A flag}{R flag}
1151\end{tableii}
1152
1153When an \class{MMDFMessage} instance is created based upon an \class{MHMessage}
1154instance, the following conversions take place:
1155
1156\begin{tableii}{l|l}{textrm}
1157 {Resulting state}{\class{MHMessage} state}
1158\lineii{R flag and O flag}{no "unseen" sequence}
1159\lineii{O flag}{"unseen" sequence}
1160\lineii{F flag}{"flagged" sequence}
1161\lineii{A flag}{"replied" sequence}
1162\end{tableii}
1163
1164When an \class{MMDFMessage} instance is created based upon a
1165\class{BabylMessage} instance, the following conversions take place:
1166
1167\begin{tableii}{l|l}{textrm}
1168 {Resulting state}{\class{BabylMessage} state}
1169\lineii{R flag and O flag}{no "unseen" label}
1170\lineii{O flag}{"unseen" label}
1171\lineii{D flag}{"deleted" label}
1172\lineii{A flag}{"answered" label}
1173\end{tableii}
1174
1175When an \class{MMDFMessage} instance is created based upon an
1176\class{mboxMessage} instance, the "From~" line is copied and all flags directly
1177correspond:
1178
1179\begin{tableii}{l|l}{textrm}
1180 {Resulting state}{\class{mboxMessage} state}
1181\lineii{R flag}{R flag}
1182\lineii{O flag}{O flag}
1183\lineii{D flag}{D flag}
1184\lineii{F flag}{F flag}
1185\lineii{A flag}{A flag}
1186\end{tableii}
1187
1188\subsection{Exceptions}
1189\label{mailbox-deprecated}
1190
1191The following exception classes are defined in the \module{mailbox} module:
1192
1193\begin{classdesc}{Error}{}
1194The based class for all other module-specific exceptions.
1195\end{classdesc}
1196
1197\begin{classdesc}{NoSuchMailboxError}{}
1198Raised when a mailbox is expected but is not found, such as when instantiating
1199a \class{Mailbox} subclass with a path that does not exist (and with the
1200\var{create} parameter set to \code{False}), or when opening a folder that does
1201not exist.
1202\end{classdesc}
1203
1204\begin{classdesc}{NotEmptyErrorError}{}
1205Raised when a mailbox is not empty but is expected to be, such as when deleting
1206a folder that contains messages.
1207\end{classdesc}
1208
1209\begin{classdesc}{ExternalClashError}{}
1210Raised when some mailbox-related condition beyond the control of the program
1211causes it to be unable to proceed, such as when failing to acquire a lock that
1212another program already holds a lock, or when a uniquely-generated file name
1213already exists.
1214\end{classdesc}
1215
1216\begin{classdesc}{FormatError}{}
1217Raised when the data in a file cannot be parsed, such as when an \class{MH}
1218instance attempts to read a corrupted \file{.mh_sequences} file.
1219\end{classdesc}
1220
1221\subsection{Deprecated classes and methods}
1222\label{mailbox-deprecated}
1223
1224Older versions of the \module{mailbox} module do not support modification of
1225mailboxes, such as adding or removing message, and do not provide classes to
1226represent format-specific message properties. For backward compatibility, the
1227older mailbox classes are still available, but the newer classes should be used
1228in preference to them.
1229
1230Older mailbox objects support only iteration and provide a single public
1231method:
1232
1233\begin{methoddesc}{next}{}
1234Return the next message in the mailbox, created with the optional \var{factory}
1235argument passed into the mailbox object's constructor. By default this is an
1236\class{rfc822.Message} object (see the \refmodule{rfc822} module). Depending
1237on the mailbox implementation the \var{fp} attribute of this object may be a
1238true file object or a class instance simulating a file object, taking care of
1239things like message boundaries if multiple mail messages are contained in a
1240single file, etc. If no more messages are available, this method returns
1241\code{None}.
1242\end{methoddesc}
1243
1244Most of the older mailbox classes have names that differ from the current
1245mailbox class names, except for \class{Maildir}. For this reason, the new
1246\class{Maildir} class defines a \method{next()} method and its constructor
1247differs slightly from those of the other new mailbox classes.
1248
1249The older mailbox classes whose names are not the same as their newer
1250counterparts are as follows:
Guido van Rossum39a23cc1997-06-02 21:04:41 +00001251
Barry Warsaw30dbd142001-01-31 22:14:01 +00001252\begin{classdesc}{UnixMailbox}{fp\optional{, factory}}
Fred Drake62700312001-02-02 03:51:05 +00001253Access to a classic \UNIX-style mailbox, where all messages are
1254contained in a single file and separated by \samp{From }
1255(a.k.a.\ \samp{From_}) lines. The file object \var{fp} points to the
1256mailbox file. The optional \var{factory} parameter is a callable that
1257should create new message objects. \var{factory} is called with one
1258argument, \var{fp} by the \method{next()} method of the mailbox
1259object. The default is the \class{rfc822.Message} class (see the
Barry Warsaw47db2522003-06-20 22:04:03 +00001260\refmodule{rfc822} module -- and the note below).
Barry Warsaw30dbd142001-01-31 22:14:01 +00001261
Fred Drake0d736212004-05-11 05:29:34 +00001262\begin{notice}
1263 For reasons of this module's internal implementation, you will
1264 probably want to open the \var{fp} object in binary mode. This is
1265 especially important on Windows.
1266\end{notice}
Barry Warsawdd69b0a2004-05-10 23:12:52 +00001267
Fred Drake62700312001-02-02 03:51:05 +00001268For maximum portability, messages in a \UNIX-style mailbox are
1269separated by any line that begins exactly with the string \code{'From
1270'} (note the trailing space) if preceded by exactly two newlines.
1271Because of the wide-range of variations in practice, nothing else on
1272the From_ line should be considered. However, the current
1273implementation doesn't check for the leading two newlines. This is
1274usually fine for most applications.
Barry Warsaw30dbd142001-01-31 22:14:01 +00001275
1276The \class{UnixMailbox} class implements a more strict version of
1277From_ line checking, using a regular expression that usually correctly
1278matched From_ delimiters. It considers delimiter line to be separated
Fred Drake62700312001-02-02 03:51:05 +00001279by \samp{From \var{name} \var{time}} lines. For maximum portability,
1280use the \class{PortableUnixMailbox} class instead. This class is
1281identical to \class{UnixMailbox} except that individual messages are
1282separated by only \samp{From } lines.
Barry Warsaw30dbd142001-01-31 22:14:01 +00001283
Fred Drake62700312001-02-02 03:51:05 +00001284For more information, see
1285\citetitle[http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html]{Configuring
1286Netscape Mail on \UNIX: Why the Content-Length Format is Bad}.
1287\end{classdesc}
1288
1289\begin{classdesc}{PortableUnixMailbox}{fp\optional{, factory}}
1290A less-strict version of \class{UnixMailbox}, which considers only the
1291\samp{From } at the beginning of the line separating messages. The
1292``\var{name} \var{time}'' portion of the From line is ignored, to
1293protect against some variations that are observed in practice. This
1294works since lines in the message which begin with \code{'From '} are
Greg Ward02669a32002-09-23 19:32:42 +00001295quoted by mail handling software at delivery-time.
Fred Drake2e495c91998-03-14 06:48:33 +00001296\end{classdesc}
Guido van Rossum39a23cc1997-06-02 21:04:41 +00001297
Barry Warsaw30dbd142001-01-31 22:14:01 +00001298\begin{classdesc}{MmdfMailbox}{fp\optional{, factory}}
Guido van Rossum39a23cc1997-06-02 21:04:41 +00001299Access an MMDF-style mailbox, where all messages are contained
1300in a single file and separated by lines consisting of 4 control-A
Fred Drake6e99adb1998-02-13 22:17:21 +00001301characters. The file object \var{fp} points to the mailbox file.
Barry Warsaw30dbd142001-01-31 22:14:01 +00001302Optional \var{factory} is as with the \class{UnixMailbox} class.
Fred Drake2e495c91998-03-14 06:48:33 +00001303\end{classdesc}
Guido van Rossum39a23cc1997-06-02 21:04:41 +00001304
Barry Warsaw30dbd142001-01-31 22:14:01 +00001305\begin{classdesc}{MHMailbox}{dirname\optional{, factory}}
Guido van Rossum39a23cc1997-06-02 21:04:41 +00001306Access an MH mailbox, a directory with each message in a separate
Fred Drake6e99adb1998-02-13 22:17:21 +00001307file with a numeric name.
1308The name of the mailbox directory is passed in \var{dirname}.
Barry Warsaw30dbd142001-01-31 22:14:01 +00001309\var{factory} is as with the \class{UnixMailbox} class.
Fred Drake2e495c91998-03-14 06:48:33 +00001310\end{classdesc}
Guido van Rossum39a23cc1997-06-02 21:04:41 +00001311
Barry Warsaw30dbd142001-01-31 22:14:01 +00001312\begin{classdesc}{BabylMailbox}{fp\optional{, factory}}
Barry Warsawc3cbbaf2001-04-11 20:12:33 +00001313Access a Babyl mailbox, which is similar to an MMDF mailbox. In
1314Babyl format, each message has two sets of headers, the
1315\emph{original} headers and the \emph{visible} headers. The original
Raymond Hettinger999b57c2003-08-25 04:28:05 +00001316headers appear before a line containing only \code{'*** EOOH ***'}
Barry Warsawc3cbbaf2001-04-11 20:12:33 +00001317(End-Of-Original-Headers) and the visible headers appear after the
1318\code{EOOH} line. Babyl-compliant mail readers will show you only the
1319visible headers, and \class{BabylMailbox} objects will return messages
1320containing only the visible headers. You'll have to do your own
1321parsing of the mailbox file to get at the original headers. Mail
1322messages start with the EOOH line and end with a line containing only
1323\code{'\e{}037\e{}014'}. \var{factory} is as with the
1324\class{UnixMailbox} class.
Fred Drake199b79c1999-02-20 05:04:59 +00001325\end{classdesc}
1326
Andrew M. Kuchling1da4a942006-04-22 02:32:43 +00001327If you wish to use the older mailbox classes with the \module{email} module
1328rather than the deprecated \module{rfc822} module, you can do so as follows:
Barry Warsaw47db2522003-06-20 22:04:03 +00001329
1330\begin{verbatim}
1331import email
1332import email.Errors
1333import mailbox
1334
1335def msgfactory(fp):
1336 try:
1337 return email.message_from_file(fp)
1338 except email.Errors.MessageParseError:
1339 # Don't return None since that will
Andrew M. Kuchling1da4a942006-04-22 02:32:43 +00001340 # stop the mailbox iterator
1341 return ''
Barry Warsaw47db2522003-06-20 22:04:03 +00001342
1343mbox = mailbox.UnixMailbox(fp, msgfactory)
1344\end{verbatim}
1345
Andrew M. Kuchling1da4a942006-04-22 02:32:43 +00001346Alternatively, if you know your mailbox contains only well-formed MIME
1347messages, you can simplify this to:
Barry Warsaw47db2522003-06-20 22:04:03 +00001348
1349\begin{verbatim}
1350import email
1351import mailbox
1352
1353mbox = mailbox.UnixMailbox(fp, email.message_from_file)
1354\end{verbatim}
Fred Drake199b79c1999-02-20 05:04:59 +00001355
Andrew M. Kuchling1da4a942006-04-22 02:32:43 +00001356\subsection{Examples}
1357\label{mailbox-examples}
Fred Drake1400baa2001-05-21 21:23:01 +00001358
Andrew M. Kuchling1da4a942006-04-22 02:32:43 +00001359A simple example of printing the subjects of all messages in a mailbox that
1360seem interesting:
Fred Drake1400baa2001-05-21 21:23:01 +00001361
Andrew M. Kuchling1da4a942006-04-22 02:32:43 +00001362\begin{verbatim}
1363import mailbox
1364for message in mailbox.mbox('~/mbox'):
1365 subject = message['subject'] # Could possibly be None.
1366 if subject and 'python' in subject.lower():
1367 print subject
1368\end{verbatim}
Guido van Rossum39a23cc1997-06-02 21:04:41 +00001369
Andrew M. Kuchling1da4a942006-04-22 02:32:43 +00001370A (surprisingly) simple example of copying all mail from a Babyl mailbox to an
1371MH mailbox, converting all of the format-specific information that can be
1372converted:
Guido van Rossum39a23cc1997-06-02 21:04:41 +00001373
Andrew M. Kuchling1da4a942006-04-22 02:32:43 +00001374\begin{verbatim}
1375import mailbox
1376destination = mailbox.MH('~/Mail')
1377for message in mailbox.Babyl('~/RMAIL'):
1378 destination.add(MHMessage(message))
1379\end{verbatim}
1380
1381An example of sorting mail from numerous mailing lists, being careful to avoid
1382mail corruption due to concurrent modification by other programs, mail loss due
1383to interruption of the program, or premature termination due to malformed
1384messages in the mailbox:
1385
1386\begin{verbatim}
1387import mailbox
1388import email.Errors
1389list_names = ('python-list', 'python-dev', 'python-bugs')
1390boxes = dict((name, mailbox.mbox('~/email/%s' % name)) for name in list_names)
1391inbox = mailbox.Maildir('~/Maildir', None)
1392for key in inbox.iterkeys():
1393 try:
1394 message = inbox[key]
1395 except email.Errors.MessageParseError:
1396 continue # The message is malformed. Just leave it.
1397 for name in list_names:
1398 list_id = message['list-id']
1399 if list_id and name in list_id:
1400 box = boxes[name]
1401 box.lock()
1402 box.add(message)
1403 box.flush() # Write copy to disk before removing original.
1404 box.unlock()
1405 inbox.discard(key)
1406 break # Found destination, so stop looking.
1407for box in boxes.itervalues():
1408 box.close()
1409\end{verbatim}