Lines Matching +full:- +full:- +full:message +full:- +full:format
1 :mod:`mailbox` --- Manipulate mailboxes in various formats
12 --------------
14 This module defines two classes, :class:`Mailbox` and :class:`Message`, for
15 accessing 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.
28 .. _mailbox-objects:
31 ------------------------
38 instantiated. Instead, format-specific subclasses should inherit from
41 The :class:`Mailbox` interface is dictionary-like, with small keys
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.
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
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
59 The default :class:`Mailbox` iterator iterates over message representations,
61 mailbox during iteration is safe and well-defined. Messages added to the
65 :exc:`KeyError` exception if the corresponding message is subsequently
71 changed by some other process. The safest mailbox format to use for such
72 tasks is Maildir; try to avoid using single-file formats such as mbox for
76 message. Failing to lock the mailbox runs the risk of losing messages or
82 .. method:: add(message)
84 Add *message* to the mailbox and return the key that has been assigned to
87 Parameter *message* may be a :class:`Message` instance, an
88 :class:`email.message.Message` instance, a string, a byte string, or a
89 file-like object (which should be open in binary mode). If *message* is
91 appropriate format-specific :class:`Message` subclass (e.g., if it's an
93 format-specific information is used. Otherwise, reasonable defaults for
94 format-specific information are used.
104 Delete the message corresponding to *key* from the mailbox.
106 If no such message exists, a :exc:`KeyError` exception is raised if the
110 format supports concurrent modification by other processes.
113 .. method:: __setitem__(key, message)
115 Replace the message corresponding to *key* with *message*. Raise a
116 :exc:`KeyError` exception if no message already corresponds to *key*.
118 As with :meth:`add`, parameter *message* may be a :class:`Message`
119 instance, an :class:`email.message.Message` instance, a string, a byte
120 string, or a file-like object (which should be open in binary mode). If
121 *message* is an
122 instance of the appropriate format-specific :class:`Message` subclass
124 :class:`mbox` instance), its format-specific information is
125 used. Otherwise, the format-specific information of the message that
143 as instances of the appropriate format-specific :class:`Message` subclass
144 unless a custom message factory was specified when the :class:`Mailbox`
156 Return an iterator over (*key*, *message*) pairs, where *key* is a key and
157 *message* is a message representation, if called as :meth:`iteritems` or
159 represented as instances of the appropriate format-specific
160 :class:`Message` subclass unless a custom message factory was specified
167 Return a representation of the message corresponding to *key*. If no such
168 message exists, *default* is returned if the method was called as
170 called as :meth:`__getitem__`. The message is represented as an instance
171 of the appropriate format-specific :class:`Message` subclass unless a
172 custom message factory was specified when the :class:`Mailbox` instance
178 Return a representation of the message corresponding to *key* as an
179 instance of the appropriate format-specific :class:`Message` subclass, or
180 raise a :exc:`KeyError` exception if no such message exists.
185 Return a byte representation of the message corresponding to *key*, or
186 raise a :exc:`KeyError` exception if no such message exists.
193 Return a string representation of the message corresponding to *key*, or
194 raise a :exc:`KeyError` exception if no such message exists. The
195 message is processed through :class:`email.message.Message` to
201 Return a file-like representation of the message corresponding to *key*,
202 or raise a :exc:`KeyError` exception if no such message exists. The
203 file-like object behaves as if open in binary mode. This file should be
208 returned in text mode. Also, the file-like object now supports the
214 Unlike other representations of messages, file-like representations are
222 Return ``True`` if *key* corresponds to a message, ``False`` otherwise.
237 Return a representation of the message corresponding to *key* and delete
238 the message. If no such message exists, return *default*. The message is
239 represented as an instance of the appropriate format-specific
240 :class:`Message` subclass unless a custom message factory was specified
246 Return an arbitrary (*key*, *message*) pair, where *key* is a key and
247 *message* is a message representation, and delete the corresponding
248 message. If the mailbox is empty, raise a :exc:`KeyError` exception. The
249 message is represented as an instance of the appropriate format-specific
250 :class:`Message` subclass unless a custom message factory was specified
256 Parameter *arg* should be a *key*-to-*message* mapping or an iterable of
257 (*key*, *message*) pairs. Updates the mailbox so that, for each given
258 *key* and *message*, the message corresponding to *key* is set to
259 *message* as if by using :meth:`__setitem__`. As with :meth:`__setitem__`,
260 each *key* must already correspond to a message in the mailbox or else a
281 mailbox format. You should *always* lock the mailbox before making any
296 .. _mailbox-maildir:
304 A subclass of :class:`Mailbox` for mailboxes in Maildir format. Parameter
305 *factory* is a callable object that accepts a file-like message representation
307 If *factory* is ``None``, :class:`MaildirMessage` is used as the default message
316 Maildir is a directory-based mailbox format invented for the qmail mail
326 finalize delivery. A mail user agent may subsequently move the message to the
327 :file:`cur` subdirectory and store information about the state of the message
340 message file names. However, some operating systems do not permit this
341 character in file names, If you wish to use a Maildir-like format on such
349 The :attr:`colon` attribute may also be set on a per-instance basis.
383 last 36 hours. The Maildir specification says that mail-reading programs
390 .. method:: add(message)
391 __setitem__(key, message)
424 remove the underlying message while the returned file remains open.
429 `maildir man page from Courier <https://www.courier-mta.org/maildir.html>`_
430 A specification of the format. Describes a common extension for
433 `Using maildir format <https://cr.yp.to/proto/maildir.html>`_
434 Notes on Maildir by its inventor. Includes an updated name-creation scheme and
438 .. _mailbox-mbox:
446 A subclass of :class:`Mailbox` for mailboxes in mbox format. Parameter *factory*
447 is a callable object that accepts a file-like message representation (which
449 *factory* is ``None``, :class:`mboxMessage` is used as the default message
453 The mbox format is the classic format for storing mail on Unix systems. All
455 each message indicated by a line whose first five characters are "From ".
457 Several variations of the mbox format exist to address perceived shortcomings in
459 original format, which is sometimes referred to as :dfn:`mboxo`. This means that
460 the :mailheader:`Content-Length` header, if present, is ignored and that any
461 occurrences of "From " at the beginning of a line in a message body are
462 transformed to ">From " when storing the message, although occurrences of ">From
463 " are not transformed to "From " when reading the message.
479 Three locking mechanisms are used---dot locking and, if available, the
486 A specification of the format, with details on locking.
488 …onfiguring Netscape Mail on Unix: Why The Content-Length Format is Bad <https://www.jwz.org/doc/co…
489 An argument for using the original mbox format rather than a variation.
495 .. _mailbox-mh:
503 A subclass of :class:`Mailbox` for mailboxes in MH format. Parameter *factory*
504 is a callable object that accepts a file-like message representation (which
506 *factory* is ``None``, :class:`MHMessage` is used as the default message
510 MH is a directory-based mailbox format invented for the MH Message Handling
511 System, a mail user agent. Each message in an MH mailbox resides in its own
515 messages without moving them to sub-folders. Sequences are defined in a file
560 Re-define the sequences that exist in the mailbox based upon *sequences*,
572 Already-issued keys are invalidated by this operation and should not be
583 These methods immediately delete the message. The MH convention of marking
584 a message for deletion by prepending a comma to its name is not used.
590 Three locking mechanisms are used---dot locking and, if available, the
593 duration of any operations that affect them, locking individual message
600 underlying message while the returned file remains open.
617 `nmh - Message Handling System <https://www.nongnu.org/nmh/>`_
620 `MH & nmh: Email for Users & Programmers <https://rand-mh.sourceforge.io/book/>`_
621 A GPL-licensed book on :program:`mh` and :program:`nmh`, with some information
622 on the mailbox format.
625 .. _mailbox-babyl:
633 A subclass of :class:`Mailbox` for mailboxes in Babyl format. Parameter
634 *factory* is a callable object that accepts a file-like message representation
636 If *factory* is ``None``, :class:`BabylMessage` is used as the default message
640 Babyl is a single-file mailbox format used by the Rmail mail user agent
641 included with Emacs. The beginning of a message is indicated by a line
642 containing the two characters Control-Underscore (``'\037'``) and Control-L
643 (``'\014'``). The end of a message is indicated by the start of the next
644 message or, in the case of the last message, a line containing a
645 Control-Underscore (``'\037'``) character.
648 so-called visible headers. Visible headers are typically a subset of the
650 attractive. Each message in a Babyl mailbox also has an accompanying list of
652 message, and a list of all user-defined labels found in the mailbox is kept
661 Return a list of the names of all user-defined labels used in the mailbox.
676 In Babyl mailboxes, the headers of a message are not stored contiguously
677 with the body of the message. To generate a file-like representation, the
680 file. As a result, the file-like object is truly independent of the
688 Three locking mechanisms are used---dot locking and, if available, the
694 `Format of Version 5 Babyl Files <https://quimby.gnus.org/notes/BABYL>`_
695 A specification of the Babyl format.
701 .. _mailbox-mmdf:
709 A subclass of :class:`Mailbox` for mailboxes in MMDF format. Parameter *factory*
710 is a callable object that accepts a file-like message representation (which
712 *factory* is ``None``, :class:`MMDFMessage` is used as the default message
716 MMDF is a single-file mailbox format invented for the Multichannel Memorandum
717 Distribution Facility, a mail transfer agent. Each message is in the same
718 form as an mbox message but is bracketed before and after by lines containing
719 four Control-A (``'\001'``) characters. As with the mbox format, the
720 beginning of each message is indicated by a line whose first five characters
722 ">From " when storing messages because the extra message separator lines
739 Three locking mechanisms are used---dot locking and, if available, the
746 A specification of MMDF format from the documentation of tin, a newsreader.
753 .. _mailbox-message-objects:
755 :class:`Message` objects
756 ------------------------
759 .. class:: Message(message=None)
761 A subclass of the :mod:`email.message` module's
762 :class:`~email.message.Message`. Subclasses of :class:`mailbox.Message` add
763 mailbox-format-specific state and behavior.
765 If *message* is omitted, the new instance is created in a default, empty state.
766 If *message* is an :class:`email.message.Message` instance, its contents are
767 copied; furthermore, any format-specific information is converted insofar as
768 possible if *message* is a :class:`Message` instance. If *message* is a string,
770 or a file, it should contain an :rfc:`2822`\ -compliant message, which is read
774 The format-specific state and behaviors offered by subclasses vary, but in
777 to a particular mailbox format). For example, file offsets for single-file
778 mailbox formats and file names for directory-based mailbox formats are not
780 such as whether a message has been read by the user or marked as important is
781 retained, because it applies to the message itself.
783 There is no requirement that :class:`Message` instances be used to represent
785 time and memory required to generate :class:`Message` representations might
787 offer string and file-like representations, and a custom message factory may
791 .. _mailbox-maildirmessage:
797 .. class:: MaildirMessage(message=None)
799 A message with Maildir-specific behaviors. Parameter *message* has the same
800 meaning as with the :class:`Message` constructor.
805 whether or not they've actually been read. Each message in :file:`cur` has an
810 contain "1," followed by so-called experimental information. Standard flags
813 +------+---------+--------------------------------+
817 +------+---------+--------------------------------+
819 +------+---------+--------------------------------+
821 +------+---------+--------------------------------+
823 +------+---------+--------------------------------+
825 +------+---------+--------------------------------+
827 +------+---------+--------------------------------+
834 Return either "new" (if the message should be stored in the :file:`new`
835 subdirectory) or "cur" (if the message should be stored in the :file:`cur`
840 A message is typically moved from :file:`new` to :file:`cur` after its
841 mailbox has been accessed, whether or not the message is has been
842 read. A message ``msg`` has been read if ``"S" in msg.get_flags()`` is
848 Set the subdirectory the message should be stored in. Parameter *subdir*
855 message complies with the standard Maildir format, the result is the
885 Return the delivery date of the message as a floating-point number
891 Set the delivery date of the message to *date*, a floating-point number
897 Return a string containing the "info" for a message. This is useful for
908 and :mailheader:`X-Status` headers are omitted and the following conversions
911 +--------------------+----------------------------------------------+
916 +--------------------+----------------------------------------------+
918 +--------------------+----------------------------------------------+
920 +--------------------+----------------------------------------------+
922 +--------------------+----------------------------------------------+
924 +--------------------+----------------------------------------------+
929 +-------------------------------+--------------------------+
933 +-------------------------------+--------------------------+
935 +-------------------------------+--------------------------+
937 +-------------------------------+--------------------------+
939 +-------------------------------+--------------------------+
944 +-------------------------------+-------------------------------+
948 +-------------------------------+-------------------------------+
950 +-------------------------------+-------------------------------+
952 +-------------------------------+-------------------------------+
954 +-------------------------------+-------------------------------+
956 +-------------------------------+-------------------------------+
959 .. _mailbox-mboxmessage:
965 .. class:: mboxMessage(message=None)
967 A message with mbox-specific behaviors. Parameter *message* has the same meaning
968 as with the :class:`Message` constructor.
972 line beginning with "From " that is used to indicate the start of a message,
973 though there is considerable variation in the exact format of this data among
974 mbox implementations. Flags that indicate the state of the message, such as
976 :mailheader:`Status` and :mailheader:`X-Status` headers.
980 +------+----------+--------------------------------+
984 +------+----------+--------------------------------+
986 +------+----------+--------------------------------+
988 +------+----------+--------------------------------+
990 +------+----------+--------------------------------+
992 +------+----------+--------------------------------+
995 "D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The
1004 message in an mbox mailbox. The leading "From " and the trailing newline
1021 message complies with the conventional format, the result is the
1051 +-----------------+-------------------------------+
1055 +-----------------+-------------------------------+
1057 +-----------------+-------------------------------+
1059 +-----------------+-------------------------------+
1061 +-----------------+-------------------------------+
1063 +-----------------+-------------------------------+
1068 +-------------------+--------------------------+
1072 +-------------------+--------------------------+
1074 +-------------------+--------------------------+
1076 +-------------------+--------------------------+
1078 +-------------------+--------------------------+
1083 +-------------------+-----------------------------+
1087 +-------------------+-----------------------------+
1089 +-------------------+-----------------------------+
1091 +-------------------+-----------------------------+
1093 +-------------------+-----------------------------+
1095 When a :class:`Message` instance is created based upon an :class:`MMDFMessage`
1098 +-----------------+----------------------------+
1102 +-----------------+----------------------------+
1104 +-----------------+----------------------------+
1106 +-----------------+----------------------------+
1108 +-----------------+----------------------------+
1110 +-----------------+----------------------------+
1113 .. _mailbox-mhmessage:
1119 .. class:: MHMessage(message=None)
1121 A message with MH-specific behaviors. Parameter *message* has the same meaning
1122 as with the :class:`Message` constructor.
1130 +----------+------------------------------------------+
1134 +----------+------------------------------------------+
1136 +----------+------------------------------------------+
1138 +----------+------------------------------------------+
1145 Return a list of the names of sequences that include this message.
1150 Set the list of sequences that include this message.
1155 Add *sequence* to the list of sequences that include this message.
1160 Remove *sequence* from the list of sequences that include this message.
1165 +--------------------+-------------------------------+
1169 +--------------------+-------------------------------+
1171 +--------------------+-------------------------------+
1173 +--------------------+-------------------------------+
1177 and :mailheader:`X-Status` headers are omitted and the following conversions
1180 +--------------------+----------------------------------------------+
1185 +--------------------+----------------------------------------------+
1187 +--------------------+----------------------------------------------+
1189 +--------------------+----------------------------------------------+
1194 +--------------------+-----------------------------+
1198 +--------------------+-----------------------------+
1200 +--------------------+-----------------------------+
1203 .. _mailbox-babylmessage:
1209 .. class:: BabylMessage(message=None)
1211 A message with Babyl-specific behaviors. Parameter *message* has the same
1212 meaning as with the :class:`Message` constructor.
1214 Certain message labels, called :dfn:`attributes`, are defined by convention
1217 +-----------+------------------------------------------+
1221 +-----------+------------------------------------------+
1223 +-----------+------------------------------------------+
1225 +-----------+------------------------------------------+
1227 +-----------+------------------------------------------+
1229 +-----------+------------------------------------------+
1231 +-----------+------------------------------------------+
1233 +-----------+------------------------------------------+
1244 Return a list of labels on the message.
1249 Set the list of labels on the message to *labels*.
1254 Add *label* to the list of labels on the message.
1259 Remove *label* from the list of labels on the message.
1264 Return an :class:`Message` instance whose headers are the message's
1270 Set the message's visible headers to be the same as the headers in
1271 *message*. Parameter *visible* should be a :class:`Message` instance, an
1272 :class:`email.message.Message` instance, a string, or a file-like object
1283 and any of :mailheader:`Date`, :mailheader:`From`, :mailheader:`Reply-To`,
1291 +-------------------+-------------------------------+
1295 +-------------------+-------------------------------+
1297 +-------------------+-------------------------------+
1299 +-------------------+-------------------------------+
1301 +-------------------+-------------------------------+
1305 and :mailheader:`X-Status` headers are omitted and the following conversions
1308 +------------------+----------------------------------------------+
1313 +------------------+----------------------------------------------+
1315 +------------------+----------------------------------------------+
1317 +------------------+----------------------------------------------+
1322 +------------------+--------------------------+
1326 +------------------+--------------------------+
1328 +------------------+--------------------------+
1331 .. _mailbox-mmdfmessage:
1337 .. class:: MMDFMessage(message=None)
1339 A message with MMDF-specific behaviors. Parameter *message* has the same meaning
1340 as with the :class:`Message` constructor.
1342 As with message in an mbox mailbox, MMDF messages are stored with the
1344 "From ". Likewise, flags that indicate the state of the message are
1345 typically stored in :mailheader:`Status` and :mailheader:`X-Status` headers.
1347 Conventional flags for MMDF messages are identical to those of mbox message
1350 +------+----------+--------------------------------+
1354 +------+----------+--------------------------------+
1356 +------+----------+--------------------------------+
1358 +------+----------+--------------------------------+
1360 +------+----------+--------------------------------+
1362 +------+----------+--------------------------------+
1365 "D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The
1375 message in an mbox mailbox. The leading "From " and the trailing newline
1392 message complies with the conventional format, the result is the
1422 +-----------------+-------------------------------+
1426 +-----------------+-------------------------------+
1428 +-----------------+-------------------------------+
1430 +-----------------+-------------------------------+
1432 +-----------------+-------------------------------+
1434 +-----------------+-------------------------------+
1439 +-------------------+--------------------------+
1443 +-------------------+--------------------------+
1445 +-------------------+--------------------------+
1447 +-------------------+--------------------------+
1449 +-------------------+--------------------------+
1454 +-------------------+-----------------------------+
1458 +-------------------+-----------------------------+
1460 +-------------------+-----------------------------+
1462 +-------------------+-----------------------------+
1464 +-------------------+-----------------------------+
1470 +-----------------+----------------------------+
1474 +-----------------+----------------------------+
1476 +-----------------+----------------------------+
1478 +-----------------+----------------------------+
1480 +-----------------+----------------------------+
1482 +-----------------+----------------------------+
1486 ----------
1493 The based class for all other module-specific exceptions.
1511 Raised when some mailbox-related condition beyond the control of the program
1523 .. _mailbox-examples:
1526 --------
1532 for message in mailbox.mbox('~/mbox'):
1533 subject = message['subject'] # Could possibly be None.
1538 format-specific information that can be converted::
1543 for message in mailbox.Babyl('~/RMAIL'):
1544 destination.add(mailbox.MHMessage(message))
1556 list_names = ('python-list', 'python-dev', 'python-bugs')
1563 message = inbox[key]
1565 continue # The message is malformed. Just leave it.
1568 list_id = message['list-id']
1574 # If there's a crash, you might duplicate a message, but
1575 # that's better than losing a message completely.
1577 box.add(message)
1581 # Remove original message