rest25/library/mailbox.rst => rest262/library/mailbox.rst
27:class:`Mailbox` objects
28------------------------
29
30
31.. class:: Mailbox
32
33   A mailbox, which may be inspected and modified.
34
n35+   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+ 
35-The :class:`Mailbox` interface is dictionary-like, with small keys corresponding
39+   The :class:`Mailbox` interface is dictionary-like, with small keys
36-to messages. Keys are issued by the :class:`Mailbox` instance with which they
40+   corresponding to messages. Keys are issued by the :class:`Mailbox` instance
37-will be used and are only meaningful to that :class:`Mailbox` instance. A key
41+   with which they will be used and are only meaningful to that :class:`Mailbox`
38-continues to identify a message even if the corresponding message is modified,
42+   instance. A key continues to identify a message even if the corresponding
39-such as by replacing it with another message. Messages may be added to a
43+   message is modified, such as by replacing it with another message.
40-:class:`Mailbox` instance using the set-like method :meth:`add` and removed
41-using a ``del`` statement or the set-like methods :meth:`remove` and
42-:meth:`discard`.
43
n45+   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+ 
44-:class:`Mailbox` interface semantics differ from dictionary semantics in some
49+   :class:`Mailbox` interface semantics differ from dictionary semantics in some
45-noteworthy ways. Each time a message is requested, a new representation
50+   noteworthy ways. Each time a message is requested, a new representation
46-(typically a :class:`Message` instance) is generated, based upon the current
51+   (typically a :class:`Message` instance) is generated based upon the current
47-state of the mailbox. Similarly, when a message is added to a :class:`Mailbox`
52+   state of the mailbox. Similarly, when a message is added to a
48-instance, the provided message representation's contents are copied. In neither
53+   :class:`Mailbox` instance, the provided message representation's contents are
49-case is a reference to the message representation kept by the :class:`Mailbox`
54+   copied. In neither case is a reference to the message representation kept by
50-instance.
55+   the :class:`Mailbox` instance.
51
n52-The default :class:`Mailbox` iterator iterates over message representations, not
n57+   The default :class:`Mailbox` iterator iterates over message representations,
53-keys as the default dictionary iterator does. Moreover, modification of a
58+   not keys as the default dictionary iterator does. Moreover, modification of a
54-mailbox during iteration is safe and well-defined. Messages added to the mailbox
59+   mailbox during iteration is safe and well-defined. Messages added to the
55-after an iterator is created will not be seen by the iterator. Messages removed
60+   mailbox after an iterator is created will not be seen by the
56-from the mailbox before the iterator yields them will be silently skipped,
61+   iterator. Messages removed from the mailbox before the iterator yields them
57-though using a key from an iterator may result in a :exc:`KeyError` exception if
62+   will be silently skipped, though using a key from an iterator may result in a
58-the corresponding message is subsequently removed.
63+   :exc:`KeyError` exception if the corresponding message is subsequently
64+   removed.
59
n60-:class:`Mailbox` itself is intended to define an interface and to be inherited
n66+   .. warning::
61-from by format-specific subclasses but is not intended to be instantiated.
62-Instead, you should instantiate a subclass.
63
n68+      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+ 
64-:class:`Mailbox` instances have the following methods:
77+   :class:`Mailbox` instances have the following methods:
65
66
n67-.. method:: Mailbox.add(message)
n80+   .. method:: add(message)
68
n69-   Add *message* to the mailbox and return the key that has been assigned to it.
n82+      Add *message* to the mailbox and return the key that has been assigned to
83+      it.
70
n71-   Parameter *message* may be a :class:`Message` instance, an
n85+      Parameter *message* may be a :class:`Message` instance, an
72-   :class:`email.Message.Message` instance, a string, or a file-like object (which
86+      :class:`email.Message.Message` instance, a string, or a file-like object
73-   should be open in text mode). If *message* is an instance of the appropriate
87+      (which should be open in text mode). If *message* is an instance of the
74-   format-specific :class:`Message` subclass (e.g., if it's an :class:`mboxMessage`
88+      appropriate format-specific :class:`Message` subclass (e.g., if it's an
75-   instance and this is an :class:`mbox` instance), its format-specific information
89+      :class:`mboxMessage` instance and this is an :class:`mbox` instance), its
76-   is used. Otherwise, reasonable defaults for format-specific information are
90+      format-specific information is used. Otherwise, reasonable defaults for
77-   used.
91+      format-specific information are used.
78
79
n80-.. method:: Mailbox.remove(key)
n94+   .. method:: remove(key)
81-            Mailbox.__delitem__(key)
95+               __delitem__(key)
82-            Mailbox.discard(key)
96+               discard(key)
83
n84-   Delete the message corresponding to *key* from the mailbox.
n98+      Delete the message corresponding to *key* from the mailbox.
85
n86-   If no such message exists, a :exc:`KeyError` exception is raised if the method
n100+      If no such message exists, a :exc:`KeyError` exception is raised if the
87-   was called as :meth:`remove` or :meth:`__delitem__` but no exception is raised
101+      method was called as :meth:`remove` or :meth:`__delitem__` but no
88-   if the method was called as :meth:`discard`. The behavior of :meth:`discard` may
102+      exception is raised if the method was called as :meth:`discard`. The
89-   be preferred if the underlying mailbox format supports concurrent modification
103+      behavior of :meth:`discard` may be preferred if the underlying mailbox
90-   by other processes.
104+      format supports concurrent modification by other processes.
91
92
n93-.. method:: Mailbox.__setitem__(key, message)
n107+   .. method:: __setitem__(key, message)
94
n95-   Replace the message corresponding to *key* with *message*. Raise a
n109+      Replace the message corresponding to *key* with *message*. Raise a
96-   :exc:`KeyError` exception if no message already corresponds to *key*.
110+      :exc:`KeyError` exception if no message already corresponds to *key*.
97
n98-   As with :meth:`add`, parameter *message* may be a :class:`Message` instance, an
n112+      As with :meth:`add`, parameter *message* may be a :class:`Message`
99-   :class:`email.Message.Message` instance, a string, or a file-like object (which
113+      instance, an :class:`email.Message.Message` instance, a string, or a
100-   should be open in text mode). If *message* is an instance of the appropriate
114+      file-like object (which should be open in text mode). If *message* is an
101-   format-specific :class:`Message` subclass (e.g., if it's an :class:`mboxMessage`
115+      instance of the appropriate format-specific :class:`Message` subclass
116+      (e.g., if it's an :class:`mboxMessage` instance and this is an
102-   instance and this is an :class:`mbox` instance), its format-specific information
117+      :class:`mbox` instance), its format-specific information is
103-   is used. Otherwise, the format-specific information of the message that
118+      used. Otherwise, the format-specific information of the message that
104-   currently corresponds to *key* is left unchanged.
119+      currently corresponds to *key* is left unchanged.
105
106
n107-.. method:: Mailbox.iterkeys()
n122+   .. method:: iterkeys()
108-            Mailbox.keys()
123+               keys()
109
n110-   Return an iterator over all keys if called as :meth:`iterkeys` or return a list
n125+      Return an iterator over all keys if called as :meth:`iterkeys` or return a
111-   of keys if called as :meth:`keys`.
126+      list of keys if called as :meth:`keys`.
112
113
n114-.. method:: Mailbox.itervalues()
n129+   .. method:: itervalues()
115-            Mailbox.__iter__()
130+               __iter__()
116-            Mailbox.values()
131+               values()
117
n118-   Return an iterator over representations of all messages if called as
n133+      Return an iterator over representations of all messages if called as
119-   :meth:`itervalues` or :meth:`__iter__` or return a list of such representations
134+      :meth:`itervalues` or :meth:`__iter__` or return a list of such
120-   if called as :meth:`values`. The messages are represented as instances of the
135+      representations if called as :meth:`values`. The messages are represented
121-   appropriate format-specific :class:`Message` subclass unless a custom message
136+      as instances of the appropriate format-specific :class:`Message` subclass
122-   factory was specified when the :class:`Mailbox` instance was initialized.
137+      unless a custom message factory was specified when the :class:`Mailbox`
138+      instance was initialized.
123
n124-   .. note::
n140+      .. note::
125
n126-      The behavior of :meth:`__iter__` is unlike that of dictionaries, which iterate
n142+         The behavior of :meth:`__iter__` is unlike that of dictionaries, which
127-      over keys.
143+         iterate over keys.
128
129
n130-.. method:: Mailbox.iteritems()
n146+   .. method:: iteritems()
131-            Mailbox.items()
147+               items()
132
n133-   Return an iterator over (*key*, *message*) pairs, where *key* is a key and
n149+      Return an iterator over (*key*, *message*) pairs, where *key* is a key and
134-   *message* is a message representation, if called as :meth:`iteritems` or return
150+      *message* is a message representation, if called as :meth:`iteritems` or
135-   a list of such pairs if called as :meth:`items`. The messages are represented as
151+      return a list of such pairs if called as :meth:`items`. The messages are
136-   instances of the appropriate format-specific :class:`Message` subclass unless a
152+      represented as instances of the appropriate format-specific
137-   custom message factory was specified when the :class:`Mailbox` instance was
153+      :class:`Message` subclass unless a custom message factory was specified
138-   initialized.
154+      when the :class:`Mailbox` instance was initialized.
139
140
n141-.. method:: Mailbox.get(key[, default=None])
n157+   .. method:: get(key[, default=None])
142-            Mailbox.__getitem__(key)
158+               __getitem__(key)
143
n144-   Return a representation of the message corresponding to *key*. If no such
n160+      Return a representation of the message corresponding to *key*. If no such
145-   message exists, *default* is returned if the method was called as :meth:`get`
161+      message exists, *default* is returned if the method was called as
146-   and a :exc:`KeyError` exception is raised if the method was called as
162+      :meth:`get` and a :exc:`KeyError` exception is raised if the method was
147-   :meth:`__getitem__`. The message is represented as an instance of the
163+      called as :meth:`__getitem__`. The message is represented as an instance
148-   appropriate format-specific :class:`Message` subclass unless a custom message
164+      of the appropriate format-specific :class:`Message` subclass unless a
149-   factory was specified when the :class:`Mailbox` instance was initialized.
165+      custom message factory was specified when the :class:`Mailbox` instance
166+      was initialized.
150
151
n152-.. method:: Mailbox.get_message(key)
n169+   .. method:: get_message(key)
153
n154-   Return a representation of the message corresponding to *key* as an instance of
n171+      Return a representation of the message corresponding to *key* as an
155-   the appropriate format-specific :class:`Message` subclass, or raise a
172+      instance of the appropriate format-specific :class:`Message` subclass, or
156-   :exc:`KeyError` exception if no such message exists.
173+      raise a :exc:`KeyError` exception if no such message exists.
157
158
n159-.. method:: Mailbox.get_string(key)
n176+   .. method:: get_string(key)
160
n161-   Return a string representation of the message corresponding to *key*, or raise a
n178+      Return a string representation of the message corresponding to *key*, or
162-   :exc:`KeyError` exception if no such message exists.
179+      raise a :exc:`KeyError` exception if no such message exists.
163
164
n165-.. method:: Mailbox.get_file(key)
n182+   .. method:: get_file(key)
166
n167-   Return a file-like representation of the message corresponding to *key*, or
n184+      Return a file-like representation of the message corresponding to *key*,
168-   raise a :exc:`KeyError` exception if no such message exists. The file-like
185+      or raise a :exc:`KeyError` exception if no such message exists. The
169-   object behaves as if open in binary mode. This file should be closed once it is
186+      file-like object behaves as if open in binary mode. This file should be
170-   no longer needed.
187+      closed once it is no longer needed.
171
n172-   .. note::
n189+      .. note::
173
n174-      Unlike other representations of messages, file-like representations are not
n191+         Unlike other representations of messages, file-like representations are
175-      necessarily independent of the :class:`Mailbox` instance that created them or of
192+         not necessarily independent of the :class:`Mailbox` instance that
176-      the underlying mailbox. More specific documentation is provided by each
193+         created them or of the underlying mailbox. More specific documentation
177-      subclass.
194+         is provided by each subclass.
178
179
n180-.. method:: Mailbox.has_key(key)
n197+   .. method:: has_key(key)
181-            Mailbox.__contains__(key)
198+               __contains__(key)
182
n183-   Return ``True`` if *key* corresponds to a message, ``False`` otherwise.
n200+      Return ``True`` if *key* corresponds to a message, ``False`` otherwise.
184
185
n186-.. method:: Mailbox.__len__()
n203+   .. method:: __len__()
187
n188-   Return a count of messages in the mailbox.
n205+      Return a count of messages in the mailbox.
189
190
n191-.. method:: Mailbox.clear()
n208+   .. method:: clear()
192
n193-   Delete all messages from the mailbox.
n210+      Delete all messages from the mailbox.
194
195
n196-.. method:: Mailbox.pop(key[, default])
n213+   .. method:: pop(key[, default])
197
n198-   Return a representation of the message corresponding to *key* and delete the
n215+      Return a representation of the message corresponding to *key* and delete
199-   message. If no such message exists, return *default* if it was supplied or else
216+      the message. If no such message exists, return *default* if it was
200-   raise a :exc:`KeyError` exception. The message is represented as an instance of
217+      supplied or else raise a :exc:`KeyError` exception. The message is
201-   the appropriate format-specific :class:`Message` subclass unless a custom
218+      represented as an instance of the appropriate format-specific
202-   message factory was specified when the :class:`Mailbox` instance was
219+      :class:`Message` subclass unless a custom message factory was specified
203-   initialized.
220+      when the :class:`Mailbox` instance was initialized.
204
205
n206-.. method:: Mailbox.popitem()
n223+   .. method:: popitem()
207
n208-   Return an arbitrary (*key*, *message*) pair, where *key* is a key and *message*
n225+      Return an arbitrary (*key*, *message*) pair, where *key* is a key and
209-   is a message representation, and delete the corresponding message. If the
226+      *message* is a message representation, and delete the corresponding
210-   mailbox is empty, raise a :exc:`KeyError` exception. The message is represented
227+      message. If the mailbox is empty, raise a :exc:`KeyError` exception. The
211-   as an instance of the appropriate format-specific :class:`Message` subclass
228+      message is represented as an instance of the appropriate format-specific
212-   unless a custom message factory was specified when the :class:`Mailbox` instance
229+      :class:`Message` subclass unless a custom message factory was specified
213-   was initialized.
230+      when the :class:`Mailbox` instance was initialized.
214
215
n216-.. method:: Mailbox.update(arg)
n233+   .. method:: update(arg)
217
n218-   Parameter *arg* should be a *key*-to-*message* mapping or an iterable of (*key*,
n235+      Parameter *arg* should be a *key*-to-*message* mapping or an iterable of
219-   *message*) pairs. Updates the mailbox so that, for each given *key* and
236+      (*key*, *message*) pairs. Updates the mailbox so that, for each given
220-   *message*, the message corresponding to *key* is set to *message* as if by using
237+      *key* and *message*, the message corresponding to *key* is set to
221-   :meth:`__setitem__`. As with :meth:`__setitem__`, each *key* must already
238+      *message* as if by using :meth:`__setitem__`. As with :meth:`__setitem__`,
222-   correspond to a message in the mailbox or else a :exc:`KeyError` exception will
239+      each *key* must already correspond to a message in the mailbox or else a
223-   be raised, so in general it is incorrect for *arg* to be a :class:`Mailbox`
240+      :exc:`KeyError` exception will be raised, so in general it is incorrect
224-   instance.
241+      for *arg* to be a :class:`Mailbox` instance.
225
n226-   .. note::
n243+      .. note::
227
n228-      Unlike with dictionaries, keyword arguments are not supported.
n245+         Unlike with dictionaries, keyword arguments are not supported.
229
230
n231-.. method:: Mailbox.flush()
n248+   .. method:: flush()
232
n233-   Write any pending changes to the filesystem. For some :class:`Mailbox`
n250+      Write any pending changes to the filesystem. For some :class:`Mailbox`
234-   subclasses, changes are always written immediately and this method does nothing.
251+      subclasses, changes are always written immediately and :meth:`flush` does
252+      nothing, but you should still make a habit of calling this method.
235
236
n237-.. method:: Mailbox.lock()
n255+   .. method:: lock()
238
n239-   Acquire an exclusive advisory lock on the mailbox so that other processes know
n257+      Acquire an exclusive advisory lock on the mailbox so that other processes
240-   not to modify it. An :exc:`ExternalClashError` is raised if the lock is not
258+      know not to modify it. An :exc:`ExternalClashError` is raised if the lock
241-   available. The particular locking mechanisms used depend upon the mailbox
259+      is not available. The particular locking mechanisms used depend upon the
242-   format.
260+      mailbox format.  You should *always* lock the mailbox before making any
261+      modifications to its contents.
243
244
n245-.. method:: Mailbox.unlock()
n264+   .. method:: unlock()
246
n247-   Release the lock on the mailbox, if any.
n266+      Release the lock on the mailbox, if any.
248
249
n250-.. method:: Mailbox.close()
n269+   .. method:: close()
251
n252-   Flush the mailbox, unlock it if necessary, and close any open files. For some
n271+      Flush the mailbox, unlock it if necessary, and close any open files. For
253-   :class:`Mailbox` subclasses, this method does nothing.
272+      some :class:`Mailbox` subclasses, this method does nothing.
254
255
256.. _mailbox-maildir:
257
258:class:`Maildir`
259^^^^^^^^^^^^^^^^
260
261
268   representation. If *create* is ``True``, the mailbox is created if it does not
269   exist.
270
271   It is for historical reasons that *factory* defaults to :class:`rfc822.Message`
272   and that *dirname* is named as such rather than *path*. For a :class:`Maildir`
273   instance that behaves like instances of other :class:`Mailbox` subclasses, set
274   *factory* to ``None``.
275
n276-Maildir is a directory-based mailbox format invented for the qmail mail transfer
n295+   Maildir is a directory-based mailbox format invented for the qmail mail
277-agent and now widely supported by other programs. Messages in a Maildir mailbox
296+   transfer agent and now widely supported by other programs. Messages in a
278-are stored in separate files within a common directory structure. This design
297+   Maildir mailbox are stored in separate files within a common directory
279-allows Maildir mailboxes to be accessed and modified by multiple unrelated
298+   structure. This design allows Maildir mailboxes to be accessed and modified
280-programs without data corruption, so file locking is unnecessary.
299+   by multiple unrelated programs without data corruption, so file locking is
300+   unnecessary.
281
n282-Maildir mailboxes contain three subdirectories, namely: :file:`tmp`,
n302+   Maildir mailboxes contain three subdirectories, namely: :file:`tmp`,
283-:file:`new`, and :file:`cur`. Messages are created momentarily in the
303+   :file:`new`, and :file:`cur`. Messages are created momentarily in the
284-:file:`tmp` subdirectory and then moved to the :file:`new` subdirectory to
304+   :file:`tmp` subdirectory and then moved to the :file:`new` subdirectory to
285-finalize delivery. A mail user agent may subsequently move the message to the
305+   finalize delivery. A mail user agent may subsequently move the message to the
286-:file:`cur` subdirectory and store information about the state of the message in
306+   :file:`cur` subdirectory and store information about the state of the message
287-a special "info" section appended to its file name.
307+   in a special "info" section appended to its file name.
288
n289-Folders of the style introduced by the Courier mail transfer agent are also
n309+   Folders of the style introduced by the Courier mail transfer agent are also
290-supported. Any subdirectory of the main mailbox is considered a folder if
310+   supported. Any subdirectory of the main mailbox is considered a folder if
291-``'.'`` is the first character in its name. Folder names are represented by
311+   ``'.'`` is the first character in its name. Folder names are represented by
292-:class:`Maildir` without the leading ``'.'``. Each folder is itself a Maildir
312+   :class:`Maildir` without the leading ``'.'``. Each folder is itself a Maildir
293-mailbox but should not contain other folders. Instead, a logical nesting is
313+   mailbox but should not contain other folders. Instead, a logical nesting is
294-indicated using ``'.'`` to delimit levels, e.g., "Archived.2005.07".
314+   indicated using ``'.'`` to delimit levels, e.g., "Archived.2005.07".
295
n296-.. note::
n316+   .. note::
297
n298-   The Maildir specification requires the use of a colon (``':'``) in certain
n318+      The Maildir specification requires the use of a colon (``':'``) in certain
299-   message file names. However, some operating systems do not permit this character
319+      message file names. However, some operating systems do not permit this
300-   in file names, If you wish to use a Maildir-like format on such an operating
320+      character in file names, If you wish to use a Maildir-like format on such
301-   system, you should specify another character to use instead. The exclamation
321+      an operating system, you should specify another character to use
302-   point (``'!'``) is a popular choice. For example::
322+      instead. The exclamation point (``'!'``) is a popular choice. For
323+      example::
303
n304-      import mailbox
n325+         import mailbox
305-      mailbox.Maildir.colon = '!'
326+         mailbox.Maildir.colon = '!'
306
n307-   The :attr:`colon` attribute may also be set on a per-instance basis.
n328+      The :attr:`colon` attribute may also be set on a per-instance basis.
308
n309-:class:`Maildir` instances have all of the methods of :class:`Mailbox` in
n330+   :class:`Maildir` instances have all of the methods of :class:`Mailbox` in
310-addition to the following:
331+   addition to the following:
311
312
n313-.. method:: Maildir.list_folders()
n334+   .. method:: list_folders()
314
n315-   Return a list of the names of all folders.
n336+      Return a list of the names of all folders.
316
317
n318-.. method:: Maildir.get_folder(folder)
n339+   .. method:: .et_folder(folder)
319
n320-   Return a :class:`Maildir` instance representing the folder whose name is
n341+      Return a :class:`Maildir` instance representing the folder whose name is
321-   *folder*. A :exc:`NoSuchMailboxError` exception is raised if the folder does not
342+      *folder*. A :exc:`NoSuchMailboxError` exception is raised if the folder
322-   exist.
343+      does not exist.
323
324
n325-.. method:: Maildir.add_folder(folder)
n346+   .. method:: add_folder(folder)
326
n327-   Create a folder whose name is *folder* and return a :class:`Maildir` instance
n348+      Create a folder whose name is *folder* and return a :class:`Maildir`
328-   representing it.
349+      instance representing it.
329
330
n331-.. method:: Maildir.remove_folder(folder)
n352+   .. method:: remove_folder(folder)
332
n333-   Delete the folder whose name is *folder*. If the folder contains any messages, a
n354+      Delete the folder whose name is *folder*. If the folder contains any
334-   :exc:`NotEmptyError` exception will be raised and the folder will not be
355+      messages, a :exc:`NotEmptyError` exception will be raised and the folder
335-   deleted.
356+      will not be deleted.
336
337
n338-.. method:: Maildir.clean()
n359+   .. method:: clean()
339
n340-   Delete temporary files from the mailbox that have not been accessed in the last
n361+      Delete temporary files from the mailbox that have not been accessed in the
341-   36 hours. The Maildir specification says that mail-reading programs should do
362+      last 36 hours. The Maildir specification says that mail-reading programs
342-   this occasionally.
363+      should do this occasionally.
343
n344-Some :class:`Mailbox` methods implemented by :class:`Maildir` deserve special
n365+   Some :class:`Mailbox` methods implemented by :class:`Maildir` deserve special
345-remarks:
366+   remarks:
346
347
n348-.. method:: Maildir.add(message)
n369+   .. method:: add(message)
349-            Maildir.__setitem__(key, message)
370+               __setitem__(key, message)
350-            Maildir.update(arg)
371+               update(arg)
351
n352-   .. warning::
n373+      .. warning::
353
n354-      These methods generate unique file names based upon the current process ID. When
n375+         These methods generate unique file names based upon the current process
355-      using multiple threads, undetected name clashes may occur and cause corruption
376+         ID. When using multiple threads, undetected name clashes may occur and
356-      of the mailbox unless threads are coordinated to avoid using these methods to
377+         cause corruption of the mailbox unless threads are coordinated to avoid
357-      manipulate the same mailbox simultaneously.
378+         using these methods to manipulate the same mailbox simultaneously.
358
359
n360-.. method:: Maildir.flush()
n381+   .. method:: flush()
361
n362-   All changes to Maildir mailboxes are immediately applied, so this method does
n383+      All changes to Maildir mailboxes are immediately applied, so this method
363-   nothing.
384+      does nothing.
364
365
n366-.. method:: Maildir.lock()
n387+   .. method:: lock()
367-            Maildir.unlock()
388+               unlock()
368
n369-   Maildir mailboxes do not support (or require) locking, so these methods do
n390+      Maildir mailboxes do not support (or require) locking, so these methods do
370-   nothing.
391+      nothing.
371
372
n373-.. method:: Maildir.close()
n394+   .. method:: close()
374
n375-   :class:`Maildir` instances do not keep any open files and the underlying
n396+      :class:`Maildir` instances do not keep any open files and the underlying
376-   mailboxes do not support locking, so this method does nothing.
397+      mailboxes do not support locking, so this method does nothing.
377
378
n379-.. method:: Maildir.get_file(key)
n400+   .. method:: get_file(key)
380
n381-   Depending upon the host platform, it may not be possible to modify or remove the
n402+      Depending upon the host platform, it may not be possible to modify or
382-   underlying message while the returned file remains open.
403+      remove the underlying message while the returned file remains open.
383
384
385.. seealso::
386
387   `maildir man page from qmail <http://www.qmail.org/man/man5/maildir.html>`_
388      The original specification of the format.
389
390   `Using maildir format <http://cr.yp.to/proto/maildir.html>`_
391      Notes on Maildir by its inventor. Includes an updated name-creation scheme and
392      details on "info" semantics.
393
n394-   `maildir man page from Courier <http://www.courier-mta.org/?maildir.html>`_
n415+   `maildir man page from Courier <http://www.courier-mta.org/maildir.html>`_
395      Another specification of the format. Describes a common extension for supporting
396      folders.
397
398
399.. _mailbox-mbox:
400
401:class:`mbox`
402^^^^^^^^^^^^^
406
407   A subclass of :class:`Mailbox` for mailboxes in mbox format. Parameter *factory*
408   is a callable object that accepts a file-like message representation (which
409   behaves as if opened in binary mode) and returns a custom representation. If
410   *factory* is ``None``, :class:`mboxMessage` is used as the default message
411   representation. If *create* is ``True``, the mailbox is created if it does not
412   exist.
413
n414-The mbox format is the classic format for storing mail on Unix systems. All
n435+   The mbox format is the classic format for storing mail on Unix systems. All
415-messages in an mbox mailbox are stored in a single file with the beginning of
436+   messages in an mbox mailbox are stored in a single file with the beginning of
416-each message indicated by a line whose first five characters are "From ".
437+   each message indicated by a line whose first five characters are "From ".
417
n418-Several variations of the mbox format exist to address perceived shortcomings in
n439+   Several variations of the mbox format exist to address perceived shortcomings in
419-the original. In the interest of compatibility, :class:`mbox` implements the
440+   the original. In the interest of compatibility, :class:`mbox` implements the
420-original format, which is sometimes referred to as :dfn:`mboxo`. This means that
441+   original format, which is sometimes referred to as :dfn:`mboxo`. This means that
421-the :mailheader:`Content-Length` header, if present, is ignored and that any
442+   the :mailheader:`Content-Length` header, if present, is ignored and that any
422-occurrences of "From " at the beginning of a line in a message body are
443+   occurrences of "From " at the beginning of a line in a message body are
423-transformed to ">From " when storing the message, although occurences of ">From
444+   transformed to ">From " when storing the message, although occurrences of ">From
424-" are not transformed to "From " when reading the message.
445+   " are not transformed to "From " when reading the message.
425
n426-Some :class:`Mailbox` methods implemented by :class:`mbox` deserve special
n447+   Some :class:`Mailbox` methods implemented by :class:`mbox` deserve special
427-remarks:
448+   remarks:
428
429
n430-.. method:: mbox.get_file(key)
n451+   .. method:: get_file(key)
431
n432-   Using the file after calling :meth:`flush` or :meth:`close` on the :class:`mbox`
n453+      Using the file after calling :meth:`flush` or :meth:`close` on the
433-   instance may yield unpredictable results or raise an exception.
454+      :class:`mbox` instance may yield unpredictable results or raise an
455+      exception.
434
435
n436-.. method:: mbox.lock()
n458+   .. method:: lock()
437-            mbox.unlock()
459+               unlock()
438
n439-   Three locking mechanisms are used---dot locking and, if available, the
n461+      Three locking mechanisms are used---dot locking and, if available, the
440-   :cfunc:`flock` and :cfunc:`lockf` system calls.
462+      :cfunc:`flock` and :cfunc:`lockf` system calls.
441
442
443.. seealso::
444
445   `mbox man page from qmail <http://www.qmail.org/man/man5/mbox.html>`_
446      A specification of the format and its variations.
447
448   `mbox man page from tin <http://www.tin.org/bin/man.cgi?section=5&topic=mbox>`_
449      Another specification of the format, with details on locking.
450
n451-   `Configuring Netscape Mail on Unix: Why The Content-Length Format is Bad <http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html>`_
n473+   `Configuring Netscape Mail on Unix: Why The Content-Length Format is Bad <http://www.jwz.org/doc/content-length.html>`_
452      An argument for using the original mbox format rather than a variation.
453
454   `"mbox" is a family of several mutually incompatible mailbox formats <http://homepages.tesco.net./~J.deBoynePollard/FGA/mail-mbox-formats.html>`_
455      A history of mbox variations.
456
457
458.. _mailbox-mh:
459
465
466   A subclass of :class:`Mailbox` for mailboxes in MH format. Parameter *factory*
467   is a callable object that accepts a file-like message representation (which
468   behaves as if opened in binary mode) and returns a custom representation. If
469   *factory* is ``None``, :class:`MHMessage` is used as the default message
470   representation. If *create* is ``True``, the mailbox is created if it does not
471   exist.
472
n473-MH is a directory-based mailbox format invented for the MH Message Handling
n495+   MH is a directory-based mailbox format invented for the MH Message Handling
474-System, a mail user agent. Each message in an MH mailbox resides in its own
496+   System, a mail user agent. Each message in an MH mailbox resides in its own
475-file. An MH mailbox may contain other MH mailboxes (called :dfn:`folders`) in
497+   file. An MH mailbox may contain other MH mailboxes (called :dfn:`folders`) in
476-addition to messages. Folders may be nested indefinitely. MH mailboxes also
498+   addition to messages. Folders may be nested indefinitely. MH mailboxes also
477-support :dfn:`sequences`, which are named lists used to logically group messages
499+   support :dfn:`sequences`, which are named lists used to logically group
478-without moving them to sub-folders. Sequences are defined in a file called
500+   messages without moving them to sub-folders. Sequences are defined in a file
479-:file:`.mh_sequences` in each folder.
501+   called :file:`.mh_sequences` in each folder.
480
n481-The :class:`MH` class manipulates MH mailboxes, but it does not attempt to
n503+   The :class:`MH` class manipulates MH mailboxes, but it does not attempt to
482-emulate all of :program:`mh`'s behaviors. In particular, it does not modify and
504+   emulate all of :program:`mh`'s behaviors. In particular, it does not modify
483-is not affected by the :file:`context` or :file:`.mh_profile` files that are
505+   and is not affected by the :file:`context` or :file:`.mh_profile` files that
484-used by :program:`mh` to store its state and configuration.
506+   are used by :program:`mh` to store its state and configuration.
485
n486-:class:`MH` instances have all of the methods of :class:`Mailbox` in addition to
n508+   :class:`MH` instances have all of the methods of :class:`Mailbox` in addition
487-the following:
509+   to the following:
488
489
n490-.. method:: MH.list_folders()
n512+   .. method:: list_folders()
491
n492-   Return a list of the names of all folders.
n514+      Return a list of the names of all folders.
493
494
n495-.. method:: MH.get_folder(folder)
n517+   .. method:: get_folder(folder)
496
n497-   Return an :class:`MH` instance representing the folder whose name is *folder*. A
n519+      Return an :class:`MH` instance representing the folder whose name is
498-   :exc:`NoSuchMailboxError` exception is raised if the folder does not exist.
520+      *folder*. A :exc:`NoSuchMailboxError` exception is raised if the folder
521+      does not exist.
499
500
n501-.. method:: MH.add_folder(folder)
n524+   .. method:: add_folder(folder)
502
n503-   Create a folder whose name is *folder* and return an :class:`MH` instance
n526+      Create a folder whose name is *folder* and return an :class:`MH` instance
504-   representing it.
527+      representing it.
505
506
n507-.. method:: MH.remove_folder(folder)
n530+   .. method:: remove_folder(folder)
508
n509-   Delete the folder whose name is *folder*. If the folder contains any messages, a
n532+      Delete the folder whose name is *folder*. If the folder contains any
510-   :exc:`NotEmptyError` exception will be raised and the folder will not be
533+      messages, a :exc:`NotEmptyError` exception will be raised and the folder
511-   deleted.
534+      will not be deleted.
512
513
n514-.. method:: MH.get_sequences()
n537+   .. method:: get_sequences()
515
n516-   Return a dictionary of sequence names mapped to key lists. If there are no
n539+      Return a dictionary of sequence names mapped to key lists. If there are no
517-   sequences, the empty dictionary is returned.
540+      sequences, the empty dictionary is returned.
518
519
n520-.. method:: MH.set_sequences(sequences)
n543+   .. method:: set_sequences(sequences)
521
n522-   Re-define the sequences that exist in the mailbox based upon *sequences*, a
n545+      Re-define the sequences that exist in the mailbox based upon *sequences*,
523-   dictionary of names mapped to key lists, like returned by :meth:`get_sequences`.
546+      a dictionary of names mapped to key lists, like returned by
547+      :meth:`get_sequences`.
524
525
n526-.. method:: MH.pack()
n550+   .. method:: pack()
527
n528-   Rename messages in the mailbox as necessary to eliminate gaps in numbering.
n552+      Rename messages in the mailbox as necessary to eliminate gaps in
529-   Entries in the sequences list are updated correspondingly.
553+      numbering.  Entries in the sequences list are updated correspondingly.
530
n531-   .. note::
n555+      .. note::
532
n533-      Already-issued keys are invalidated by this operation and should not be
n557+         Already-issued keys are invalidated by this operation and should not be
534-      subsequently used.
558+         subsequently used.
535
n536-Some :class:`Mailbox` methods implemented by :class:`MH` deserve special
n560+   Some :class:`Mailbox` methods implemented by :class:`MH` deserve special
537-remarks:
561+   remarks:
538
539
n540-.. method:: MH.remove(key)
n564+   .. method:: remove(key)
541-            MH.__delitem__(key)
565+               __delitem__(key)
542-            MH.discard(key)
566+               discard(key)
543
n544-   These methods immediately delete the message. The MH convention of marking a
n568+      These methods immediately delete the message. The MH convention of marking
545-   message for deletion by prepending a comma to its name is not used.
569+      a message for deletion by prepending a comma to its name is not used.
546
547
n548-.. method:: MH.lock()
n572+   .. method:: lock()
549-            MH.unlock()
573+               unlock()
550
n551-   Three locking mechanisms are used---dot locking and, if available, the
n575+      Three locking mechanisms are used---dot locking and, if available, the
552-   :cfunc:`flock` and :cfunc:`lockf` system calls. For MH mailboxes, locking the
576+      :cfunc:`flock` and :cfunc:`lockf` system calls. For MH mailboxes, locking
553-   mailbox means locking the :file:`.mh_sequences` file and, only for the duration
577+      the mailbox means locking the :file:`.mh_sequences` file and, only for the
554-   of any operations that affect them, locking individual message files.
578+      duration of any operations that affect them, locking individual message
579+      files.
555
556
n557-.. method:: MH.get_file(key)
n582+   .. method:: get_file(key)
558
n559-   Depending upon the host platform, it may not be possible to remove the
n584+      Depending upon the host platform, it may not be possible to remove the
560-   underlying message while the returned file remains open.
585+      underlying message while the returned file remains open.
561
562
n563-.. method:: MH.flush()
n588+   .. method:: flush()
564
n565-   All changes to MH mailboxes are immediately applied, so this method does
n590+      All changes to MH mailboxes are immediately applied, so this method does
566-   nothing.
591+      nothing.
567
568
n569-.. method:: MH.close()
n594+   .. method:: close()
570
n571-   :class:`MH` instances do not keep any open files, so this method is equivelant
n596+      :class:`MH` instances do not keep any open files, so this method is
572-   to :meth:`unlock`.
597+      equivalent to :meth:`unlock`.
573
574
575.. seealso::
576
577   `nmh - Message Handling System <http://www.nongnu.org/nmh/>`_
578      Home page of :program:`nmh`, an updated version of the original :program:`mh`.
579
580   `MH & nmh: Email for Users & Programmers <http://www.ics.uci.edu/~mh/book/>`_
592
593   A subclass of :class:`Mailbox` for mailboxes in Babyl format. Parameter
594   *factory* is a callable object that accepts a file-like message representation
595   (which behaves as if opened in binary mode) and returns a custom representation.
596   If *factory* is ``None``, :class:`BabylMessage` is used as the default message
597   representation. If *create* is ``True``, the mailbox is created if it does not
598   exist.
599
n600-Babyl is a single-file mailbox format used by the Rmail mail user agent included
n625+   Babyl is a single-file mailbox format used by the Rmail mail user agent
601-with Emacs. The beginning of a message is indicated by a line containing the two
626+   included with Emacs. The beginning of a message is indicated by a line
602-characters Control-Underscore (``'\\037'``) and Control-L (``'\\014'``). The end
627+   containing the two characters Control-Underscore (``'\037'``) and Control-L
603-of a message is indicated by the start of the next message or, in the case of
628+   (``'\014'``). The end of a message is indicated by the start of the next
604-the last message, a line containing a Control-Underscore (``'\\037'``)
629+   message or, in the case of the last message, a line containing a
605-character.
630+   Control-Underscore (``'\037'``) character.
606
n607-Messages in a Babyl mailbox have two sets of headers, original headers and so-
n632+   Messages in a Babyl mailbox have two sets of headers, original headers and
608-called visible headers. Visible headers are typically a subset of the original
633+   so-called visible headers. Visible headers are typically a subset of the
609-headers that have been reformatted or abridged to be more attractive. Each
634+   original headers that have been reformatted or abridged to be more
610-message in a Babyl mailbox also has an accompanying list of :dfn:`labels`, or
635+   attractive. Each message in a Babyl mailbox also has an accompanying list of
611-short strings that record extra information about the message, and a list of all
636+   :dfn:`labels`, or short strings that record extra information about the
612-user-defined labels found in the mailbox is kept in the Babyl options section.
637+   message, and a list of all user-defined labels found in the mailbox is kept
638+   in the Babyl options section.
613
n614-:class:`Babyl` instances have all of the methods of :class:`Mailbox` in addition
n640+   :class:`Babyl` instances have all of the methods of :class:`Mailbox` in
615-to the following:
641+   addition to the following:
616
617
n618-.. method:: Babyl.get_labels()
n644+   .. method:: get_labels()
619
n620-   Return a list of the names of all user-defined labels used in the mailbox.
n646+      Return a list of the names of all user-defined labels used in the mailbox.
621
n622-   .. note::
n648+      .. note::
623
n624-      The actual messages are inspected to determine which labels exist in the mailbox
n650+         The actual messages are inspected to determine which labels exist in
625-      rather than consulting the list of labels in the Babyl options section, but the
651+         the mailbox rather than consulting the list of labels in the Babyl
626-      Babyl section is updated whenever the mailbox is modified.
652+         options section, but the Babyl section is updated whenever the mailbox
653+         is modified.
627
n628-Some :class:`Mailbox` methods implemented by :class:`Babyl` deserve special
n655+   Some :class:`Mailbox` methods implemented by :class:`Babyl` deserve special
629-remarks:
656+   remarks:
630
631
n632-.. method:: Babyl.get_file(key)
n659+   .. method:: get_file(key)
633
n634-   In Babyl mailboxes, the headers of a message are not stored contiguously with
n661+      In Babyl mailboxes, the headers of a message are not stored contiguously
635-   the body of the message. To generate a file-like representation, the headers and
662+      with the body of the message. To generate a file-like representation, the
636-   body are copied together into a :class:`StringIO` instance (from the
663+      headers and body are copied together into a :class:`StringIO` instance
637-   :mod:`StringIO` module), which has an API identical to that of a file. As a
664+      (from the :mod:`StringIO` module), which has an API identical to that of a
638-   result, the file-like object is truly independent of the underlying mailbox but
665+      file. As a result, the file-like object is truly independent of the
639-   does not save memory compared to a string representation.
666+      underlying mailbox but does not save memory compared to a string
667+      representation.
640
641
n642-.. method:: Babyl.lock()
n670+   .. method:: lock()
643-            Babyl.unlock()
671+               unlock()
644
n645-   Three locking mechanisms are used---dot locking and, if available, the
n673+      Three locking mechanisms are used---dot locking and, if available, the
646-   :cfunc:`flock` and :cfunc:`lockf` system calls.
674+      :cfunc:`flock` and :cfunc:`lockf` system calls.
647
648
649.. seealso::
650
651   `Format of Version 5 Babyl Files <http://quimby.gnus.org/notes/BABYL>`_
652      A specification of the Babyl format.
653
n654-   `Reading Mail with Rmail <http://www.gnu.org/software/emacs/manual/html_node/Rmail.html>`_
n682+   `Reading Mail with Rmail <http://www.gnu.org/software/emacs/manual/html_node/emacs/Rmail.html>`_
655      The Rmail manual, with some information on Babyl semantics.
656
657
658.. _mailbox-mmdf:
659
660:class:`MMDF`
661^^^^^^^^^^^^^
662
665
666   A subclass of :class:`Mailbox` for mailboxes in MMDF format. Parameter *factory*
667   is a callable object that accepts a file-like message representation (which
668   behaves as if opened in binary mode) and returns a custom representation. If
669   *factory* is ``None``, :class:`MMDFMessage` is used as the default message
670   representation. If *create* is ``True``, the mailbox is created if it does not
671   exist.
672
n673-MMDF is a single-file mailbox format invented for the Multichannel Memorandum
n701+   MMDF is a single-file mailbox format invented for the Multichannel Memorandum
674-Distribution Facility, a mail transfer agent. Each message is in the same form
702+   Distribution Facility, a mail transfer agent. Each message is in the same
675-as an mbox message but is bracketed before and after by lines containing four
703+   form as an mbox message but is bracketed before and after by lines containing
676-Control-A (``'\\001'``) characters. As with the mbox format, the beginning of
704+   four Control-A (``'\001'``) characters. As with the mbox format, the
677-each message is indicated by a line whose first five characters are "From ", but
705+   beginning of each message is indicated by a line whose first five characters
678-additional occurrences of "From " are not transformed to ">From " when storing
706+   are "From ", but additional occurrences of "From " are not transformed to
679-messages because the extra message separator lines prevent mistaking such
707+   ">From " when storing messages because the extra message separator lines
680-occurrences for the starts of subsequent messages.
708+   prevent mistaking such occurrences for the starts of subsequent messages.
681
n682-Some :class:`Mailbox` methods implemented by :class:`MMDF` deserve special
n710+   Some :class:`Mailbox` methods implemented by :class:`MMDF` deserve special
683-remarks:
711+   remarks:
684
685
n686-.. method:: MMDF.get_file(key)
n714+   .. method:: get_file(key)
687
n688-   Using the file after calling :meth:`flush` or :meth:`close` on the :class:`MMDF`
n716+      Using the file after calling :meth:`flush` or :meth:`close` on the
689-   instance may yield unpredictable results or raise an exception.
717+      :class:`MMDF` instance may yield unpredictable results or raise an
718+      exception.
690
691
n692-.. method:: MMDF.lock()
n721+   .. method:: lock()
693-            MMDF.unlock()
722+               unlock()
694
n695-   Three locking mechanisms are used---dot locking and, if available, the
n724+      Three locking mechanisms are used---dot locking and, if available, the
696-   :cfunc:`flock` and :cfunc:`lockf` system calls.
725+      :cfunc:`flock` and :cfunc:`lockf` system calls.
697
698
699.. seealso::
700
701   `mmdf man page from tin <http://www.tin.org/bin/man.cgi?section=5&topic=mmdf>`_
702      A specification of MMDF format from the documentation of tin, a newsreader.
703
704   `MMDF <http://en.wikipedia.org/wiki/MMDF>`_
719
720   If *message* is omitted, the new instance is created in a default, empty state.
721   If *message* is an :class:`email.Message.Message` instance, its contents are
722   copied; furthermore, any format-specific information is converted insofar as
723   possible if *message* is a :class:`Message` instance. If *message* is a string
724   or a file, it should contain an :rfc:`2822`\ -compliant message, which is read
725   and parsed.
726
n727-The format-specific state and behaviors offered by subclasses vary, but in
n756+   The format-specific state and behaviors offered by subclasses vary, but in
728-general it is only the properties that are not specific to a particular mailbox
757+   general it is only the properties that are not specific to a particular
729-that are supported (although presumably the properties are specific to a
758+   mailbox that are supported (although presumably the properties are specific
730-particular mailbox format). For example, file offsets for single-file mailbox
759+   to a particular mailbox format). For example, file offsets for single-file
731-formats and file names for directory-based mailbox formats are not retained,
760+   mailbox formats and file names for directory-based mailbox formats are not
732-because they are only applicable to the original mailbox. But state such as
761+   retained, because they are only applicable to the original mailbox. But state
733-whether a message has been read by the user or marked as important is retained,
762+   such as whether a message has been read by the user or marked as important is
734-because it applies to the message itself.
763+   retained, because it applies to the message itself.
735
n736-There is no requirement that :class:`Message` instances be used to represent
n765+   There is no requirement that :class:`Message` instances be used to represent
737-messages retrieved using :class:`Mailbox` instances. In some situations, the
766+   messages retrieved using :class:`Mailbox` instances. In some situations, the
738-time and memory required to generate :class:`Message` representations might not
767+   time and memory required to generate :class:`Message` representations might
739-not acceptable. For such situations, :class:`Mailbox` instances also offer
768+   not not acceptable. For such situations, :class:`Mailbox` instances also
740-string and file-like representations, and a custom message factory may be
769+   offer string and file-like representations, and a custom message factory may
741-specified when a :class:`Mailbox` instance is initialized.
770+   be specified when a :class:`Mailbox` instance is initialized.
742
743
744.. _mailbox-maildirmessage:
745
746:class:`MaildirMessage`
747^^^^^^^^^^^^^^^^^^^^^^^
748
749
750.. class:: MaildirMessage([message])
751
752   A message with Maildir-specific behaviors. Parameter *message* has the same
753   meaning as with the :class:`Message` constructor.
754
n755-Typically, a mail user agent application moves all of the messages in the
n784+   Typically, a mail user agent application moves all of the messages in the
756-:file:`new` subdirectory to the :file:`cur` subdirectory after the first time
785+   :file:`new` subdirectory to the :file:`cur` subdirectory after the first time
757-the user opens and closes the mailbox, recording that the messages are old
786+   the user opens and closes the mailbox, recording that the messages are old
758-whether or not they've actually been read. Each message in :file:`cur` has an
787+   whether or not they've actually been read. Each message in :file:`cur` has an
759-"info" section added to its file name to store information about its state.
788+   "info" section added to its file name to store information about its state.
760-(Some mail readers may also add an "info" section to messages in :file:`new`.)
789+   (Some mail readers may also add an "info" section to messages in
761-The "info" section may take one of two forms: it may contain "2," followed by a
790+   :file:`new`.)  The "info" section may take one of two forms: it may contain
762-list of standardized flags (e.g., "2,FR") or it may contain "1," followed by so-
791+   "2," followed by a list of standardized flags (e.g., "2,FR") or it may
763-called experimental information. Standard flags for Maildir messages are as
792+   contain "1," followed by so-called experimental information. Standard flags
764-follows:
793+   for Maildir messages are as follows:
765
n766-+------+---------+--------------------------------+
n795+   +------+---------+--------------------------------+
767-| Flag | Meaning | Explanation                    |
796+   | Flag | Meaning | Explanation                    |
768-+======+=========+================================+
797+   +======+=========+================================+
769-| D    | Draft   | Under composition              |
798+   | D    | Draft   | Under composition              |
770-+------+---------+--------------------------------+
799+   +------+---------+--------------------------------+
771-| F    | Flagged | Marked as important            |
800+   | F    | Flagged | Marked as important            |
772-+------+---------+--------------------------------+
801+   +------+---------+--------------------------------+
773-| P    | Passed  | Forwarded, resent, or bounced  |
802+   | P    | Passed  | Forwarded, resent, or bounced  |
774-+------+---------+--------------------------------+
803+   +------+---------+--------------------------------+
775-| R    | Replied | Replied to                     |
804+   | R    | Replied | Replied to                     |
776-+------+---------+--------------------------------+
805+   +------+---------+--------------------------------+
777-| S    | Seen    | Read                           |
806+   | S    | Seen    | Read                           |
778-+------+---------+--------------------------------+
807+   +------+---------+--------------------------------+
779-| T    | Trashed | Marked for subsequent deletion |
808+   | T    | Trashed | Marked for subsequent deletion |
780-+------+---------+--------------------------------+
809+   +------+---------+--------------------------------+
781
n782-:class:`MaildirMessage` instances offer the following methods:
n811+   :class:`MaildirMessage` instances offer the following methods:
783
784
n785-.. method:: MaildirMessage.get_subdir()
n814+   .. method:: get_subdir()
786
n787-   Return either "new" (if the message should be stored in the :file:`new`
n816+      Return either "new" (if the message should be stored in the :file:`new`
788-   subdirectory) or "cur" (if the message should be stored in the :file:`cur`
817+      subdirectory) or "cur" (if the message should be stored in the :file:`cur`
789-   subdirectory).
818+      subdirectory).
790
n791-   .. note::
n820+      .. note::
792
n793-      A message is typically moved from :file:`new` to :file:`cur` after its mailbox
n822+         A message is typically moved from :file:`new` to :file:`cur` after its
794-      has been accessed, whether or not the message is has been read. A message
823+         mailbox has been accessed, whether or not the message is has been
795-      ``msg`` has been read if ``"S" not in msg.get_flags()`` is ``True``.
824+         read. A message ``msg`` has been read if ``"S" in msg.get_flags()`` is
825+         ``True``.
796
797
n798-.. method:: MaildirMessage.set_subdir(subdir)
n828+   .. method:: set_subdir(subdir)
799
n800-   Set the subdirectory the message should be stored in. Parameter *subdir* must be
n830+      Set the subdirectory the message should be stored in. Parameter *subdir*
801-   either "new" or "cur".
831+      must be either "new" or "cur".
802
803
n804-.. method:: MaildirMessage.get_flags()
n834+   .. method:: get_flags()
805
n806-   Return a string specifying the flags that are currently set. If the message
n836+      Return a string specifying the flags that are currently set. If the
807-   complies with the standard Maildir format, the result is the concatenation in
837+      message complies with the standard Maildir format, the result is the
808-   alphabetical order of zero or one occurrence of each of ``'D'``, ``'F'``,
838+      concatenation in alphabetical order of zero or one occurrence of each of
809-   ``'P'``, ``'R'``, ``'S'``, and ``'T'``. The empty string is returned if no flags
839+      ``'D'``, ``'F'``, ``'P'``, ``'R'``, ``'S'``, and ``'T'``. The empty string
810-   are set or if "info" contains experimental semantics.
840+      is returned if no flags are set or if "info" contains experimental
841+      semantics.
811
812
n813-.. method:: MaildirMessage.set_flags(flags)
n844+   .. method:: set_flags(flags)
814
n815-   Set the flags specified by *flags* and unset all others.
n846+      Set the flags specified by *flags* and unset all others.
816
817
n818-.. method:: MaildirMessage.add_flag(flag)
n849+   .. method:: add_flag(flag)
819
n820-   Set the flag(s) specified by *flag* without changing other flags. To add more
n851+      Set the flag(s) specified by *flag* without changing other flags. To add
821-   than one flag at a time, *flag* may be a string of more than one character. The
852+      more than one flag at a time, *flag* may be a string of more than one
822-   current "info" is overwritten whether or not it contains experimental
853+      character. The current "info" is overwritten whether or not it contains
823-   information rather than flags.
854+      experimental information rather than flags.
824
825
n826-.. method:: MaildirMessage.remove_flag(flag)
n857+   .. method:: remove_flag(flag)
827
n828-   Unset the flag(s) specified by *flag* without changing other flags. To remove
n859+      Unset the flag(s) specified by *flag* without changing other flags. To
829-   more than one flag at a time, *flag* maybe a string of more than one character.
860+      remove more than one flag at a time, *flag* maybe a string of more than
830-   If "info" contains experimental information rather than flags, the current
861+      one character.  If "info" contains experimental information rather than
831-   "info" is not modified.
862+      flags, the current "info" is not modified.
832
833
n834-.. method:: MaildirMessage.get_date()
n865+   .. method:: get_date()
835
n836-   Return the delivery date of the message as a floating-point number representing
n867+      Return the delivery date of the message as a floating-point number
837-   seconds since the epoch.
868+      representing seconds since the epoch.
838
839
n840-.. method:: MaildirMessage.set_date(date)
n871+   .. method:: set_date(date)
841
n842-   Set the delivery date of the message to *date*, a floating-point number
n873+      Set the delivery date of the message to *date*, a floating-point number
843-   representing seconds since the epoch.
874+      representing seconds since the epoch.
844
845
n846-.. method:: MaildirMessage.get_info()
n877+   .. method:: get_info()
847
n848-   Return a string containing the "info" for a message. This is useful for
n879+      Return a string containing the "info" for a message. This is useful for
849-   accessing and modifying "info" that is experimental (i.e., not a list of flags).
880+      accessing and modifying "info" that is experimental (i.e., not a list of
881+      flags).
850
851
n852-.. method:: MaildirMessage.set_info(info)
n884+   .. method:: set_info(info)
853
n854-   Set "info" to *info*, which should be a string.
n886+      Set "info" to *info*, which should be a string.
855
856When a :class:`MaildirMessage` instance is created based upon an
857:class:`mboxMessage` or :class:`MMDFMessage` instance, the :mailheader:`Status`
858and :mailheader:`X-Status` headers are omitted and the following conversions
859take place:
860
861+--------------------+----------------------------------------------+
862| Resulting state    | :class:`mboxMessage` or :class:`MMDFMessage` |
912^^^^^^^^^^^^^^^^^^^^
913
914
915.. class:: mboxMessage([message])
916
917   A message with mbox-specific behaviors. Parameter *message* has the same meaning
918   as with the :class:`Message` constructor.
919
n920-Messages in an mbox mailbox are stored together in a single file. The sender's
n952+   Messages in an mbox mailbox are stored together in a single file. The
921-envelope address and the time of delivery are typically stored in a line
953+   sender's envelope address and the time of delivery are typically stored in a
922-beginning with "From " that is used to indicate the start of a message, though
954+   line beginning with "From " that is used to indicate the start of a message,
923-there is considerable variation in the exact format of this data among mbox
955+   though there is considerable variation in the exact format of this data among
924-implementations. Flags that indicate the state of the message, such as whether
956+   mbox implementations. Flags that indicate the state of the message, such as
925-it has been read or marked as important, are typically stored in
957+   whether it has been read or marked as important, are typically stored in
926-:mailheader:`Status` and :mailheader:`X-Status` headers.
958+   :mailheader:`Status` and :mailheader:`X-Status` headers.
927
n928-Conventional flags for mbox messages are as follows:
n960+   Conventional flags for mbox messages are as follows:
929
n930-+------+----------+--------------------------------+
n962+   +------+----------+--------------------------------+
931-| Flag | Meaning  | Explanation                    |
963+   | Flag | Meaning  | Explanation                    |
932-+======+==========+================================+
964+   +======+==========+================================+
933-| R    | Read     | Read                           |
965+   | R    | Read     | Read                           |
934-+------+----------+--------------------------------+
966+   +------+----------+--------------------------------+
935-| O    | Old      | Previously detected by MUA     |
967+   | O    | Old      | Previously detected by MUA     |
936-+------+----------+--------------------------------+
968+   +------+----------+--------------------------------+
937-| D    | Deleted  | Marked for subsequent deletion |
969+   | D    | Deleted  | Marked for subsequent deletion |
938-+------+----------+--------------------------------+
970+   +------+----------+--------------------------------+
939-| F    | Flagged  | Marked as important            |
971+   | F    | Flagged  | Marked as important            |
940-+------+----------+--------------------------------+
972+   +------+----------+--------------------------------+
941-| A    | Answered | Replied to                     |
973+   | A    | Answered | Replied to                     |
942-+------+----------+--------------------------------+
974+   +------+----------+--------------------------------+
943
n944-The "R" and "O" flags are stored in the :mailheader:`Status` header, and the
n976+   The "R" and "O" flags are stored in the :mailheader:`Status` header, and the
945-"D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The
977+   "D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The
946-flags and headers typically appear in the order mentioned.
978+   flags and headers typically appear in the order mentioned.
947
n948-:class:`mboxMessage` instances offer the following methods:
n980+   :class:`mboxMessage` instances offer the following methods:
949
950
n951-.. method:: mboxMessage.get_from()
n983+   .. method:: get_from()
952
n953-   Return a string representing the "From " line that marks the start of the
n985+      Return a string representing the "From " line that marks the start of the
954-   message in an mbox mailbox. The leading "From " and the trailing newline are
986+      message in an mbox mailbox. The leading "From " and the trailing newline
955-   excluded.
987+      are excluded.
956
957
n958-.. method:: mboxMessage.set_from(from_[, time_=None])
n990+   .. method:: set_from(from_[, time_=None])
959
n960-   Set the "From " line to *from_*, which should be specified without a leading
n992+      Set the "From " line to *from_*, which should be specified without a
961-   "From " or trailing newline. For convenience, *time_* may be specified and will
993+      leading "From " or trailing newline. For convenience, *time_* may be
962-   be formatted appropriately and appended to *from_*. If *time_* is specified, it
994+      specified and will be formatted appropriately and appended to *from_*. If
963-   should be a :class:`struct_time` instance, a tuple suitable for passing to
995+      *time_* is specified, it should be a :class:`struct_time` instance, a
964-   :meth:`time.strftime`, or ``True`` (to use :meth:`time.gmtime`).
996+      tuple suitable for passing to :meth:`time.strftime`, or ``True`` (to use
997+      :meth:`time.gmtime`).
965
966
n967-.. method:: mboxMessage.get_flags()
n1000+   .. method:: get_flags()
968
n969-   Return a string specifying the flags that are currently set. If the message
n1002+      Return a string specifying the flags that are currently set. If the
970-   complies with the conventional format, the result is the concatenation in the
1003+      message complies with the conventional format, the result is the
971-   following order of zero or one occurrence of each of ``'R'``, ``'O'``, ``'D'``,
1004+      concatenation in the following order of zero or one occurrence of each of
972-   ``'F'``, and ``'A'``.
1005+      ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.
973
974
n975-.. method:: mboxMessage.set_flags(flags)
n1008+   .. method:: set_flags(flags)
976
n977-   Set the flags specified by *flags* and unset all others. Parameter *flags*
n1010+      Set the flags specified by *flags* and unset all others. Parameter *flags*
978-   should be the concatenation in any order of zero or more occurrences of each of
1011+      should be the concatenation in any order of zero or more occurrences of
979-   ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.
1012+      each of ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.
980
981
n982-.. method:: mboxMessage.add_flag(flag)
n1015+   .. method:: add_flag(flag)
983
n984-   Set the flag(s) specified by *flag* without changing other flags. To add more
n1017+      Set the flag(s) specified by *flag* without changing other flags. To add
985-   than one flag at a time, *flag* may be a string of more than one character.
1018+      more than one flag at a time, *flag* may be a string of more than one
1019+      character.
986
987
n988-.. method:: mboxMessage.remove_flag(flag)
n1022+   .. method:: remove_flag(flag)
989
n990-   Unset the flag(s) specified by *flag* without changing other flags. To remove
n1024+      Unset the flag(s) specified by *flag* without changing other flags. To
991-   more than one flag at a time, *flag* maybe a string of more than one character.
1025+      remove more than one flag at a time, *flag* maybe a string of more than
1026+      one character.
992
993When an :class:`mboxMessage` instance is created based upon a
994:class:`MaildirMessage` instance, a "From " line is generated based upon the
995:class:`MaildirMessage` instance's delivery date, and the following conversions
996take place:
997
998+-----------------+-------------------------------+
999| Resulting state | :class:`MaildirMessage` state |
1063^^^^^^^^^^^^^^^^^^
1064
1065
1066.. class:: MHMessage([message])
1067
1068   A message with MH-specific behaviors. Parameter *message* has the same meaning
1069   as with the :class:`Message` constructor.
1070
n1071-MH messages do not support marks or flags in the traditional sense, but they do
n1106+   MH messages do not support marks or flags in the traditional sense, but they
1072-support sequences, which are logical groupings of arbitrary messages. Some mail
1107+   do support sequences, which are logical groupings of arbitrary messages. Some
1073-reading programs (although not the standard :program:`mh` and :program:`nmh`)
1108+   mail reading programs (although not the standard :program:`mh` and
1074-use sequences in much the same way flags are used with other formats, as
1109+   :program:`nmh`) use sequences in much the same way flags are used with other
1075-follows:
1110+   formats, as follows:
1076
n1077-+----------+------------------------------------------+
n1112+   +----------+------------------------------------------+
1078-| Sequence | Explanation                              |
1113+   | Sequence | Explanation                              |
1079-+==========+==========================================+
1114+   +==========+==========================================+
1080-| unseen   | Not read, but previously detected by MUA |
1115+   | unseen   | Not read, but previously detected by MUA |
1081-+----------+------------------------------------------+
1116+   +----------+------------------------------------------+
1082-| replied  | Replied to                               |
1117+   | replied  | Replied to                               |
1083-+----------+------------------------------------------+
1118+   +----------+------------------------------------------+
1084-| flagged  | Marked as important                      |
1119+   | flagged  | Marked as important                      |
1085-+----------+------------------------------------------+
1120+   +----------+------------------------------------------+
1086
n1087-:class:`MHMessage` instances offer the following methods:
n1122+   :class:`MHMessage` instances offer the following methods:
1088
1089
n1090-.. method:: MHMessage.get_sequences()
n1125+   .. method:: get_sequences()
1091
n1092-   Return a list of the names of sequences that include this message.
n1127+      Return a list of the names of sequences that include this message.
1093
1094
n1095-.. method:: MHMessage.set_sequences(sequences)
n1130+   .. method:: set_sequences(sequences)
1096
n1097-   Set the list of sequences that include this message.
n1132+      Set the list of sequences that include this message.
1098
1099
n1100-.. method:: MHMessage.add_sequence(sequence)
n1135+   .. method:: add_sequence(sequence)
1101
n1102-   Add *sequence* to the list of sequences that include this message.
n1137+      Add *sequence* to the list of sequences that include this message.
1103
1104
n1105-.. method:: MHMessage.remove_sequence(sequence)
n1140+   .. method:: remove_sequence(sequence)
1106
n1107-   Remove *sequence* from the list of sequences that include this message.
n1142+      Remove *sequence* from the list of sequences that include this message.
1108
1109When an :class:`MHMessage` instance is created based upon a
1110:class:`MaildirMessage` instance, the following conversions take place:
1111
1112+--------------------+-------------------------------+
1113| Resulting state    | :class:`MaildirMessage` state |
1114+====================+===============================+
1115| "unseen" sequence  | no S flag                     |
1153^^^^^^^^^^^^^^^^^^^^^
1154
1155
1156.. class:: BabylMessage([message])
1157
1158   A message with Babyl-specific behaviors. Parameter *message* has the same
1159   meaning as with the :class:`Message` constructor.
1160
n1161-Certain message labels, called :dfn:`attributes`, are defined by convention to
n1196+   Certain message labels, called :dfn:`attributes`, are defined by convention
1162-have special meanings. The attributes are as follows:
1197+   to have special meanings. The attributes are as follows:
1163
n1164-+-----------+------------------------------------------+
n1199+   +-----------+------------------------------------------+
1165-| Label     | Explanation                              |
1200+   | Label     | Explanation                              |
1166-+===========+==========================================+
1201+   +===========+==========================================+
1167-| unseen    | Not read, but previously detected by MUA |
1202+   | unseen    | Not read, but previously detected by MUA |
1168-+-----------+------------------------------------------+
1203+   +-----------+------------------------------------------+
1169-| deleted   | Marked for subsequent deletion           |
1204+   | deleted   | Marked for subsequent deletion           |
1170-+-----------+------------------------------------------+
1205+   +-----------+------------------------------------------+
1171-| filed     | Copied to another file or mailbox        |
1206+   | filed     | Copied to another file or mailbox        |
1172-+-----------+------------------------------------------+
1207+   +-----------+------------------------------------------+
1173-| answered  | Replied to                               |
1208+   | answered  | Replied to                               |
1174-+-----------+------------------------------------------+
1209+   +-----------+------------------------------------------+
1175-| forwarded | Forwarded                                |
1210+   | forwarded | Forwarded                                |
1176-+-----------+------------------------------------------+
1211+   +-----------+------------------------------------------+
1177-| edited    | Modified by the user                     |
1212+   | edited    | Modified by the user                     |
1178-+-----------+------------------------------------------+
1213+   +-----------+------------------------------------------+
1179-| resent    | Resent                                   |
1214+   | resent    | Resent                                   |
1180-+-----------+------------------------------------------+
1215+   +-----------+------------------------------------------+
1181
n1182-By default, Rmail displays only visible headers. The :class:`BabylMessage`
n1217+   By default, Rmail displays only visible headers. The :class:`BabylMessage`
1183-class, though, uses the original headers because they are more complete. Visible
1218+   class, though, uses the original headers because they are more
1184-headers may be accessed explicitly if desired.
1219+   complete. Visible headers may be accessed explicitly if desired.
1185
n1186-:class:`BabylMessage` instances offer the following methods:
n1221+   :class:`BabylMessage` instances offer the following methods:
1187
1188
n1189-.. method:: BabylMessage.get_labels()
n1224+   .. method:: get_labels()
1190
n1191-   Return a list of labels on the message.
n1226+      Return a list of labels on the message.
1192
1193
n1194-.. method:: BabylMessage.set_labels(labels)
n1229+   .. method:: set_labels(labels)
1195
n1196-   Set the list of labels on the message to *labels*.
n1231+      Set the list of labels on the message to *labels*.
1197
1198
n1199-.. method:: BabylMessage.add_label(label)
n1234+   .. method:: add_label(label)
1200
n1201-   Add *label* to the list of labels on the message.
n1236+      Add *label* to the list of labels on the message.
1202
1203
n1204-.. method:: BabylMessage.remove_label(label)
n1239+   .. method:: remove_label(label)
1205
n1206-   Remove *label* from the list of labels on the message.
n1241+      Remove *label* from the list of labels on the message.
1207
1208
n1209-.. method:: BabylMessage.get_visible()
n1244+   .. method:: get_visible()
1210
n1211-   Return an :class:`Message` instance whose headers are the message's visible
n1246+      Return an :class:`Message` instance whose headers are the message's
1212-   headers and whose body is empty.
1247+      visible headers and whose body is empty.
1213
1214
n1215-.. method:: BabylMessage.set_visible(visible)
n1250+   .. method:: set_visible(visible)
1216
n1217-   Set the message's visible headers to be the same as the headers in *message*.
n1252+      Set the message's visible headers to be the same as the headers in
1218-   Parameter *visible* should be a :class:`Message` instance, an
1253+      *message*.  Parameter *visible* should be a :class:`Message` instance, an
1219-   :class:`email.Message.Message` instance, a string, or a file-like object (which
1254+      :class:`email.Message.Message` instance, a string, or a file-like object
1220-   should be open in text mode).
1255+      (which should be open in text mode).
1221
1222
n1223-.. method:: BabylMessage.update_visible()
n1258+   .. method:: update_visible()
1224
n1225-   When a :class:`BabylMessage` instance's original headers are modified, the
n1260+      When a :class:`BabylMessage` instance's original headers are modified, the
1226-   visible headers are not automatically modified to correspond. This method
1261+      visible headers are not automatically modified to correspond. This method
1227-   updates the visible headers as follows: each visible header with a corresponding
1262+      updates the visible headers as follows: each visible header with a
1228-   original header is set to the value of the original header, each visible header
1263+      corresponding original header is set to the value of the original header,
1229-   without a corresponding original header is removed, and any of
1264+      each visible header without a corresponding original header is removed,
1230-   :mailheader:`Date`, :mailheader:`From`, :mailheader:`Reply-To`,
1265+      and any of :mailheader:`Date`, :mailheader:`From`, :mailheader:`Reply-To`,
1231-   :mailheader:`To`, :mailheader:`CC`, and :mailheader:`Subject` that are present
1266+      :mailheader:`To`, :mailheader:`CC`, and :mailheader:`Subject` that are
1232-   in the original headers but not the visible headers are added to the visible
1267+      present in the original headers but not the visible headers are added to
1233-   headers.
1268+      the visible headers.
1234
1235When a :class:`BabylMessage` instance is created based upon a
1236:class:`MaildirMessage` instance, the following conversions take place:
1237
1238+-------------------+-------------------------------+
1239| Resulting state   | :class:`MaildirMessage` state |
1240+===================+===============================+
1241| "unseen" label    | no S flag                     |
1281^^^^^^^^^^^^^^^^^^^^
1282
1283
1284.. class:: MMDFMessage([message])
1285
1286   A message with MMDF-specific behaviors. Parameter *message* has the same meaning
1287   as with the :class:`Message` constructor.
1288
n1289-As with message in an mbox mailbox, MMDF messages are stored with the sender's
n1324+   As with message in an mbox mailbox, MMDF messages are stored with the
1290-address and the delivery date in an initial line beginning with "From ".
1325+   sender's address and the delivery date in an initial line beginning with
1291-Likewise, flags that indicate the state of the message are typically stored in
1326+   "From ".  Likewise, flags that indicate the state of the message are
1292-:mailheader:`Status` and :mailheader:`X-Status` headers.
1327+   typically stored in :mailheader:`Status` and :mailheader:`X-Status` headers.
1293
n1294-Conventional flags for MMDF messages are identical to those of mbox message and
n1329+   Conventional flags for MMDF messages are identical to those of mbox message
1295-are as follows:
1330+   and are as follows:
1296
n1297-+------+----------+--------------------------------+
n1332+   +------+----------+--------------------------------+
1298-| Flag | Meaning  | Explanation                    |
1333+   | Flag | Meaning  | Explanation                    |
1299-+======+==========+================================+
1334+   +======+==========+================================+
1300-| R    | Read     | Read                           |
1335+   | R    | Read     | Read                           |
1301-+------+----------+--------------------------------+
1336+   +------+----------+--------------------------------+
1302-| O    | Old      | Previously detected by MUA     |
1337+   | O    | Old      | Previously detected by MUA     |
1303-+------+----------+--------------------------------+
1338+   +------+----------+--------------------------------+
1304-| D    | Deleted  | Marked for subsequent deletion |
1339+   | D    | Deleted  | Marked for subsequent deletion |
1305-+------+----------+--------------------------------+
1340+   +------+----------+--------------------------------+
1306-| F    | Flagged  | Marked as important            |
1341+   | F    | Flagged  | Marked as important            |
1307-+------+----------+--------------------------------+
1342+   +------+----------+--------------------------------+
1308-| A    | Answered | Replied to                     |
1343+   | A    | Answered | Replied to                     |
1309-+------+----------+--------------------------------+
1344+   +------+----------+--------------------------------+
1310
n1311-The "R" and "O" flags are stored in the :mailheader:`Status` header, and the
n1346+   The "R" and "O" flags are stored in the :mailheader:`Status` header, and the
1312-"D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The
1347+   "D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The
1313-flags and headers typically appear in the order mentioned.
1348+   flags and headers typically appear in the order mentioned.
1314
n1315-:class:`MMDFMessage` instances offer the following methods, which are identical
n1350+   :class:`MMDFMessage` instances offer the following methods, which are
1316-to those offered by :class:`mboxMessage`:
1351+   identical to those offered by :class:`mboxMessage`:
1317
1318
n1319-.. method:: MMDFMessage.get_from()
n1354+   .. method:: get_from()
1320
n1321-   Return a string representing the "From " line that marks the start of the
n1356+      Return a string representing the "From " line that marks the start of the
1322-   message in an mbox mailbox. The leading "From " and the trailing newline are
1357+      message in an mbox mailbox. The leading "From " and the trailing newline
1323-   excluded.
1358+      are excluded.
1324
1325
n1326-.. method:: MMDFMessage.set_from(from_[, time_=None])
n1361+   .. method:: set_from(from_[, time_=None])
1327
n1328-   Set the "From " line to *from_*, which should be specified without a leading
n1363+      Set the "From " line to *from_*, which should be specified without a
1329-   "From " or trailing newline. For convenience, *time_* may be specified and will
1364+      leading "From " or trailing newline. For convenience, *time_* may be
1330-   be formatted appropriately and appended to *from_*. If *time_* is specified, it
1365+      specified and will be formatted appropriately and appended to *from_*. If
1331-   should be a :class:`struct_time` instance, a tuple suitable for passing to
1366+      *time_* is specified, it should be a :class:`struct_time` instance, a
1332-   :meth:`time.strftime`, or ``True`` (to use :meth:`time.gmtime`).
1367+      tuple suitable for passing to :meth:`time.strftime`, or ``True`` (to use
1368+      :meth:`time.gmtime`).
1333
1334
n1335-.. method:: MMDFMessage.get_flags()
n1371+   .. method:: get_flags()
1336
n1337-   Return a string specifying the flags that are currently set. If the message
n1373+      Return a string specifying the flags that are currently set. If the
1338-   complies with the conventional format, the result is the concatenation in the
1374+      message complies with the conventional format, the result is the
1339-   following order of zero or one occurrence of each of ``'R'``, ``'O'``, ``'D'``,
1375+      concatenation in the following order of zero or one occurrence of each of
1340-   ``'F'``, and ``'A'``.
1376+      ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.
1341
1342
n1343-.. method:: MMDFMessage.set_flags(flags)
n1379+   .. method:: set_flags(flags)
1344
n1345-   Set the flags specified by *flags* and unset all others. Parameter *flags*
n1381+      Set the flags specified by *flags* and unset all others. Parameter *flags*
1346-   should be the concatenation in any order of zero or more occurrences of each of
1382+      should be the concatenation in any order of zero or more occurrences of
1347-   ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.
1383+      each of ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.
1348
1349
n1350-.. method:: MMDFMessage.add_flag(flag)
n1386+   .. method:: add_flag(flag)
1351
n1352-   Set the flag(s) specified by *flag* without changing other flags. To add more
n1388+      Set the flag(s) specified by *flag* without changing other flags. To add
1353-   than one flag at a time, *flag* may be a string of more than one character.
1389+      more than one flag at a time, *flag* may be a string of more than one
1390+      character.
1354
1355
n1356-.. method:: MMDFMessage.remove_flag(flag)
n1393+   .. method:: remove_flag(flag)
1357
n1358-   Unset the flag(s) specified by *flag* without changing other flags. To remove
n1395+      Unset the flag(s) specified by *flag* without changing other flags. To
1359-   more than one flag at a time, *flag* maybe a string of more than one character.
1396+      remove more than one flag at a time, *flag* maybe a string of more than
1397+      one character.
1360
1361When an :class:`MMDFMessage` instance is created based upon a
1362:class:`MaildirMessage` instance, a "From " line is generated based upon the
1363:class:`MaildirMessage` instance's delivery date, and the following conversions
1364take place:
1365
1366+-----------------+-------------------------------+
1367| Resulting state | :class:`MaildirMessage` state |
1421| D flag          | D flag                     |
1422+-----------------+----------------------------+
1423| F flag          | F flag                     |
1424+-----------------+----------------------------+
1425| A flag          | A flag                     |
1426+-----------------+----------------------------+
1427
1428
n1429-.. _mailbox-deprecated:
1430- 
1431Exceptions
1432----------
1433
1434The following exception classes are defined in the :mod:`mailbox` module:
1435
1436
n1437-.. class:: Error()
n1473+.. exception:: Error()
1438
1439   The based class for all other module-specific exceptions.
1440
1441
n1442-.. class:: NoSuchMailboxError()
n1478+.. exception:: NoSuchMailboxError()
1443
1444   Raised when a mailbox is expected but is not found, such as when instantiating a
1445   :class:`Mailbox` subclass with a path that does not exist (and with the *create*
1446   parameter set to ``False``), or when opening a folder that does not exist.
1447
1448
n1449-.. class:: NotEmptyErrorError()
n1485+.. exception:: NotEmptyError()
1450
1451   Raised when a mailbox is not empty but is expected to be, such as when deleting
1452   a folder that contains messages.
1453
1454
n1455-.. class:: ExternalClashError()
n1491+.. exception:: ExternalClashError()
1456
1457   Raised when some mailbox-related condition beyond the control of the program
1458   causes it to be unable to proceed, such as when failing to acquire a lock that
1459   another program already holds a lock, or when a uniquely-generated file name
1460   already exists.
1461
1462
n1463-.. class:: FormatError()
n1499+.. exception:: FormatError()
1464
1465   Raised when the data in a file cannot be parsed, such as when an :class:`MH`
1466   instance attempts to read a corrupted :file:`.mh_sequences` file.
1467
1468
1469.. _mailbox-deprecated:
1470
1471Deprecated classes and methods
1472------------------------------
n1509+ 
1510+.. deprecated:: 2.6
1473
1474Older versions of the :mod:`mailbox` module do not support modification of
1475mailboxes, such as adding or removing message, and do not provide classes to
1476represent format-specific message properties. For backward compatibility, the
1477older mailbox classes are still available, but the newer classes should be used
n1478-in preference to them.
n1516+in preference to them.  The old classes will be removed in Python 3.0.
1479
1480Older mailbox objects support only iteration and provide a single public method:
1481
1482
n1483-.. method:: XXX Class.next()
n1521+.. method:: oldmailbox.next()
1484
1485   Return the next message in the mailbox, created with the optional *factory*
1486   argument passed into the mailbox object's constructor. By default this is an
1487   :class:`rfc822.Message` object (see the :mod:`rfc822` module).  Depending on the
1488   mailbox implementation the *fp* attribute of this object may be a true file
1489   object or a class instance simulating a file object, taking care of things like
1490   message boundaries if multiple mail messages are contained in a single file,
1491   etc.  If no more messages are available, this method returns ``None``.
1512   .. note::
1513
1514      For reasons of this module's internal implementation, you will probably want to
1515      open the *fp* object in binary mode.  This is especially important on Windows.
1516
1517   For maximum portability, messages in a Unix-style mailbox are separated by any
1518   line that begins exactly with the string ``'From '`` (note the trailing space)
1519   if preceded by exactly two newlines. Because of the wide-range of variations in
n1520-   practice, nothing else on the From_ line should be considered.  However, the
n1558+   practice, nothing else on the ``From_`` line should be considered.  However, the
1521   current implementation doesn't check for the leading two newlines.  This is
1522   usually fine for most applications.
1523
n1524-   The :class:`UnixMailbox` class implements a more strict version of From_ line
n1562+   The :class:`UnixMailbox` class implements a more strict version of ``From_``
1525-   checking, using a regular expression that usually correctly matched From_
1563+   line checking, using a regular expression that usually correctly matched
1526-   delimiters.  It considers delimiter line to be separated by ``From name time``
1564+   ``From_`` delimiters.  It considers delimiter line to be separated by ``From
1527-   lines.  For maximum portability, use the :class:`PortableUnixMailbox` class
1565+   name time`` lines.  For maximum portability, use the
1528-   instead.  This class is identical to :class:`UnixMailbox` except that individual
1566+   :class:`PortableUnixMailbox` class instead.  This class is identical to
1529-   messages are separated by only ``From`` lines.
1567+   :class:`UnixMailbox` except that individual messages are separated by only
1530- 
1568+   ``From`` lines.
1531-   For more information, see `Configuring Netscape Mail on Unix: Why the Content-
1532-   Length Format is Bad <http://home.netscape.com/eng/mozilla/2.0/relnotes/demo
1533-   /content-length.html>`_.
1534
1535
1536.. class:: PortableUnixMailbox(fp[, factory])
1537
1538   A less-strict version of :class:`UnixMailbox`, which considers only the ``From``
1539   at the beginning of the line separating messages.  The "*name* *time*" portion
1540   of the From line is ignored, to protect against some variations that are
1541   observed in practice.  This works since lines in the message which begin with
1610       if subject and 'python' in subject.lower():
1611           print subject
1612
1613To copy all mail from a Babyl mailbox to an MH mailbox, converting all of the
1614format-specific information that can be converted::
1615
1616   import mailbox
1617   destination = mailbox.MH('~/Mail')
n1653+   destination.lock()
1618   for message in mailbox.Babyl('~/RMAIL'):
n1619-       destination.add(MHMessage(message))
n1655+       destination.add(mailbox.MHMessage(message))
1656+   destination.flush()
1657+   destination.unlock()
1620
n1621-An example of sorting mail from numerous mailing lists, being careful to avoid
n1659+This example sorts mail from several mailing lists into different mailboxes,
1622-mail corruption due to concurrent modification by other programs, mail loss due
1660+being careful to avoid mail corruption due to concurrent modification by other
1623-to interruption of the program, or premature termination due to malformed
1661+programs, mail loss due to interruption of the program, or premature termination
1624-messages in the mailbox::
1662+due to malformed messages in the mailbox::
1625
1626   import mailbox
1627   import email.Errors
n1666+ 
1628   list_names = ('python-list', 'python-dev', 'python-bugs')
n1668+ 
1629   boxes = dict((name, mailbox.mbox('~/email/%s' % name)) for name in list_names)
n1630-   inbox = mailbox.Maildir('~/Maildir', None)
n1670+   inbox = mailbox.Maildir('~/Maildir', factory=None)
1671+ 
1631   for key in inbox.iterkeys():
1632       try:
1633           message = inbox[key]
1634       except email.Errors.MessageParseError:
1635           continue                # The message is malformed. Just leave it.
n1677+ 
1636       for name in list_names:
1637           list_id = message['list-id']
1638           if list_id and name in list_id:
n1681+               # Get mailbox to use
1639               box = boxes[name]
n1683+ 
1684+               # Write copy to disk before removing original.
1685+               # If there's a crash, you might duplicate a message, but
1686+               # that's better than losing a message completely.
1640               box.lock()
1641               box.add(message)
n1642-               box.flush()         # Write copy to disk before removing original.
n1689+               box.flush()
1643               box.unlock()
n1691+ 
1692+               # Remove original message
1693+               inbox.lock()
1644               inbox.discard(key)
n1695+               inbox.flush()
1696+               inbox.unlock()
1645               break               # Found destination, so stop looking.
t1698+ 
1646   for box in boxes.itervalues():
1647       box.close()
1648
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op