/Doc/library/mailbox.rst
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