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