PageRenderTime 186ms CodeModel.GetById 81ms app.highlight 70ms RepoModel.GetById 20ms app.codeStats 1ms

/Doc/library/mailbox.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 1701 lines | 1177 code | 524 blank | 0 comment | 0 complexity | 513aba026b0f937dc68203f3b76f52f6 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   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 :class:`Message`
  15class with format-specific state and behavior. Supported mailbox formats are
  16Maildir, 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:: get_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
 888When a :class:`MaildirMessage` instance is created based upon an
 889:class:`mboxMessage` or :class:`MMDFMessage` instance, the :mailheader:`Status`
 890and :mailheader:`X-Status` headers are omitted and the following conversions
 891take 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
 908When 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
 923When 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
1028When 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
1031take 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
1047When 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
1062When 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
1077When a :class:`Message` instance is created based upon an :class:`MMDFMessage`
1078instance, 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)
1136
1137      Add *sequence* to the list of sequences that include this message.
1138
1139
1140   .. method:: remove_sequence(sequence)
1141
1142      Remove *sequence* from the list of sequences that include this message.
1143
1144When an :class:`MHMessage` instance is created based upon a
1145:class:`MaildirMessage` instance, the following conversions take place:
1146
1147+--------------------+-------------------------------+
1148| Resulting state    | :class:`MaildirMessage` state |
1149+====================+===============================+
1150| "unseen" sequence  | no S flag                     |
1151+--------------------+-------------------------------+
1152| "replied" sequence | R flag                        |
1153+--------------------+-------------------------------+
1154| "flagged" sequence | F flag                        |
1155+--------------------+-------------------------------+
1156
1157When an :class:`MHMessage` instance is created based upon an
1158:class:`mboxMessage` or :class:`MMDFMessage` instance, the :mailheader:`Status`
1159and :mailheader:`X-Status` headers are omitted and the following conversions
1160take place:
1161
1162+--------------------+----------------------------------------------+
1163| Resulting state    | :class:`mboxMessage` or :class:`MMDFMessage` |
1164|                    | state                                        |
1165+====================+==============================================+
1166| "unseen" sequence  | no R flag                                    |
1167+--------------------+----------------------------------------------+
1168| "replied" sequence | A flag                                       |
1169+--------------------+----------------------------------------------+
1170| "flagged" sequence | F flag                                       |
1171+--------------------+----------------------------------------------+
1172
1173When an :class:`MHMessage` instance is created based upon a
1174:class:`BabylMessage` instance, the following conversions take place:
1175
1176+--------------------+-----------------------------+
1177| Resulting state    | :class:`BabylMessage` state |
1178+====================+=============================+
1179| "unseen" sequence  | "unseen" label              |
1180+--------------------+-----------------------------+
1181| "replied" sequence | "answered" label            |
1182+--------------------+-----------------------------+
1183
1184
1185.. _mailbox-babylmessage:
1186
1187:class:`BabylMessage`
1188^^^^^^^^^^^^^^^^^^^^^
1189
1190
1191.. class:: BabylMessage([message])
1192
1193   A message with Babyl-specific behaviors. Parameter *message* has the same
1194   meaning as with the :class:`Message` constructor.
1195
1196   Certain message labels, called :dfn:`attributes`, are defined by convention
1197   to have special meanings. The attributes are as follows:
1198
1199   +-----------+------------------------------------------+
1200   | Label     | Explanation                              |
1201   +===========+==========================================+
1202   | unseen    | Not read, but previously detected by MUA |
1203   +-----------+------------------------------------------+
1204   | deleted   | Marked for subsequent deletion           |
1205   +-----------+------------------------------------------+
1206   | filed     | Copied to another file or mailbox        |
1207   +-----------+------------------------------------------+
1208   | answered  | Replied to                               |
1209   +-----------+------------------------------------------+
1210   | forwarded | Forwarded                                |
1211   +-----------+------------------------------------------+
1212   | edited    | Modified by the user                     |
1213   +-----------+------------------------------------------+
1214   | resent    | Resent                                   |
1215   +-----------+------------------------------------------+
1216
1217   By default, Rmail displays only visible headers. The :class:`BabylMessage`
1218   class, though, uses the original headers because they are more
1219   complete. Visible headers may be accessed explicitly if desired.
1220
1221   :class:`BabylMessage` instances offer the following methods:
1222
1223
1224   .. method:: get_labels()
1225
1226      Return a list of labels on the message.
1227
1228
1229   .. method:: set_labels(labels)
1230
1231      Set the list of labels on the message to *labels*.
1232
1233
1234   .. method:: add_label(label)
1235
1236      Add *label* to the list of labels on the message.
1237
1238
1239   .. method:: remove_label(label)
1240
1241      Remove *label* from the list of labels on the message.
1242
1243
1244   .. method:: get_visible()
1245
1246      Return an :class:`Message` instance whose headers are the message's
1247      visible headers and whose body is empty.
1248
1249
1250   .. method:: set_visible(visible)
1251
1252      Set the message's visible headers to be the same as the headers in
1253      *message*.  Parameter *visible* should be a :class:`Message` instance, an
1254      :class:`email.Message.Message` instance, a string, or a file-like object
1255      (which should be open in text mode).
1256
1257
1258   .. method:: update_visible()
1259
1260      When a :class:`BabylMessage` instance's original headers are modified, the
1261      visible headers are not automatically modified t…

Large files files are truncated, but you can click here to view the full file