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 

    11 This module defines two classes, :class:`Mailbox` and :class:`Message`, for

    12 accessing 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 :class:`Message`

    15 class with format-specific state and behavior. Supported mailbox formats are

    16 Maildir, mbox, MH, Babyl, and MMDF.

    17 

    18 

    19 .. seealso::

    20 

    21    Module :mod:`email`

    22       Represent and manipulate messages.

    23 

    24 

    25 .. _mailbox-objects:

    26 

    27 :class:`Mailbox` objects

    28 ------------------------

    29 

    30 

    31 .. class:: Mailbox

    32 

    33    A mailbox, which may be inspected and modified.

    34 

    35    The :class:`Mailbox` class defines an interface and is not intended to be

    36    instantiated.  Instead, format-specific subclasses should inherit from

    37    :class:`Mailbox` and your code should instantiate a particular subclass.

    38 

    39    The :class:`Mailbox` interface is dictionary-like, with small keys

    40    corresponding to messages. Keys are issued by the :class:`Mailbox` instance

    41    with which they will be used and are only meaningful to that :class:`Mailbox`

    42    instance. A key continues to identify a message even if the corresponding

    43    message is modified, such as by replacing it with another message.

    44 

    45    Messages may be added to a :class:`Mailbox` instance using the set-like

    46    method :meth:`add` and removed using a ``del`` statement or the set-like

    47    methods :meth:`remove` and :meth:`discard`.

    48 

    49    :class:`Mailbox` interface semantics differ from dictionary semantics in some

    50    noteworthy ways. Each time a message is requested, a new representation

    51    (typically a :class:`Message` instance) is generated based upon the current

    52    state of the mailbox. Similarly, when a message is added to a

    53    :class:`Mailbox` instance, the provided message representation's contents are

    54    copied. In neither case is a reference to the message representation kept by

    55    the :class:`Mailbox` instance.

    56 

    57    The default :class:`Mailbox` iterator iterates over message representations,

    58    not keys as the default dictionary iterator does. Moreover, modification of a

    59    mailbox during iteration is safe and well-defined. Messages added to the

    60    mailbox after an iterator is created will not be seen by the

    61    iterator. Messages removed from the mailbox before the iterator yields them

    62    will be silently skipped, though using a key from an iterator may result in a

    63    :exc:`KeyError` exception if the corresponding message is subsequently

    64    removed.

    65 

    66    .. warning::

    67 

    68       Be very cautious when modifying mailboxes that might be simultaneously

    69       changed by some other process.  The safest mailbox format to use for such

    70       tasks is Maildir; try to avoid using single-file formats such as mbox for

    71       concurrent writing.  If you're modifying a mailbox, you *must* lock it by

    72       calling the :meth:`lock` and :meth:`unlock` methods *before* reading any

    73       messages in the file or making any changes by adding or deleting a

    74       message.  Failing to lock the mailbox runs the risk of losing messages or

    75       corrupting the entire mailbox.

    76 

    77    :class:`Mailbox` instances have the following methods:

    78 

    79 

    80    .. method:: add(message)

    81 

    82       Add *message* to the mailbox and return the key that has been assigned to

    83       it.

    84 

    85       Parameter *message* may be a :class:`Message` instance, an

    86       :class:`email.Message.Message` instance, a string, or a file-like object

    87       (which should be open in text mode). If *message* is an instance of the

    88       appropriate format-specific :class:`Message` subclass (e.g., if it's an

    89       :class:`mboxMessage` instance and this is an :class:`mbox` instance), its

    90       format-specific information is used. Otherwise, reasonable defaults for

    91       format-specific information are used.

    92 

    93 

    94    .. method:: remove(key)

    95                __delitem__(key)

    96                discard(key)

    97 

    98       Delete the message corresponding to *key* from the mailbox.

    99 

   100       If no such message exists, a :exc:`KeyError` exception is raised if the

   101       method was called as :meth:`remove` or :meth:`__delitem__` but no

   102       exception is raised if the method was called as :meth:`discard`. The

   103       behavior of :meth:`discard` may be preferred if the underlying mailbox

   104       format supports concurrent modification by other processes.

   105 

   106 

   107    .. method:: __setitem__(key, message)

   108 

   109       Replace the message corresponding to *key* with *message*. Raise a

   110       :exc:`KeyError` exception if no message already corresponds to *key*.

   111 

   112       As with :meth:`add`, parameter *message* may be a :class:`Message`

   113       instance, an :class:`email.Message.Message` instance, a string, or a

   114       file-like object (which should be open in text mode). If *message* is an

   115       instance of the appropriate format-specific :class:`Message` subclass

   116       (e.g., if it's an :class:`mboxMessage` instance and this is an

   117       :class:`mbox` instance), its format-specific information is

   118       used. Otherwise, the format-specific information of the message that

   119       currently corresponds to *key* is left unchanged.

   120 

   121 

   122    .. method:: iterkeys()

   123                keys()

   124 

   125       Return an iterator over all keys if called as :meth:`iterkeys` or return a

   126       list of keys if called as :meth:`keys`.

   127 

   128 

   129    .. method:: itervalues()

   130                __iter__()

   131                values()

   132 

   133       Return an iterator over representations of all messages if called as

   134       :meth:`itervalues` or :meth:`__iter__` or return a list of such

   135       representations if called as :meth:`values`. The messages are represented

   136       as instances of the appropriate format-specific :class:`Message` subclass

   137       unless a custom message factory was specified when the :class:`Mailbox`

   138       instance was initialized.

   139 

   140       .. note::

   141 

   142          The behavior of :meth:`__iter__` is unlike that of dictionaries, which

   143          iterate over keys.

   144 

   145 

   146    .. method:: iteritems()

   147                items()

   148 

   149       Return an iterator over (*key*, *message*) pairs, where *key* is a key and

   150       *message* is a message representation, if called as :meth:`iteritems` or

   151       return a list of such pairs if called as :meth:`items`. The messages are

   152       represented as instances of the appropriate format-specific

   153       :class:`Message` subclass unless a custom message factory was specified

   154       when the :class:`Mailbox` instance was initialized.

   155 

   156 

   157    .. method:: get(key[, default=None])

   158                __getitem__(key)

   159 

   160       Return a representation of the message corresponding to *key*. If no such

   161       message exists, *default* is returned if the method was called as

   162       :meth:`get` and a :exc:`KeyError` exception is raised if the method was

   163       called as :meth:`__getitem__`. The message is represented as an instance

   164       of the appropriate format-specific :class:`Message` subclass unless a

   165       custom message factory was specified when the :class:`Mailbox` instance

   166       was initialized.

   167 

   168 

   169    .. method:: get_message(key)

   170 

   171       Return a representation of the message corresponding to *key* as an

   172       instance of the appropriate format-specific :class:`Message` subclass, or

   173       raise a :exc:`KeyError` exception if no such message exists.

   174 

   175 

   176    .. method:: get_string(key)

   177 

   178       Return a string representation of the message corresponding to *key*, or

   179       raise a :exc:`KeyError` exception if no such message exists.

   180 

   181 

   182    .. method:: get_file(key)

   183 

   184       Return a file-like representation of the message corresponding to *key*,

   185       or raise a :exc:`KeyError` exception if no such message exists. The

   186       file-like object behaves as if open in binary mode. This file should be

   187       closed once it is no longer needed.

   188 

   189       .. note::

   190 

   191          Unlike other representations of messages, file-like representations are

   192          not necessarily independent of the :class:`Mailbox` instance that

   193          created them or of the underlying mailbox. More specific documentation

   194          is provided by each subclass.

   195 

   196 

   197    .. method:: has_key(key)

   198                __contains__(key)

   199 

   200       Return ``True`` if *key* corresponds to a message, ``False`` otherwise.

   201 

   202 

   203    .. method:: __len__()

   204 

   205       Return a count of messages in the mailbox.

   206 

   207 

   208    .. method:: clear()

   209 

   210       Delete all messages from the mailbox.

   211 

   212 

   213    .. method:: pop(key[, default])

   214 

   215       Return a representation of the message corresponding to *key* and delete

   216       the message. If no such message exists, return *default* if it was

   217       supplied or else raise a :exc:`KeyError` exception. The message is

   218       represented as an instance of the appropriate format-specific

   219       :class:`Message` subclass unless a custom message factory was specified

   220       when the :class:`Mailbox` instance was initialized.

   221 

   222 

   223    .. method:: popitem()

   224 

   225       Return an arbitrary (*key*, *message*) pair, where *key* is a key and

   226       *message* is a message representation, and delete the corresponding

   227       message. If the mailbox is empty, raise a :exc:`KeyError` exception. The

   228       message is represented as an instance of the appropriate format-specific

   229       :class:`Message` subclass unless a custom message factory was specified

   230       when the :class:`Mailbox` instance was initialized.

   231 

   232 

   233    .. method:: update(arg)

   234 

   235       Parameter *arg* should be a *key*-to-*message* mapping or an iterable of

   236       (*key*, *message*) pairs. Updates the mailbox so that, for each given

   237       *key* and *message*, the message corresponding to *key* is set to

   238       *message* as if by using :meth:`__setitem__`. As with :meth:`__setitem__`,

   239       each *key* must already correspond to a message in the mailbox or else a

   240       :exc:`KeyError` exception will be raised, so in general it is incorrect

   241       for *arg* to be a :class:`Mailbox` instance.

   242 

   243       .. note::

   244 

   245          Unlike with dictionaries, keyword arguments are not supported.

   246 

   247 

   248    .. method:: flush()

   249 

   250       Write any pending changes to the filesystem. For some :class:`Mailbox`

   251       subclasses, changes are always written immediately and :meth:`flush` does

   252       nothing, but you should still make a habit of calling this method.

   253 

   254 

   255    .. method:: lock()

   256 

   257       Acquire an exclusive advisory lock on the mailbox so that other processes

   258       know not to modify it. An :exc:`ExternalClashError` is raised if the lock

   259       is not available. The particular locking mechanisms used depend upon the

   260       mailbox format.  You should *always* lock the mailbox before making any

   261       modifications to its contents.

   262 

   263 

   264    .. method:: unlock()

   265 

   266       Release the lock on the mailbox, if any.

   267 

   268 

   269    .. method:: close()

   270 

   271       Flush the mailbox, unlock it if necessary, and close any open files. For

   272       some :class:`Mailbox` subclasses, this method does nothing.

   273 

   274 

   275 .. _mailbox-maildir:

   276 

   277 :class:`Maildir`

   278 ^^^^^^^^^^^^^^^^

   279 

   280 

   281 .. class:: Maildir(dirname[, factory=rfc822.Message[, create=True]])

   282 

   283    A subclass of :class:`Mailbox` for mailboxes in Maildir format. Parameter

   284    *factory* is a callable object that accepts a file-like message representation

   285    (which behaves as if opened in binary mode) and returns a custom representation.

   286    If *factory* is ``None``, :class:`MaildirMessage` is used as the default message

   287    representation. If *create* is ``True``, the mailbox is created if it does not

   288    exist.

   289 

   290    It is for historical reasons that *factory* defaults to :class:`rfc822.Message`

   291    and that *dirname* is named as such rather than *path*. For a :class:`Maildir`

   292    instance that behaves like instances of other :class:`Mailbox` subclasses, set

   293    *factory* to ``None``.

   294 

   295    Maildir is a directory-based mailbox format invented for the qmail mail

   296    transfer agent and now widely supported by other programs. Messages in a

   297    Maildir mailbox are stored in separate files within a common directory

   298    structure. This design allows Maildir mailboxes to be accessed and modified

   299    by multiple unrelated programs without data corruption, so file locking is

   300    unnecessary.

   301 

   302    Maildir mailboxes contain three subdirectories, namely: :file:`tmp`,

   303    :file:`new`, and :file:`cur`. Messages are created momentarily in the

   304    :file:`tmp` subdirectory and then moved to the :file:`new` subdirectory to

   305    finalize delivery. A mail user agent may subsequently move the message to the

   306    :file:`cur` subdirectory and store information about the state of the message

   307    in a special "info" section appended to its file name.

   308 

   309    Folders of the style introduced by the Courier mail transfer agent are also

   310    supported. Any subdirectory of the main mailbox is considered a folder if

   311    ``'.'`` is the first character in its name. Folder names are represented by

   312    :class:`Maildir` without the leading ``'.'``. Each folder is itself a Maildir

   313    mailbox but should not contain other folders. Instead, a logical nesting is

   314    indicated using ``'.'`` to delimit levels, e.g., "Archived.2005.07".

   315 

   316    .. note::

   317 

   318       The Maildir specification requires the use of a colon (``':'``) in certain

   319       message file names. However, some operating systems do not permit this

   320       character in file names, If you wish to use a Maildir-like format on such

   321       an operating system, you should specify another character to use

   322       instead. The exclamation point (``'!'``) is a popular choice. For

   323       example::

   324 

   325          import mailbox

   326          mailbox.Maildir.colon = '!'

   327 

   328       The :attr:`colon` attribute may also be set on a per-instance basis.

   329 

   330    :class:`Maildir` instances have all of the methods of :class:`Mailbox` in

   331    addition to the following:

   332 

   333 

   334    .. method:: list_folders()

   335 

   336       Return a list of the names of all folders.

   337 

   338 

   339    .. method:: .et_folder(folder)

   340 

   341       Return a :class:`Maildir` instance representing the folder whose name is

   342       *folder*. A :exc:`NoSuchMailboxError` exception is raised if the folder

   343       does not exist.

   344 

   345 

   346    .. method:: add_folder(folder)

   347 

   348       Create a folder whose name is *folder* and return a :class:`Maildir`

   349       instance representing it.

   350 

   351 

   352    .. method:: remove_folder(folder)

   353 

   354       Delete the folder whose name is *folder*. If the folder contains any

   355       messages, a :exc:`NotEmptyError` exception will be raised and the folder

   356       will not be deleted.

   357 

   358 

   359    .. method:: clean()

   360 

   361       Delete temporary files from the mailbox that have not been accessed in the

   362       last 36 hours. The Maildir specification says that mail-reading programs

   363       should do this occasionally.

   364 

   365    Some :class:`Mailbox` methods implemented by :class:`Maildir` deserve special

   366    remarks:

   367 

   368 

   369    .. method:: add(message)

   370                __setitem__(key, message)

   371                update(arg)

   372 

   373       .. warning::

   374 

   375          These methods generate unique file names based upon the current process

   376          ID. When using multiple threads, undetected name clashes may occur and

   377          cause corruption of the mailbox unless threads are coordinated to avoid

   378          using these methods to manipulate the same mailbox simultaneously.

   379 

   380 

   381    .. method:: flush()

   382 

   383       All changes to Maildir mailboxes are immediately applied, so this method

   384       does nothing.

   385 

   386 

   387    .. method:: lock()

   388                unlock()

   389 

   390       Maildir mailboxes do not support (or require) locking, so these methods do

   391       nothing.

   392 

   393 

   394    .. method:: close()

   395 

   396       :class:`Maildir` instances do not keep any open files and the underlying

   397       mailboxes do not support locking, so this method does nothing.

   398 

   399 

   400    .. method:: get_file(key)

   401 

   402       Depending upon the host platform, it may not be possible to modify or

   403       remove the underlying message while the returned file remains open.

   404 

   405 

   406 .. seealso::

   407 

   408    `maildir man page from qmail <http://www.qmail.org/man/man5/maildir.html>`_

   409       The original specification of the format.

   410 

   411    `Using maildir format <http://cr.yp.to/proto/maildir.html>`_

   412       Notes on Maildir by its inventor. Includes an updated name-creation scheme and

   413       details on "info" semantics.

   414 

   415    `maildir man page from Courier <http://www.courier-mta.org/maildir.html>`_

   416       Another specification of the format. Describes a common extension for supporting

   417       folders.

   418 

   419 

   420 .. _mailbox-mbox:

   421 

   422 :class:`mbox`

   423 ^^^^^^^^^^^^^

   424 

   425 

   426 .. class:: mbox(path[, factory=None[, create=True]])

   427 

   428    A subclass of :class:`Mailbox` for mailboxes in mbox format. Parameter *factory*

   429    is a callable object that accepts a file-like message representation (which

   430    behaves as if opened in binary mode) and returns a custom representation. If

   431    *factory* is ``None``, :class:`mboxMessage` is used as the default message

   432    representation. If *create* is ``True``, the mailbox is created if it does not

   433    exist.

   434 

   435    The mbox format is the classic format for storing mail on Unix systems. All

   436    messages in an mbox mailbox are stored in a single file with the beginning of

   437    each message indicated by a line whose first five characters are "From ".

   438 

   439    Several variations of the mbox format exist to address perceived shortcomings in

   440    the original. In the interest of compatibility, :class:`mbox` implements the

   441    original format, which is sometimes referred to as :dfn:`mboxo`. This means that

   442    the :mailheader:`Content-Length` header, if present, is ignored and that any

   443    occurrences of "From " at the beginning of a line in a message body are

   444    transformed to ">From " when storing the message, although occurrences of ">From

   445    " are not transformed to "From " when reading the message.

   446 

   447    Some :class:`Mailbox` methods implemented by :class:`mbox` deserve special

   448    remarks:

   449 

   450 

   451    .. method:: get_file(key)

   452 

   453       Using the file after calling :meth:`flush` or :meth:`close` on the

   454       :class:`mbox` instance may yield unpredictable results or raise an

   455       exception.

   456 

   457 

   458    .. method:: lock()

   459                unlock()

   460 

   461       Three locking mechanisms are used---dot locking and, if available, the

   462       :cfunc:`flock` and :cfunc:`lockf` system calls.

   463 

   464 

   465 .. seealso::

   466 

   467    `mbox man page from qmail <http://www.qmail.org/man/man5/mbox.html>`_

   468       A specification of the format and its variations.

   469 

   470    `mbox man page from tin <http://www.tin.org/bin/man.cgi?section=5&topic=mbox>`_

   471       Another specification of the format, with details on locking.

   472 

   473    `Configuring Netscape Mail on Unix: Why The Content-Length Format is Bad <http://www.jwz.org/doc/content-length.html>`_

   474       An argument for using the original mbox format rather than a variation.

   475 

   476    `"mbox" is a family of several mutually incompatible mailbox formats <http://homepages.tesco.net./~J.deBoynePollard/FGA/mail-mbox-formats.html>`_

   477       A history of mbox variations.

   478 

   479 

   480 .. _mailbox-mh:

   481 

   482 :class:`MH`

   483 ^^^^^^^^^^^

   484 

   485 

   486 .. class:: MH(path[, factory=None[, create=True]])

   487 

   488    A subclass of :class:`Mailbox` for mailboxes in MH format. Parameter *factory*

   489    is a callable object that accepts a file-like message representation (which

   490    behaves as if opened in binary mode) and returns a custom representation. If

   491    *factory* is ``None``, :class:`MHMessage` is used as the default message

   492    representation. If *create* is ``True``, the mailbox is created if it does not

   493    exist.

   494 

   495    MH is a directory-based mailbox format invented for the MH Message Handling

   496    System, a mail user agent. Each message in an MH mailbox resides in its own

   497    file. An MH mailbox may contain other MH mailboxes (called :dfn:`folders`) in

   498    addition to messages. Folders may be nested indefinitely. MH mailboxes also

   499    support :dfn:`sequences`, which are named lists used to logically group

   500    messages without moving them to sub-folders. Sequences are defined in a file

   501    called :file:`.mh_sequences` in each folder.

   502 

   503    The :class:`MH` class manipulates MH mailboxes, but it does not attempt to

   504    emulate all of :program:`mh`'s behaviors. In particular, it does not modify

   505    and is not affected by the :file:`context` or :file:`.mh_profile` files that

   506    are used by :program:`mh` to store its state and configuration.

   507 

   508    :class:`MH` instances have all of the methods of :class:`Mailbox` in addition

   509    to the following:

   510 

   511 

   512    .. method:: list_folders()

   513 

   514       Return a list of the names of all folders.

   515 

   516 

   517    .. method:: get_folder(folder)

   518 

   519       Return an :class:`MH` instance representing the folder whose name is

   520       *folder*. A :exc:`NoSuchMailboxError` exception is raised if the folder

   521       does not exist.

   522 

   523 

   524    .. method:: add_folder(folder)

   525 

   526       Create a folder whose name is *folder* and return an :class:`MH` instance

   527       representing it.

   528 

   529 

   530    .. method:: remove_folder(folder)

   531 

   532       Delete the folder whose name is *folder*. If the folder contains any

   533       messages, a :exc:`NotEmptyError` exception will be raised and the folder

   534       will not be deleted.

   535 

   536 

   537    .. method:: get_sequences()

   538 

   539       Return a dictionary of sequence names mapped to key lists. If there are no

   540       sequences, the empty dictionary is returned.

   541 

   542 

   543    .. method:: set_sequences(sequences)

   544 

   545       Re-define the sequences that exist in the mailbox based upon *sequences*,

   546       a dictionary of names mapped to key lists, like returned by

   547       :meth:`get_sequences`.

   548 

   549 

   550    .. method:: pack()

   551 

   552       Rename messages in the mailbox as necessary to eliminate gaps in

   553       numbering.  Entries in the sequences list are updated correspondingly.

   554 

   555       .. note::

   556 

   557          Already-issued keys are invalidated by this operation and should not be

   558          subsequently used.

   559 

   560    Some :class:`Mailbox` methods implemented by :class:`MH` deserve special

   561    remarks:

   562 

   563 

   564    .. method:: remove(key)

   565                __delitem__(key)

   566                discard(key)

   567 

   568       These methods immediately delete the message. The MH convention of marking

   569       a message for deletion by prepending a comma to its name is not used.

   570 

   571 

   572    .. method:: lock()

   573                unlock()

   574 

   575       Three locking mechanisms are used---dot locking and, if available, the

   576       :cfunc:`flock` and :cfunc:`lockf` system calls. For MH mailboxes, locking

   577       the mailbox means locking the :file:`.mh_sequences` file and, only for the

   578       duration of any operations that affect them, locking individual message

   579       files.

   580 

   581 

   582    .. method:: get_file(key)

   583 

   584       Depending upon the host platform, it may not be possible to remove the

   585       underlying message while the returned file remains open.

   586 

   587 

   588    .. method:: flush()

   589 

   590       All changes to MH mailboxes are immediately applied, so this method does

   591       nothing.

   592 

   593 

   594    .. method:: close()

   595 

   596       :class:`MH` instances do not keep any open files, so this method is

   597       equivalent to :meth:`unlock`.

   598 

   599 

   600 .. seealso::

   601 

   602    `nmh - Message Handling System <http://www.nongnu.org/nmh/>`_

   603       Home page of :program:`nmh`, an updated version of the original :program:`mh`.

   604 

   605    `MH & nmh: Email for Users & Programmers <http://www.ics.uci.edu/~mh/book/>`_

   606       A GPL-licensed book on :program:`mh` and :program:`nmh`, with some information

   607       on the mailbox format.

   608 

   609 

   610 .. _mailbox-babyl:

   611 

   612 :class:`Babyl`

   613 ^^^^^^^^^^^^^^

   614 

   615 

   616 .. class:: Babyl(path[, factory=None[, create=True]])

   617 

   618    A subclass of :class:`Mailbox` for mailboxes in Babyl format. Parameter

   619    *factory* is a callable object that accepts a file-like message representation

   620    (which behaves as if opened in binary mode) and returns a custom representation.

   621    If *factory* is ``None``, :class:`BabylMessage` is used as the default message

   622    representation. If *create* is ``True``, the mailbox is created if it does not

   623    exist.

   624 

   625    Babyl is a single-file mailbox format used by the Rmail mail user agent

   626    included with Emacs. The beginning of a message is indicated by a line

   627    containing the two characters Control-Underscore (``'\037'``) and Control-L

   628    (``'\014'``). The end of a message is indicated by the start of the next

   629    message or, in the case of the last message, a line containing a

   630    Control-Underscore (``'\037'``) character.

   631 

   632    Messages in a Babyl mailbox have two sets of headers, original headers and

   633    so-called visible headers. Visible headers are typically a subset of the

   634    original headers that have been reformatted or abridged to be more

   635    attractive. Each message in a Babyl mailbox also has an accompanying list of

   636    :dfn:`labels`, or short strings that record extra information about the

   637    message, and a list of all user-defined labels found in the mailbox is kept

   638    in the Babyl options section.

   639 

   640    :class:`Babyl` instances have all of the methods of :class:`Mailbox` in

   641    addition to the following:

   642 

   643 

   644    .. method:: get_labels()

   645 

   646       Return a list of the names of all user-defined labels used in the mailbox.

   647 

   648       .. note::

   649 

   650          The actual messages are inspected to determine which labels exist in

   651          the mailbox rather than consulting the list of labels in the Babyl

   652          options section, but the Babyl section is updated whenever the mailbox

   653          is modified.

   654 

   655    Some :class:`Mailbox` methods implemented by :class:`Babyl` deserve special

   656    remarks:

   657 

   658 

   659    .. method:: get_file(key)

   660 

   661       In Babyl mailboxes, the headers of a message are not stored contiguously

   662       with the body of the message. To generate a file-like representation, the

   663       headers and body are copied together into a :class:`StringIO` instance

   664       (from the :mod:`StringIO` module), which has an API identical to that of a

   665       file. As a result, the file-like object is truly independent of the

   666       underlying mailbox but does not save memory compared to a string

   667       representation.

   668 

   669 

   670    .. method:: lock()

   671                unlock()

   672 

   673       Three locking mechanisms are used---dot locking and, if available, the

   674       :cfunc:`flock` and :cfunc:`lockf` system calls.

   675 

   676 

   677 .. seealso::

   678 

   679    `Format of Version 5 Babyl Files <http://quimby.gnus.org/notes/BABYL>`_

   680       A specification of the Babyl format.

   681 

   682    `Reading Mail with Rmail <http://www.gnu.org/software/emacs/manual/html_node/emacs/Rmail.html>`_

   683       The Rmail manual, with some information on Babyl semantics.

   684 

   685 

   686 .. _mailbox-mmdf:

   687 

   688 :class:`MMDF`

   689 ^^^^^^^^^^^^^

   690 

   691 

   692 .. class:: MMDF(path[, factory=None[, create=True]])

   693 

   694    A subclass of :class:`Mailbox` for mailboxes in MMDF format. Parameter *factory*

   695    is a callable object that accepts a file-like message representation (which

   696    behaves as if opened in binary mode) and returns a custom representation. If

   697    *factory* is ``None``, :class:`MMDFMessage` is used as the default message

   698    representation. If *create* is ``True``, the mailbox is created if it does not

   699    exist.

   700 

   701    MMDF is a single-file mailbox format invented for the Multichannel Memorandum

   702    Distribution Facility, a mail transfer agent. Each message is in the same

   703    form as an mbox message but is bracketed before and after by lines containing

   704    four Control-A (``'\001'``) characters. As with the mbox format, the

   705    beginning of each message is indicated by a line whose first five characters

   706    are "From ", but additional occurrences of "From " are not transformed to

   707    ">From " when storing messages because the extra message separator lines

   708    prevent mistaking such occurrences for the starts of subsequent messages.

   709 

   710    Some :class:`Mailbox` methods implemented by :class:`MMDF` deserve special

   711    remarks:

   712 

   713 

   714    .. method:: get_file(key)

   715 

   716       Using the file after calling :meth:`flush` or :meth:`close` on the

   717       :class:`MMDF` instance may yield unpredictable results or raise an

   718       exception.

   719 

   720 

   721    .. method:: lock()

   722                unlock()

   723 

   724       Three locking mechanisms are used---dot locking and, if available, the

   725       :cfunc:`flock` and :cfunc:`lockf` system calls.

   726 

   727 

   728 .. seealso::

   729 

   730    `mmdf man page from tin <http://www.tin.org/bin/man.cgi?section=5&topic=mmdf>`_

   731       A specification of MMDF format from the documentation of tin, a newsreader.

   732 

   733    `MMDF <http://en.wikipedia.org/wiki/MMDF>`_

   734       A Wikipedia article describing the Multichannel Memorandum Distribution

   735       Facility.

   736 

   737 

   738 .. _mailbox-message-objects:

   739 

   740 :class:`Message` objects

   741 ------------------------

   742 

   743 

   744 .. class:: Message([message])

   745 

   746    A subclass of the :mod:`email.Message` module's :class:`Message`. Subclasses of

   747    :class:`mailbox.Message` add mailbox-format-specific state and behavior.

   748 

   749    If *message* is omitted, the new instance is created in a default, empty state.

   750    If *message* is an :class:`email.Message.Message` instance, its contents are

   751    copied; furthermore, any format-specific information is converted insofar as

   752    possible if *message* is a :class:`Message` instance. If *message* is a string

   753    or a file, it should contain an :rfc:`2822`\ -compliant message, which is read

   754    and parsed.

   755 

   756    The format-specific state and behaviors offered by subclasses vary, but in

   757    general it is only the properties that are not specific to a particular

   758    mailbox that are supported (although presumably the properties are specific

   759    to a particular mailbox format). For example, file offsets for single-file

   760    mailbox formats and file names for directory-based mailbox formats are not

   761    retained, because they are only applicable to the original mailbox. But state

   762    such as whether a message has been read by the user or marked as important is

   763    retained, because it applies to the message itself.

   764 

   765    There is no requirement that :class:`Message` instances be used to represent

   766    messages retrieved using :class:`Mailbox` instances. In some situations, the

   767    time and memory required to generate :class:`Message` representations might

   768    not not acceptable. For such situations, :class:`Mailbox` instances also

   769    offer string and file-like representations, and a custom message factory may

   770    be specified when a :class:`Mailbox` instance is initialized.

   771 

   772 

   773 .. _mailbox-maildirmessage:

   774 

   775 :class:`MaildirMessage`

   776 ^^^^^^^^^^^^^^^^^^^^^^^

   777 

   778 

   779 .. class:: MaildirMessage([message])

   780 

   781    A message with Maildir-specific behaviors. Parameter *message* has the same

   782    meaning as with the :class:`Message` constructor.

   783 

   784    Typically, a mail user agent application moves all of the messages in the

   785    :file:`new` subdirectory to the :file:`cur` subdirectory after the first time

   786    the user opens and closes the mailbox, recording that the messages are old

   787    whether or not they've actually been read. Each message in :file:`cur` has an

   788    "info" section added to its file name to store information about its state.

   789    (Some mail readers may also add an "info" section to messages in

   790    :file:`new`.)  The "info" section may take one of two forms: it may contain

   791    "2," followed by a list of standardized flags (e.g., "2,FR") or it may

   792    contain "1," followed by so-called experimental information. Standard flags

   793    for Maildir messages are as follows:

   794 

   795    +------+---------+--------------------------------+

   796    | Flag | Meaning | Explanation                    |

   797    +======+=========+================================+

   798    | D    | Draft   | Under composition              |

   799    +------+---------+--------------------------------+

   800    | F    | Flagged | Marked as important            |

   801    +------+---------+--------------------------------+

   802    | P    | Passed  | Forwarded, resent, or bounced  |

   803    +------+---------+--------------------------------+

   804    | R    | Replied | Replied to                     |

   805    +------+---------+--------------------------------+

   806    | S    | Seen    | Read                           |

   807    +------+---------+--------------------------------+

   808    | T    | Trashed | Marked for subsequent deletion |

   809    +------+---------+--------------------------------+

   810 

   811    :class:`MaildirMessage` instances offer the following methods:

   812 

   813 

   814    .. method:: get_subdir()

   815 

   816       Return either "new" (if the message should be stored in the :file:`new`

   817       subdirectory) or "cur" (if the message should be stored in the :file:`cur`

   818       subdirectory).

   819 

   820       .. note::

   821 

   822          A message is typically moved from :file:`new` to :file:`cur` after its

   823          mailbox has been accessed, whether or not the message is has been

   824          read. A message ``msg`` has been read if ``"S" in msg.get_flags()`` is

   825          ``True``.

   826 

   827 

   828    .. method:: set_subdir(subdir)

   829 

   830       Set the subdirectory the message should be stored in. Parameter *subdir*

   831       must be either "new" or "cur".

   832 

   833 

   834    .. method:: get_flags()

   835 

   836       Return a string specifying the flags that are currently set. If the

   837       message complies with the standard Maildir format, the result is the

   838       concatenation in alphabetical order of zero or one occurrence of each of

   839       ``'D'``, ``'F'``, ``'P'``, ``'R'``, ``'S'``, and ``'T'``. The empty string

   840       is returned if no flags are set or if "info" contains experimental

   841       semantics.

   842 

   843 

   844    .. method:: set_flags(flags)

   845 

   846       Set the flags specified by *flags* and unset all others.

   847 

   848 

   849    .. method:: add_flag(flag)

   850 

   851       Set the flag(s) specified by *flag* without changing other flags. To add

   852       more than one flag at a time, *flag* may be a string of more than one

   853       character. The current "info" is overwritten whether or not it contains

   854       experimental information rather than flags.

   855 

   856 

   857    .. method:: remove_flag(flag)

   858 

   859       Unset the flag(s) specified by *flag* without changing other flags. To

   860       remove more than one flag at a time, *flag* maybe a string of more than

   861       one character.  If "info" contains experimental information rather than

   862       flags, the current "info" is not modified.

   863 

   864 

   865    .. method:: get_date()

   866 

   867       Return the delivery date of the message as a floating-point number

   868       representing seconds since the epoch.

   869 

   870 

   871    .. method:: set_date(date)

   872 

   873       Set the delivery date of the message to *date*, a floating-point number

   874       representing seconds since the epoch.

   875 

   876 

   877    .. method:: get_info()

   878 

   879       Return a string containing the "info" for a message. This is useful for

   880       accessing and modifying "info" that is experimental (i.e., not a list of

   881       flags).

   882 

   883 

   884    .. method:: set_info(info)

   885 

   886       Set "info" to *info*, which should be a string.

   887 

   888 When a :class:`MaildirMessage` instance is created based upon an

   889 :class:`mboxMessage` or :class:`MMDFMessage` instance, the :mailheader:`Status`

   890 and :mailheader:`X-Status` headers are omitted and the following conversions

   891 take place:

   892 

   893 +--------------------+----------------------------------------------+

   894 | Resulting state    | :class:`mboxMessage` or :class:`MMDFMessage` |

   895 |                    | state                                        |

   896 +====================+==============================================+

   897 | "cur" subdirectory | O flag                                       |

   898 +--------------------+----------------------------------------------+

   899 | F flag             | F flag                                       |

   900 +--------------------+----------------------------------------------+

   901 | R flag             | A flag                                       |

   902 +--------------------+----------------------------------------------+

   903 | S flag             | R flag                                       |

   904 +--------------------+----------------------------------------------+

   905 | T flag             | D flag                                       |

   906 +--------------------+----------------------------------------------+

   907 

   908 When a :class:`MaildirMessage` instance is created based upon an

   909 :class:`MHMessage` instance, the following conversions take place:

   910 

   911 +-------------------------------+--------------------------+

   912 | Resulting state               | :class:`MHMessage` state |

   913 +===============================+==========================+

   914 | "cur" subdirectory            | "unseen" sequence        |

   915 +-------------------------------+--------------------------+

   916 | "cur" subdirectory and S flag | no "unseen" sequence     |

   917 +-------------------------------+--------------------------+

   918 | F flag                        | "flagged" sequence       |

   919 +-------------------------------+--------------------------+

   920 | R flag                        | "replied" sequence       |

   921 +-------------------------------+--------------------------+

   922 

   923 When a :class:`MaildirMessage` instance is created based upon a

   924 :class:`BabylMessage` instance, the following conversions take place:

   925 

   926 +-------------------------------+-------------------------------+

   927 | Resulting state               | :class:`BabylMessage` state   |

   928 +===============================+===============================+

   929 | "cur" subdirectory            | "unseen" label                |

   930 +-------------------------------+-------------------------------+

   931 | "cur" subdirectory and S flag | no "unseen" label             |

   932 +-------------------------------+-------------------------------+

   933 | P flag                        | "forwarded" or "resent" label |

   934 +-------------------------------+-------------------------------+

   935 | R flag                        | "answered" label              |

   936 +-------------------------------+-------------------------------+

   937 | T flag                        | "deleted" label               |

   938 +-------------------------------+-------------------------------+

   939 

   940 

   941 .. _mailbox-mboxmessage:

   942 

   943 :class:`mboxMessage`

   944 ^^^^^^^^^^^^^^^^^^^^

   945 

   946 

   947 .. class:: mboxMessage([message])

   948 

   949    A message with mbox-specific behaviors. Parameter *message* has the same meaning

   950    as with the :class:`Message` constructor.

   951 

   952    Messages in an mbox mailbox are stored together in a single file. The

   953    sender's envelope address and the time of delivery are typically stored in a

   954    line beginning with "From " that is used to indicate the start of a message,

   955    though there is considerable variation in the exact format of this data among

   956    mbox implementations. Flags that indicate the state of the message, such as

   957    whether it has been read or marked as important, are typically stored in

   958    :mailheader:`Status` and :mailheader:`X-Status` headers.

   959 

   960    Conventional flags for mbox messages are as follows:

   961 

   962    +------+----------+--------------------------------+

   963    | Flag | Meaning  | Explanation                    |

   964    +======+==========+================================+

   965    | R    | Read     | Read                           |

   966    +------+----------+--------------------------------+

   967    | O    | Old      | Previously detected by MUA     |

   968    +------+----------+--------------------------------+

   969    | D    | Deleted  | Marked for subsequent deletion |

   970    +------+----------+--------------------------------+

   971    | F    | Flagged  | Marked as important            |

   972    +------+----------+--------------------------------+

   973    | A    | Answered | Replied to                     |

   974    +------+----------+--------------------------------+

   975 

   976    The "R" and "O" flags are stored in the :mailheader:`Status` header, and the

   977    "D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The

   978    flags and headers typically appear in the order mentioned.

   979 

   980    :class:`mboxMessage` instances offer the following methods:

   981 

   982 

   983    .. method:: get_from()

   984 

   985       Return a string representing the "From " line that marks the start of the

   986       message in an mbox mailbox. The leading "From " and the trailing newline

   987       are excluded.

   988 

   989 

   990    .. method:: set_from(from_[, time_=None])

   991 

   992       Set the "From " line to *from_*, which should be specified without a

   993       leading "From " or trailing newline. For convenience, *time_* may be

   994       specified and will be formatted appropriately and appended to *from_*. If

   995       *time_* is specified, it should be a :class:`struct_time` instance, a

   996       tuple suitable for passing to :meth:`time.strftime`, or ``True`` (to use

   997       :meth:`time.gmtime`).

   998 

   999 

  1000    .. method:: get_flags()

  1001 

  1002       Return a string specifying the flags that are currently set. If the

  1003       message complies with the conventional format, the result is the

  1004       concatenation in the following order of zero or one occurrence of each of

  1005       ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.

  1006 

  1007 

  1008    .. method:: set_flags(flags)

  1009 

  1010       Set the flags specified by *flags* and unset all others. Parameter *flags*

  1011       should be the concatenation in any order of zero or more occurrences of

  1012       each of ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.

  1013 

  1014 

  1015    .. method:: add_flag(flag)

  1016 

  1017       Set the flag(s) specified by *flag* without changing other flags. To add

  1018       more than one flag at a time, *flag* may be a string of more than one

  1019       character.

  1020 

  1021 

  1022    .. method:: remove_flag(flag)

  1023 

  1024       Unset the flag(s) specified by *flag* without changing other flags. To

  1025       remove more than one flag at a time, *flag* maybe a string of more than

  1026       one character.

  1027 

  1028 When an :class:`mboxMessage` instance is created based upon a

  1029 :class:`MaildirMessage` instance, a "From " line is generated based upon the

  1030 :class:`MaildirMessage` instance's delivery date, and the following conversions

  1031 take place:

  1032 

  1033 +-----------------+-------------------------------+

  1034 | Resulting state | :class:`MaildirMessage` state |

  1035 +=================+===============================+

  1036 | R flag          | S flag                        |

  1037 +-----------------+-------------------------------+

  1038 | O flag          | "cur" subdirectory            |

  1039 +-----------------+-------------------------------+

  1040 | D flag          | T flag                        |

  1041 +-----------------+-------------------------------+

  1042 | F flag          | F flag                        |

  1043 +-----------------+-------------------------------+

  1044 | A flag          | R flag                        |

  1045 +-----------------+-------------------------------+

  1046 

  1047 When an :class:`mboxMessage` instance is created based upon an

  1048 :class:`MHMessage` instance, the following conversions take place:

  1049 

  1050 +-------------------+--------------------------+

  1051 | Resulting state   | :class:`MHMessage` state |

  1052 +===================+==========================+

  1053 | R flag and O flag | no "unseen" sequence     |

  1054 +-------------------+--------------------------+

  1055 | O flag            | "unseen" sequence        |

  1056 +-------------------+--------------------------+

  1057 | F flag            | "flagged" sequence       |

  1058 +-------------------+--------------------------+

  1059 | A flag            | "replied" sequence       |

  1060 +-------------------+--------------------------+

  1061 

  1062 When an :class:`mboxMessage` instance is created based upon a

  1063 :class:`BabylMessage` instance, the following conversions take place:

  1064 

  1065 +-------------------+-----------------------------+

  1066 | Resulting state   | :class:`BabylMessage` state |

  1067 +===================+=============================+

  1068 | R flag and O flag | no "unseen" label           |

  1069 +-------------------+-----------------------------+

  1070 | O flag            | "unseen" label              |

  1071 +-------------------+-----------------------------+

  1072 | D flag            | "deleted" label             |

  1073 +-------------------+-----------------------------+

  1074 | A flag            | "answered" label            |

  1075 +-------------------+-----------------------------+

  1076 

  1077 When a :class:`Message` instance is created based upon an :class:`MMDFMessage`

  1078 instance, the "From " line is copied and all flags directly correspond:

  1079 

  1080 +-----------------+----------------------------+

  1081 | Resulting state | :class:`MMDFMessage` state |

  1082 +=================+============================+

  1083 | R flag          | R flag                     |

  1084 +-----------------+----------------------------+

  1085 | O flag          | O flag                     |

  1086 +-----------------+----------------------------+

  1087 | D flag          | D flag                     |

  1088 +-----------------+----------------------------+

  1089 | F flag          | F flag                     |

  1090 +-----------------+----------------------------+

  1091 | A flag          | A flag                     |

  1092 +-----------------+----------------------------+

  1093 

  1094 

  1095 .. _mailbox-mhmessage:

  1096 

  1097 :class:`MHMessage`

  1098 ^^^^^^^^^^^^^^^^^^

  1099 

  1100 

  1101 .. class:: MHMessage([message])

  1102 

  1103    A message with MH-specific behaviors. Parameter *message* has the same meaning

  1104    as with the :class:`Message` constructor.

  1105 

  1106    MH messages do not support marks or flags in the traditional sense, but they

  1107    do support sequences, which are logical groupings of arbitrary messages. Some

  1108    mail reading programs (although not the standard :program:`mh` and

  1109    :program:`nmh`) use sequences in much the same way flags are used with other

  1110    formats, as follows:

  1111 

  1112    +----------+------------------------------------------+

  1113    | Sequence | Explanation                              |

  1114    +==========+==========================================+

  1115    | unseen   | Not read, but previously detected by MUA |

  1116    +----------+------------------------------------------+

  1117    | replied  | Replied to                               |

  1118    +----------+------------------------------------------+

  1119    | flagged  | Marked as important                      |

  1120    +----------+------------------------------------------+

  1121 

  1122    :class:`MHMessage` instances offer the following methods:

  1123 

  1124 

  1125    .. method:: get_sequences()

  1126 

  1127       Return a list of the names of sequences that include this message.

  1128 

  1129 

  1130    .. method:: set_sequences(sequences)

  1131 

  1132       Set the list of sequences that include this message.

  1133 

  1134 

  1135    .. method:: add_sequence(sequence)