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