study/uTools-Manuals
1
0
Fork 0
mirror of https://github.com/fofolee/uTools-Manuals.git synced 2025-06-09 15:34:05 +08:00
Code Issues Packages Projects Releases Wiki Activity
uTools-Manuals/docs/python/mailbox.html
fofolee 38dcd51d8a v0.0.2
2019-04-21 11:50:48 +08:00

52 lines
157 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<div class="body" role="main"><div class="section" id="module-mailbox"><h1><span class="yiyi-st" id="yiyi-10">19.4. <a class="reference internal" href="#module-mailbox" title="mailbox: Manipulate mailboxes in various formats"><code class="xref py py-mod docutils literal"><span class="pre">mailbox</span></code></a> — Manipulate mailboxes in various formats</span></h1><p><span class="yiyi-st" id="yiyi-11"><strong>Source code:</strong> <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/mailbox.py">Lib/mailbox.py</a></span></p><p><span class="yiyi-st" id="yiyi-12">This module defines two classes, <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> and <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a>, for accessing and manipulating on-disk mailboxes and the messages they contain. </span><span class="yiyi-st" id="yiyi-13"><a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> offers a dictionary-like mapping from keys to messages. </span><span class="yiyi-st" id="yiyi-14"><a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> extends the <a class="reference internal" href="email.message.html#module-email.message" title="email.message: The base class representing email messages."><code class="xref py py-mod docutils literal"><span class="pre">email.message</span></code></a> module’s <a class="reference internal" href="email.message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> class with format-specific state and behavior. </span><span class="yiyi-st" id="yiyi-15">Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.</span></p><div class="admonition seealso"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-16">See also</span></p><dl class="last docutils"><dt><span class="yiyi-st" id="yiyi-17">Module <a class="reference internal" href="email.html#module-email" title="email: Package supporting the parsing, manipulating, and generating email messages, including MIME documents."><code class="xref py py-mod docutils literal"><span class="pre">email</span></code></a></span></dt><dd><span class="yiyi-st" id="yiyi-18">Represent and manipulate messages.</span></dd></dl></div><div class="section" id="mailbox-objects"><h2><span class="yiyi-st" id="yiyi-19">19.4.1. </span><span class="yiyi-st" id="yiyi-20"><a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> objects</span></h2><dl class="class"><dt id="mailbox.Mailbox"><span class="yiyi-st" id="yiyi-21"> <em class="property">class </em><code class="descclassname">mailbox.</code><code class="descname">Mailbox</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-22">A mailbox, which may be inspected and modified.</span></p><p><span class="yiyi-st" id="yiyi-23">The <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> class defines an interface and is not intended to be instantiated. </span><span class="yiyi-st" id="yiyi-24">Instead, format-specific subclasses should inherit from <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> and your code should instantiate a particular subclass.</span></p><p><span class="yiyi-st" id="yiyi-25">The <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> interface is dictionary-like, with small keys corresponding to messages. </span><span class="yiyi-st" id="yiyi-26">Keys are issued by the <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> instance with which they will be used and are only meaningful to that <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> instance. </span><span class="yiyi-st" id="yiyi-27">A key continues to identify a message even if the corresponding message is modified, such as by replacing it with another message.</span></p><p><span class="yiyi-st" id="yiyi-28">Messages may be added to a <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> instance using the set-like method <a class="reference internal" href="#mailbox.Mailbox.add" title="mailbox.Mailbox.add"><code class="xref py py-meth docutils literal"><span class="pre">add()</span></code></a> and removed using a <code class="docutils literal"><span class="pre">del</span></code> statement or the set-like methods <a class="reference internal" href="#mailbox.Mailbox.remove" title="mailbox.Mailbox.remove"><code class="xref py py-meth docutils literal"><span class="pre">remove()</span></code></a> and <a class="reference internal" href="#mailbox.Mailbox.discard" title="mailbox.Mailbox.discard"><code class="xref py py-meth docutils literal"><span class="pre">discard()</span></code></a>.</span></p><p><span class="yiyi-st" id="yiyi-29"><a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> interface semantics differ from dictionary semantics in some noteworthy ways. </span><span class="yiyi-st" id="yiyi-30">Each time a message is requested, a new representation (typically a <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> instance) is generated based upon the current state of the mailbox. </span><span class="yiyi-st" id="yiyi-31">Similarly, when a message is added to a <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> instance, the provided message representation’s contents are copied. </span><span class="yiyi-st" id="yiyi-32">In neither case is a reference to the message representation kept by the <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> instance.</span></p><p><span class="yiyi-st" id="yiyi-33">The default <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> iterator iterates over message representations, not keys as the default dictionary iterator does. </span><span class="yiyi-st" id="yiyi-34">Moreover, modification of a mailbox during iteration is safe and well-defined. </span><span class="yiyi-st" id="yiyi-35">Messages added to the mailbox after an iterator is created will not be seen by the iterator. </span><span class="yiyi-st" id="yiyi-36">Messages removed from the mailbox before the iterator yields them will be silently skipped, though using a key from an iterator may result in a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal"><span class="pre">KeyError</span></code></a> exception if the corresponding message is subsequently removed.</span></p><div class="admonition warning"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-37">Warning</span></p><p class="last"><span class="yiyi-st" id="yiyi-38">Be very cautious when modifying mailboxes that might be simultaneously changed by some other process. </span><span class="yiyi-st" id="yiyi-39">The safest mailbox format to use for such tasks is Maildir; try to avoid using single-file formats such as mbox for concurrent writing. </span><span class="yiyi-st" id="yiyi-40">If you’re modifying a mailbox, you <em>must</em> lock it by calling the <a class="reference internal" href="#mailbox.Mailbox.lock" title="mailbox.Mailbox.lock"><code class="xref py py-meth docutils literal"><span class="pre">lock()</span></code></a> and <a class="reference internal" href="#mailbox.Mailbox.unlock" title="mailbox.Mailbox.unlock"><code class="xref py py-meth docutils literal"><span class="pre">unlock()</span></code></a> methods <em>before</em> reading any messages in the file or making any changes by adding or deleting a message. </span><span class="yiyi-st" id="yiyi-41">Failing to lock the mailbox runs the risk of losing messages or corrupting the entire mailbox.</span></p></div><p><span class="yiyi-st" id="yiyi-42"><a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> instances have the following methods:</span></p><dl class="method"><dt id="mailbox.Mailbox.add"><span class="yiyi-st" id="yiyi-43"> <code class="descname">add</code><span class="sig-paren">(</span><em>message</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-44">Add <em>message</em> to the mailbox and return the key that has been assigned to it.</span></p><p><span class="yiyi-st" id="yiyi-45">Parameter <em>message</em> may be a <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> instance, an <a class="reference internal" href="email.message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal"><span class="pre">email.message.Message</span></code></a> instance, a string, a byte string, or a file-like object (which should be open in binary mode). </span><span class="yiyi-st" id="yiyi-46">If <em>message</em> is an instance of the appropriate format-specific <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> subclass (e.g., if it’s an <a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a> instance and this is an <a class="reference internal" href="#mailbox.mbox" title="mailbox.mbox"><code class="xref py py-class docutils literal"><span class="pre">mbox</span></code></a> instance), its format-specific information is used. </span><span class="yiyi-st" id="yiyi-47">Otherwise, reasonable defaults for format-specific information are used.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-48"><span class="versionmodified">Changed in version 3.2: </span>Support for binary input was added.</span></p></div></dd></dl><dl class="method"><dt id="mailbox.Mailbox.remove"><span class="yiyi-st" id="yiyi-49"> <code class="descname">remove</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dt id="mailbox.Mailbox.__delitem__"><span class="yiyi-st" id="yiyi-50"> <code class="descname">__delitem__</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dt id="mailbox.Mailbox.discard"><span class="yiyi-st" id="yiyi-51"> <code class="descname">discard</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-52">Delete the message corresponding to <em>key</em> from the mailbox.</span></p><p><span class="yiyi-st" id="yiyi-53">If no such message exists, a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal"><span class="pre">KeyError</span></code></a> exception is raised if the method was called as <a class="reference internal" href="#mailbox.Mailbox.remove" title="mailbox.Mailbox.remove"><code class="xref py py-meth docutils literal"><span class="pre">remove()</span></code></a> or <a class="reference internal" href="#mailbox.Mailbox.__delitem__" title="mailbox.Mailbox.__delitem__"><code class="xref py py-meth docutils literal"><span class="pre">__delitem__()</span></code></a> but no exception is raised if the method was called as <a class="reference internal" href="#mailbox.Mailbox.discard" title="mailbox.Mailbox.discard"><code class="xref py py-meth docutils literal"><span class="pre">discard()</span></code></a>. </span><span class="yiyi-st" id="yiyi-54">The behavior of <a class="reference internal" href="#mailbox.Mailbox.discard" title="mailbox.Mailbox.discard"><code class="xref py py-meth docutils literal"><span class="pre">discard()</span></code></a> may be preferred if the underlying mailbox format supports concurrent modification by other processes.</span></p></dd></dl><dl class="method"><dt id="mailbox.Mailbox.__setitem__"><span class="yiyi-st" id="yiyi-55"> <code class="descname">__setitem__</code><span class="sig-paren">(</span><em>key</em>, <em>message</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-56">Replace the message corresponding to <em>key</em> with <em>message</em>. </span><span class="yiyi-st" id="yiyi-57">Raise a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal"><span class="pre">KeyError</span></code></a> exception if no message already corresponds to <em>key</em>.</span></p><p><span class="yiyi-st" id="yiyi-58">As with <a class="reference internal" href="#mailbox.Mailbox.add" title="mailbox.Mailbox.add"><code class="xref py py-meth docutils literal"><span class="pre">add()</span></code></a>, parameter <em>message</em> may be a <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> instance, an <a class="reference internal" href="email.message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal"><span class="pre">email.message.Message</span></code></a> instance, a string, a byte string, or a file-like object (which should be open in binary mode). </span><span class="yiyi-st" id="yiyi-59">If <em>message</em> is an instance of the appropriate format-specific <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> subclass (e.g., if it’s an <a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a> instance and this is an <a class="reference internal" href="#mailbox.mbox" title="mailbox.mbox"><code class="xref py py-class docutils literal"><span class="pre">mbox</span></code></a> instance), its format-specific information is used. </span><span class="yiyi-st" id="yiyi-60">Otherwise, the format-specific information of the message that currently corresponds to <em>key</em> is left unchanged.</span></p></dd></dl><dl class="method"><dt id="mailbox.Mailbox.iterkeys"><span class="yiyi-st" id="yiyi-61"> <code class="descname">iterkeys</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dt id="mailbox.Mailbox.keys"><span class="yiyi-st" id="yiyi-62"> <code class="descname">keys</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-63">Return an iterator over all keys if called as <a class="reference internal" href="#mailbox.Mailbox.iterkeys" title="mailbox.Mailbox.iterkeys"><code class="xref py py-meth docutils literal"><span class="pre">iterkeys()</span></code></a> or return a list of keys if called as <a class="reference internal" href="#mailbox.Mailbox.keys" title="mailbox.Mailbox.keys"><code class="xref py py-meth docutils literal"><span class="pre">keys()</span></code></a>.</span></p></dd></dl><dl class="method"><dt id="mailbox.Mailbox.itervalues"><span class="yiyi-st" id="yiyi-64"> <code class="descname">itervalues</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dt id="mailbox.Mailbox.__iter__"><span class="yiyi-st" id="yiyi-65"> <code class="descname">__iter__</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dt id="mailbox.Mailbox.values"><span class="yiyi-st" id="yiyi-66"> <code class="descname">values</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-67">Return an iterator over representations of all messages if called as <a class="reference internal" href="#mailbox.Mailbox.itervalues" title="mailbox.Mailbox.itervalues"><code class="xref py py-meth docutils literal"><span class="pre">itervalues()</span></code></a> or <a class="reference internal" href="#mailbox.Mailbox.__iter__" title="mailbox.Mailbox.__iter__"><code class="xref py py-meth docutils literal"><span class="pre">__iter__()</span></code></a> or return a list of such representations if called as <a class="reference internal" href="#mailbox.Mailbox.values" title="mailbox.Mailbox.values"><code class="xref py py-meth docutils literal"><span class="pre">values()</span></code></a>. </span><span class="yiyi-st" id="yiyi-68">The messages are represented as instances of the appropriate format-specific <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> subclass unless a custom message factory was specified when the <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> instance was initialized.</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-69">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-70">The behavior of <a class="reference internal" href="#mailbox.Mailbox.__iter__" title="mailbox.Mailbox.__iter__"><code class="xref py py-meth docutils literal"><span class="pre">__iter__()</span></code></a> is unlike that of dictionaries, which iterate over keys.</span></p></div></dd></dl><dl class="method"><dt id="mailbox.Mailbox.iteritems"><span class="yiyi-st" id="yiyi-71"> <code class="descname">iteritems</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dt id="mailbox.Mailbox.items"><span class="yiyi-st" id="yiyi-72"> <code class="descname">items</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-73">Return an iterator over (<em>key</em>, <em>message</em>) pairs, where <em>key</em> is a key and <em>message</em> is a message representation, if called as <a class="reference internal" href="#mailbox.Mailbox.iteritems" title="mailbox.Mailbox.iteritems"><code class="xref py py-meth docutils literal"><span class="pre">iteritems()</span></code></a> or return a list of such pairs if called as <a class="reference internal" href="#mailbox.Mailbox.items" title="mailbox.Mailbox.items"><code class="xref py py-meth docutils literal"><span class="pre">items()</span></code></a>. </span><span class="yiyi-st" id="yiyi-74">The messages are represented as instances of the appropriate format-specific <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> subclass unless a custom message factory was specified when the <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> instance was initialized.</span></p></dd></dl><dl class="method"><dt id="mailbox.Mailbox.get"><span class="yiyi-st" id="yiyi-75"> <code class="descname">get</code><span class="sig-paren">(</span><em>key</em>, <em>default=None</em><span class="sig-paren">)</span></span></dt><dt id="mailbox.Mailbox.__getitem__"><span class="yiyi-st" id="yiyi-76"> <code class="descname">__getitem__</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-77">Return a representation of the message corresponding to <em>key</em>. </span><span class="yiyi-st" id="yiyi-78">If no such message exists, <em>default</em> is returned if the method was called as <a class="reference internal" href="#mailbox.Mailbox.get" title="mailbox.Mailbox.get"><code class="xref py py-meth docutils literal"><span class="pre">get()</span></code></a> and a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal"><span class="pre">KeyError</span></code></a> exception is raised if the method was called as <a class="reference internal" href="#mailbox.Mailbox.__getitem__" title="mailbox.Mailbox.__getitem__"><code class="xref py py-meth docutils literal"><span class="pre">__getitem__()</span></code></a>. </span><span class="yiyi-st" id="yiyi-79">The message is represented as an instance of the appropriate format-specific <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> subclass unless a custom message factory was specified when the <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> instance was initialized.</span></p></dd></dl><dl class="method"><dt id="mailbox.Mailbox.get_message"><span class="yiyi-st" id="yiyi-80"> <code class="descname">get_message</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-81">Return a representation of the message corresponding to <em>key</em> as an instance of the appropriate format-specific <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> subclass, or raise a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal"><span class="pre">KeyError</span></code></a> exception if no such message exists.</span></p></dd></dl><dl class="method"><dt id="mailbox.Mailbox.get_bytes"><span class="yiyi-st" id="yiyi-82"> <code class="descname">get_bytes</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-83">Return a byte representation of the message corresponding to <em>key</em>, or raise a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal"><span class="pre">KeyError</span></code></a> exception if no such message exists.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-84"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl><dl class="method"><dt id="mailbox.Mailbox.get_string"><span class="yiyi-st" id="yiyi-85"> <code class="descname">get_string</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-86">Return a string representation of the message corresponding to <em>key</em>, or raise a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal"><span class="pre">KeyError</span></code></a> exception if no such message exists. </span><span class="yiyi-st" id="yiyi-87">The message is processed through <a class="reference internal" href="email.message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal"><span class="pre">email.message.Message</span></code></a> to convert it to a 7bit clean representation.</span></p></dd></dl><dl class="method"><dt id="mailbox.Mailbox.get_file"><span class="yiyi-st" id="yiyi-88"> <code class="descname">get_file</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-89">Return a file-like representation of the message corresponding to <em>key</em>, or raise a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal"><span class="pre">KeyError</span></code></a> exception if no such message exists. </span><span class="yiyi-st" id="yiyi-90">The file-like object behaves as if open in binary mode. </span><span class="yiyi-st" id="yiyi-91">This file should be closed once it is no longer needed.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-92"><span class="versionmodified">Changed in version 3.2: </span>The file object really is a binary file; previously it was incorrectly returned in text mode. </span><span class="yiyi-st" id="yiyi-93">Also, the file-like object now supports the context management protocol: you can use a <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal"><span class="pre">with</span></code></a> statement to automatically close it.</span></p></div><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-94">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-95">Unlike other representations of messages, file-like representations are not necessarily independent of the <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> instance that created them or of the underlying mailbox. </span><span class="yiyi-st" id="yiyi-96">More specific documentation is provided by each subclass.</span></p></div></dd></dl><dl class="method"><dt id="mailbox.Mailbox.__contains__"><span class="yiyi-st" id="yiyi-97"> <code class="descname">__contains__</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-98">Return <code class="docutils literal"><span class="pre">True</span></code> if <em>key</em> corresponds to a message, <code class="docutils literal"><span class="pre">False</span></code> otherwise.</span></p></dd></dl><dl class="method"><dt id="mailbox.Mailbox.__len__"><span class="yiyi-st" id="yiyi-99"> <code class="descname">__len__</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-100">Return a count of messages in the mailbox.</span></p></dd></dl><dl class="method"><dt id="mailbox.Mailbox.clear"><span class="yiyi-st" id="yiyi-101"> <code class="descname">clear</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-102">Delete all messages from the mailbox.</span></p></dd></dl><dl class="method"><dt id="mailbox.Mailbox.pop"><span class="yiyi-st" id="yiyi-103"> <code class="descname">pop</code><span class="sig-paren">(</span><em>key</em>, <em>default=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-104">Return a representation of the message corresponding to <em>key</em> and delete the message. </span><span class="yiyi-st" id="yiyi-105">If no such message exists, return <em>default</em>. </span><span class="yiyi-st" id="yiyi-106">The message is represented as an instance of the appropriate format-specific <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> subclass unless a custom message factory was specified when the <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> instance was initialized.</span></p></dd></dl><dl class="method"><dt id="mailbox.Mailbox.popitem"><span class="yiyi-st" id="yiyi-107"> <code class="descname">popitem</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-108">Return an arbitrary (<em>key</em>, <em>message</em>) pair, where <em>key</em> is a key and <em>message</em> is a message representation, and delete the corresponding message. </span><span class="yiyi-st" id="yiyi-109">If the mailbox is empty, raise a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal"><span class="pre">KeyError</span></code></a> exception. </span><span class="yiyi-st" id="yiyi-110">The message is represented as an instance of the appropriate format-specific <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> subclass unless a custom message factory was specified when the <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> instance was initialized.</span></p></dd></dl><dl class="method"><dt id="mailbox.Mailbox.update"><span class="yiyi-st" id="yiyi-111"> <code class="descname">update</code><span class="sig-paren">(</span><em>arg</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-112">Parameter <em>arg</em> should be a <em>key</em>-to-<em>message</em> mapping or an iterable of (<em>key</em>, <em>message</em>) pairs. </span><span class="yiyi-st" id="yiyi-113">Updates the mailbox so that, for each given <em>key</em> and <em>message</em>, the message corresponding to <em>key</em> is set to <em>message</em> as if by using <a class="reference internal" href="#mailbox.Mailbox.__setitem__" title="mailbox.Mailbox.__setitem__"><code class="xref py py-meth docutils literal"><span class="pre">__setitem__()</span></code></a>. </span><span class="yiyi-st" id="yiyi-114">As with <a class="reference internal" href="#mailbox.Mailbox.__setitem__" title="mailbox.Mailbox.__setitem__"><code class="xref py py-meth docutils literal"><span class="pre">__setitem__()</span></code></a>, each <em>key</em> must already correspond to a message in the mailbox or else a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal"><span class="pre">KeyError</span></code></a> exception will be raised, so in general it is incorrect for <em>arg</em> to be a <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> instance.</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-115">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-116">Unlike with dictionaries, keyword arguments are not supported.</span></p></div></dd></dl><dl class="method"><dt id="mailbox.Mailbox.flush"><span class="yiyi-st" id="yiyi-117"> <code class="descname">flush</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-118">Write any pending changes to the filesystem. </span><span class="yiyi-st" id="yiyi-119">For some <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> subclasses, changes are always written immediately and <a class="reference internal" href="#mailbox.Mailbox.flush" title="mailbox.Mailbox.flush"><code class="xref py py-meth docutils literal"><span class="pre">flush()</span></code></a> does nothing, but you should still make a habit of calling this method.</span></p></dd></dl><dl class="method"><dt id="mailbox.Mailbox.lock"><span class="yiyi-st" id="yiyi-120"> <code class="descname">lock</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-121">Acquire an exclusive advisory lock on the mailbox so that other processes know not to modify it. </span><span class="yiyi-st" id="yiyi-122">An <a class="reference internal" href="#mailbox.ExternalClashError" title="mailbox.ExternalClashError"><code class="xref py py-exc docutils literal"><span class="pre">ExternalClashError</span></code></a> is raised if the lock is not available. </span><span class="yiyi-st" id="yiyi-123">The particular locking mechanisms used depend upon the mailbox format. </span><span class="yiyi-st" id="yiyi-124">You should <em>always</em> lock the mailbox before making any modifications to its contents.</span></p></dd></dl><dl class="method"><dt id="mailbox.Mailbox.unlock"><span class="yiyi-st" id="yiyi-125"> <code class="descname">unlock</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-126">Release the lock on the mailbox, if any.</span></p></dd></dl><dl class="method"><dt id="mailbox.Mailbox.close"><span class="yiyi-st" id="yiyi-127"> <code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-128">Flush the mailbox, unlock it if necessary, and close any open files. </span><span class="yiyi-st" id="yiyi-129">For some <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> subclasses, this method does nothing.</span></p></dd></dl></dd></dl><div class="section" id="maildir"><h3><span class="yiyi-st" id="yiyi-130">19.4.1.1. </span><span class="yiyi-st" id="yiyi-131"><a class="reference internal" href="#mailbox.Maildir" title="mailbox.Maildir"><code class="xref py py-class docutils literal"><span class="pre">Maildir</span></code></a></span></h3><dl class="class"><dt id="mailbox.Maildir"><span class="yiyi-st" id="yiyi-132"> <em class="property">class </em><code class="descclassname">mailbox.</code><code class="descname">Maildir</code><span class="sig-paren">(</span><em>dirname</em>, <em>factory=None</em>, <em>create=True</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-133">A subclass of <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> for mailboxes in Maildir format. </span><span class="yiyi-st" id="yiyi-134">Parameter <em>factory</em> is a callable object that accepts a file-like message representation (which behaves as if opened in binary mode) and returns a custom representation. </span><span class="yiyi-st" id="yiyi-135">If <em>factory</em> is <code class="docutils literal"><span class="pre">None</span></code>, <a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal"><span class="pre">MaildirMessage</span></code></a> is used as the default message representation. </span><span class="yiyi-st" id="yiyi-136">If <em>create</em> is <code class="docutils literal"><span class="pre">True</span></code>, the mailbox is created if it does not exist.</span></p><p><span class="yiyi-st" id="yiyi-137">It is for historical reasons that <em>dirname</em> is named as such rather than <em>path</em>.</span></p><p><span class="yiyi-st" id="yiyi-138">Maildir is a directory-based mailbox format invented for the qmail mail transfer agent and now widely supported by other programs. </span><span class="yiyi-st" id="yiyi-139">Messages in a Maildir mailbox are stored in separate files within a common directory structure. </span><span class="yiyi-st" id="yiyi-140">This design allows Maildir mailboxes to be accessed and modified by multiple unrelated programs without data corruption, so file locking is unnecessary.</span></p><p><span class="yiyi-st" id="yiyi-141">Maildir mailboxes contain three subdirectories, namely: <code class="file docutils literal"><span class="pre">tmp</span></code>, <code class="file docutils literal"><span class="pre">new</span></code>, and <code class="file docutils literal"><span class="pre">cur</span></code>. </span><span class="yiyi-st" id="yiyi-142">Messages are created momentarily in the <code class="file docutils literal"><span class="pre">tmp</span></code> subdirectory and then moved to the <code class="file docutils literal"><span class="pre">new</span></code> subdirectory to finalize delivery. </span><span class="yiyi-st" id="yiyi-143">A mail user agent may subsequently move the message to the <code class="file docutils literal"><span class="pre">cur</span></code> subdirectory and store information about the state of the message in a special “info” section appended to its file name.</span></p><p><span class="yiyi-st" id="yiyi-144">Folders of the style introduced by the Courier mail transfer agent are also supported. </span><span class="yiyi-st" id="yiyi-145">Any subdirectory of the main mailbox is considered a folder if <code class="docutils literal"><span class="pre">'.'</span></code></span><span class="yiyi-st" id="yiyi-146"> is the first character in its name. </span><span class="yiyi-st" id="yiyi-147">Folder names are represented by <a class="reference internal" href="#mailbox.Maildir" title="mailbox.Maildir"><code class="xref py py-class docutils literal"><span class="pre">Maildir</span></code></a> without the leading <code class="docutils literal"><span class="pre">'.'</span></code>. </span><span class="yiyi-st" id="yiyi-148">Each folder is itself a Maildir mailbox but should not contain other folders. </span><span class="yiyi-st" id="yiyi-149">Instead, a logical nesting is indicated using <code class="docutils literal"><span class="pre">'.'</span></code></span><span class="yiyi-st" id="yiyi-150"> to delimit levels, e.g., “Archived.2005.07”.</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-151">Note</span></p><p><span class="yiyi-st" id="yiyi-152">The Maildir specification requires the use of a colon (<code class="docutils literal"><span class="pre">':'</span></code>) in certain message file names. </span><span class="yiyi-st" id="yiyi-153">However, some operating systems do not permit this character in file names, If you wish to use a Maildir-like format on such an operating system, you should specify another character to use instead. </span><span class="yiyi-st" id="yiyi-154">The exclamation point (<code class="docutils literal"><span class="pre">'!'</span></code>) is a popular choice. </span><span class="yiyi-st" id="yiyi-155">For example:</span></p><pre><code class="language-python"><span></span><span class="kn">import</span> <span class="nn">mailbox</span>
<span class="n">mailbox</span><span class="o">.</span><span class="n">Maildir</span><span class="o">.</span><span class="n">colon</span> <span class="o">=</span> <span class="s1">'!'</span>
</code></pre><p class="last"><span class="yiyi-st" id="yiyi-156">The <code class="xref py py-attr docutils literal"><span class="pre">colon</span></code> attribute may also be set on a per-instance basis.</span></p></div><p><span class="yiyi-st" id="yiyi-157"><a class="reference internal" href="#mailbox.Maildir" title="mailbox.Maildir"><code class="xref py py-class docutils literal"><span class="pre">Maildir</span></code></a> instances have all of the methods of <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> in addition to the following:</span></p><dl class="method"><dt id="mailbox.Maildir.list_folders"><span class="yiyi-st" id="yiyi-158"> <code class="descname">list_folders</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-159">Return a list of the names of all folders.</span></p></dd></dl><dl class="method"><dt id="mailbox.Maildir.get_folder"><span class="yiyi-st" id="yiyi-160"> <code class="descname">get_folder</code><span class="sig-paren">(</span><em>folder</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-161">Return a <a class="reference internal" href="#mailbox.Maildir" title="mailbox.Maildir"><code class="xref py py-class docutils literal"><span class="pre">Maildir</span></code></a> instance representing the folder whose name is <em>folder</em>. </span><span class="yiyi-st" id="yiyi-162">A <a class="reference internal" href="#mailbox.NoSuchMailboxError" title="mailbox.NoSuchMailboxError"><code class="xref py py-exc docutils literal"><span class="pre">NoSuchMailboxError</span></code></a> exception is raised if the folder does not exist.</span></p></dd></dl><dl class="method"><dt id="mailbox.Maildir.add_folder"><span class="yiyi-st" id="yiyi-163"> <code class="descname">add_folder</code><span class="sig-paren">(</span><em>folder</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-164">Create a folder whose name is <em>folder</em> and return a <a class="reference internal" href="#mailbox.Maildir" title="mailbox.Maildir"><code class="xref py py-class docutils literal"><span class="pre">Maildir</span></code></a> instance representing it.</span></p></dd></dl><dl class="method"><dt id="mailbox.Maildir.remove_folder"><span class="yiyi-st" id="yiyi-165"> <code class="descname">remove_folder</code><span class="sig-paren">(</span><em>folder</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-166">Delete the folder whose name is <em>folder</em>. </span><span class="yiyi-st" id="yiyi-167">If the folder contains any messages, a <a class="reference internal" href="#mailbox.NotEmptyError" title="mailbox.NotEmptyError"><code class="xref py py-exc docutils literal"><span class="pre">NotEmptyError</span></code></a> exception will be raised and the folder will not be deleted.</span></p></dd></dl><dl class="method"><dt id="mailbox.Maildir.clean"><span class="yiyi-st" id="yiyi-168"> <code class="descname">clean</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-169">Delete temporary files from the mailbox that have not been accessed in the last 36 hours. </span><span class="yiyi-st" id="yiyi-170">The Maildir specification says that mail-reading programs should do this occasionally.</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-171">Some <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> methods implemented by <a class="reference internal" href="#mailbox.Maildir" title="mailbox.Maildir"><code class="xref py py-class docutils literal"><span class="pre">Maildir</span></code></a> deserve special remarks:</span></p><dl class="method"><dt id="mailbox.Maildir.add"><span class="yiyi-st" id="yiyi-172"> <code class="descname">add</code><span class="sig-paren">(</span><em>message</em><span class="sig-paren">)</span></span></dt><dt id="mailbox.Maildir.__setitem__"><span class="yiyi-st" id="yiyi-173"> <code class="descname">__setitem__</code><span class="sig-paren">(</span><em>key</em>, <em>message</em><span class="sig-paren">)</span></span></dt><dt id="mailbox.Maildir.update"><span class="yiyi-st" id="yiyi-174"> <code class="descname">update</code><span class="sig-paren">(</span><em>arg</em><span class="sig-paren">)</span></span></dt><dd><div class="admonition warning"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-175">Warning</span></p><p class="last"><span class="yiyi-st" id="yiyi-176">These methods generate unique file names based upon the current process ID. </span><span class="yiyi-st" id="yiyi-177">When using multiple threads, undetected name clashes may occur and cause corruption of the mailbox unless threads are coordinated to avoid using these methods to manipulate the same mailbox simultaneously.</span></p></div></dd></dl><dl class="method"><dt id="mailbox.Maildir.flush"><span class="yiyi-st" id="yiyi-178"> <code class="descname">flush</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-179">All changes to Maildir mailboxes are immediately applied, so this method does nothing.</span></p></dd></dl><dl class="method"><dt id="mailbox.Maildir.lock"><span class="yiyi-st" id="yiyi-180"> <code class="descname">lock</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dt id="mailbox.Maildir.unlock"><span class="yiyi-st" id="yiyi-181"> <code class="descname">unlock</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-182">Maildir mailboxes do not support (or require) locking, so these methods do nothing.</span></p></dd></dl><dl class="method"><dt id="mailbox.Maildir.close"><span class="yiyi-st" id="yiyi-183"> <code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-184"><a class="reference internal" href="#mailbox.Maildir" title="mailbox.Maildir"><code class="xref py py-class docutils literal"><span class="pre">Maildir</span></code></a> instances do not keep any open files and the underlying mailboxes do not support locking, so this method does nothing.</span></p></dd></dl><dl class="method"><dt id="mailbox.Maildir.get_file"><span class="yiyi-st" id="yiyi-185"> <code class="descname">get_file</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-186">Depending upon the host platform, it may not be possible to modify or remove the underlying message while the returned file remains open.</span></p></dd></dl></dd></dl><div class="admonition seealso"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-187">See also</span></p><dl class="last docutils"><dt><span class="yiyi-st" id="yiyi-188"><a class="reference external" href="http://www.qmail.org/man/man5/maildir.html">maildir man page from qmail</a></span></dt><dd><span class="yiyi-st" id="yiyi-189">The original specification of the format.</span></dd><dt><span class="yiyi-st" id="yiyi-190"><a class="reference external" href="https://cr.yp.to/proto/maildir.html">Using maildir format</a></span></dt><dd><span class="yiyi-st" id="yiyi-191">Notes on Maildir by its inventor. </span><span class="yiyi-st" id="yiyi-192">Includes an updated name-creation scheme and details on “info” semantics.</span></dd><dt><span class="yiyi-st" id="yiyi-193"><a class="reference external" href="http://www.courier-mta.org/maildir.html">maildir man page from Courier</a></span></dt><dd><span class="yiyi-st" id="yiyi-194">Another specification of the format. </span><span class="yiyi-st" id="yiyi-195">Describes a common extension for supporting folders.</span></dd></dl></div></div><div class="section" id="mbox"><h3><span class="yiyi-st" id="yiyi-196">19.4.1.2. <a class="reference internal" href="#mailbox.mbox" title="mailbox.mbox"><code class="xref py py-class docutils literal"><span class="pre">mbox</span></code></a></span></h3><dl class="class"><dt id="mailbox.mbox"><span class="yiyi-st" id="yiyi-197"> <em class="property">class </em><code class="descclassname">mailbox.</code><code class="descname">mbox</code><span class="sig-paren">(</span><em>path</em>, <em>factory=None</em>, <em>create=True</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-198">A subclass of <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> for mailboxes in mbox format. </span><span class="yiyi-st" id="yiyi-199">Parameter <em>factory</em> is a callable object that accepts a file-like message representation (which behaves as if opened in binary mode) and returns a custom representation. </span><span class="yiyi-st" id="yiyi-200">If <em>factory</em> is <code class="docutils literal"><span class="pre">None</span></code>, <a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a> is used as the default message representation. </span><span class="yiyi-st" id="yiyi-201">If <em>create</em> is <code class="docutils literal"><span class="pre">True</span></code>, the mailbox is created if it does not exist.</span></p><p><span class="yiyi-st" id="yiyi-202">The mbox format is the classic format for storing mail on Unix systems. </span><span class="yiyi-st" id="yiyi-203">All messages in an mbox mailbox are stored in a single file with the beginning of each message indicated by a line whose first five characters are “From ”.</span></p><p><span class="yiyi-st" id="yiyi-204">Several variations of the mbox format exist to address perceived shortcomings in the original. </span><span class="yiyi-st" id="yiyi-205">In the interest of compatibility, <a class="reference internal" href="#mailbox.mbox" title="mailbox.mbox"><code class="xref py py-class docutils literal"><span class="pre">mbox</span></code></a> implements the original format, which is sometimes referred to as <em class="dfn">mboxo</em>. </span><span class="yiyi-st" id="yiyi-206">This means that the <em class="mailheader">Content-Length</em> header, if present, is ignored and that any occurrences of “From ” at the beginning of a line in a message body are transformed to “&gt;From ” when storing the message, although occurrences of “&gt;From ” are not transformed to “From ” when reading the message.</span></p><p><span class="yiyi-st" id="yiyi-207">Some <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> methods implemented by <a class="reference internal" href="#mailbox.mbox" title="mailbox.mbox"><code class="xref py py-class docutils literal"><span class="pre">mbox</span></code></a> deserve special remarks:</span></p><dl class="method"><dt id="mailbox.mbox.get_file"><span class="yiyi-st" id="yiyi-208"> <code class="descname">get_file</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-209">Using the file after calling <code class="xref py py-meth docutils literal"><span class="pre">flush()</span></code> or <code class="xref py py-meth docutils literal"><span class="pre">close()</span></code> on the <a class="reference internal" href="#mailbox.mbox" title="mailbox.mbox"><code class="xref py py-class docutils literal"><span class="pre">mbox</span></code></a> instance may yield unpredictable results or raise an exception.</span></p></dd></dl><dl class="method"><dt id="mailbox.mbox.lock"><span class="yiyi-st" id="yiyi-210"> <code class="descname">lock</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dt id="mailbox.mbox.unlock"><span class="yiyi-st" id="yiyi-211"> <code class="descname">unlock</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-212">Three locking mechanisms are used—dot locking and, if available, the <code class="xref c c-func docutils literal"><span class="pre">flock()</span></code> and <code class="xref c c-func docutils literal"><span class="pre">lockf()</span></code> system calls.</span></p></dd></dl></dd></dl><div class="admonition seealso"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-213">See also</span></p><dl class="last docutils"><dt><span class="yiyi-st" id="yiyi-214"><a class="reference external" href="http://www.qmail.org/man/man5/mbox.html">mbox man page from qmail</a></span></dt><dd><span class="yiyi-st" id="yiyi-215">A specification of the format and its variations.</span></dd><dt><span class="yiyi-st" id="yiyi-216"><a class="reference external" href="http://www.tin.org/bin/man.cgi?section=5&amp;topic=mbox">mbox man page from tin</a></span></dt><dd><span class="yiyi-st" id="yiyi-217">Another specification of the format, with details on locking.</span></dd><dt><span class="yiyi-st" id="yiyi-218"><a class="reference external" href="https://www.jwz.org/doc/content-length.html">Configuring Netscape Mail on Unix: Why The Content-Length Format is Bad</a></span></dt><dd><span class="yiyi-st" id="yiyi-219">An argument for using the original mbox format rather than a variation.</span></dd><dt><span class="yiyi-st" id="yiyi-220"><a class="reference external" href="http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html">“mbox” is a family of several mutually incompatible mailbox formats</a></span></dt><dd><span class="yiyi-st" id="yiyi-221">A history of mbox variations.</span></dd></dl></div></div><div class="section" id="mh"><h3><span class="yiyi-st" id="yiyi-222">19.4.1.3. </span><span class="yiyi-st" id="yiyi-223"><a class="reference internal" href="#mailbox.MH" title="mailbox.MH"><code class="xref py py-class docutils literal"><span class="pre">MH</span></code></a></span></h3><dl class="class"><dt id="mailbox.MH"><span class="yiyi-st" id="yiyi-224"> <em class="property">class </em><code class="descclassname">mailbox.</code><code class="descname">MH</code><span class="sig-paren">(</span><em>path</em>, <em>factory=None</em>, <em>create=True</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-225">A subclass of <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> for mailboxes in MH format. </span><span class="yiyi-st" id="yiyi-226">Parameter <em>factory</em> is a callable object that accepts a file-like message representation (which behaves as if opened in binary mode) and returns a custom representation. </span><span class="yiyi-st" id="yiyi-227">If <em>factory</em> is <code class="docutils literal"><span class="pre">None</span></code>, <a class="reference internal" href="#mailbox.MHMessage" title="mailbox.MHMessage"><code class="xref py py-class docutils literal"><span class="pre">MHMessage</span></code></a> is used as the default message representation. </span><span class="yiyi-st" id="yiyi-228">If <em>create</em> is <code class="docutils literal"><span class="pre">True</span></code>, the mailbox is created if it does not exist.</span></p><p><span class="yiyi-st" id="yiyi-229">MH is a directory-based mailbox format invented for the MH Message Handling System, a mail user agent. </span><span class="yiyi-st" id="yiyi-230">Each message in an MH mailbox resides in its own file. </span><span class="yiyi-st" id="yiyi-231">An MH mailbox may contain other MH mailboxes (called <em class="dfn">folders</em>) in addition to messages. </span><span class="yiyi-st" id="yiyi-232">Folders may be nested indefinitely. </span><span class="yiyi-st" id="yiyi-233">MH mailboxes also support <em class="dfn">sequences</em>, which are named lists used to logically group messages without moving them to sub-folders. </span><span class="yiyi-st" id="yiyi-234">Sequences are defined in a file called <code class="file docutils literal"><span class="pre">.mh_sequences</span></code> in each folder.</span></p><p><span class="yiyi-st" id="yiyi-235">The <a class="reference internal" href="#mailbox.MH" title="mailbox.MH"><code class="xref py py-class docutils literal"><span class="pre">MH</span></code></a> class manipulates MH mailboxes, but it does not attempt to emulate all of <strong class="program">mh</strong>‘s behaviors. </span><span class="yiyi-st" id="yiyi-236">In particular, it does not modify and is not affected by the <code class="file docutils literal"><span class="pre">context</span></code> or <code class="file docutils literal"><span class="pre">.mh_profile</span></code> files that are used by <strong class="program">mh</strong> to store its state and configuration.</span></p><p><span class="yiyi-st" id="yiyi-237"><a class="reference internal" href="#mailbox.MH" title="mailbox.MH"><code class="xref py py-class docutils literal"><span class="pre">MH</span></code></a> instances have all of the methods of <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> in addition to the following:</span></p><dl class="method"><dt id="mailbox.MH.list_folders"><span class="yiyi-st" id="yiyi-238"> <code class="descname">list_folders</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-239">Return a list of the names of all folders.</span></p></dd></dl><dl class="method"><dt id="mailbox.MH.get_folder"><span class="yiyi-st" id="yiyi-240"> <code class="descname">get_folder</code><span class="sig-paren">(</span><em>folder</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-241">Return an <a class="reference internal" href="#mailbox.MH" title="mailbox.MH"><code class="xref py py-class docutils literal"><span class="pre">MH</span></code></a> instance representing the folder whose name is <em>folder</em>. </span><span class="yiyi-st" id="yiyi-242">A <a class="reference internal" href="#mailbox.NoSuchMailboxError" title="mailbox.NoSuchMailboxError"><code class="xref py py-exc docutils literal"><span class="pre">NoSuchMailboxError</span></code></a> exception is raised if the folder does not exist.</span></p></dd></dl><dl class="method"><dt id="mailbox.MH.add_folder"><span class="yiyi-st" id="yiyi-243"> <code class="descname">add_folder</code><span class="sig-paren">(</span><em>folder</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-244">Create a folder whose name is <em>folder</em> and return an <a class="reference internal" href="#mailbox.MH" title="mailbox.MH"><code class="xref py py-class docutils literal"><span class="pre">MH</span></code></a> instance representing it.</span></p></dd></dl><dl class="method"><dt id="mailbox.MH.remove_folder"><span class="yiyi-st" id="yiyi-245"> <code class="descname">remove_folder</code><span class="sig-paren">(</span><em>folder</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-246">Delete the folder whose name is <em>folder</em>. </span><span class="yiyi-st" id="yiyi-247">If the folder contains any messages, a <a class="reference internal" href="#mailbox.NotEmptyError" title="mailbox.NotEmptyError"><code class="xref py py-exc docutils literal"><span class="pre">NotEmptyError</span></code></a> exception will be raised and the folder will not be deleted.</span></p></dd></dl><dl class="method"><dt id="mailbox.MH.get_sequences"><span class="yiyi-st" id="yiyi-248"> <code class="descname">get_sequences</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-249">Return a dictionary of sequence names mapped to key lists. </span><span class="yiyi-st" id="yiyi-250">If there are no sequences, the empty dictionary is returned.</span></p></dd></dl><dl class="method"><dt id="mailbox.MH.set_sequences"><span class="yiyi-st" id="yiyi-251"> <code class="descname">set_sequences</code><span class="sig-paren">(</span><em>sequences</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-252">Re-define the sequences that exist in the mailbox based upon <em>sequences</em>, a dictionary of names mapped to key lists, like returned by <a class="reference internal" href="#mailbox.MH.get_sequences" title="mailbox.MH.get_sequences"><code class="xref py py-meth docutils literal"><span class="pre">get_sequences()</span></code></a>.</span></p></dd></dl><dl class="method"><dt id="mailbox.MH.pack"><span class="yiyi-st" id="yiyi-253"> <code class="descname">pack</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-254">Rename messages in the mailbox as necessary to eliminate gaps in numbering. </span><span class="yiyi-st" id="yiyi-255">Entries in the sequences list are updated correspondingly.</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-256">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-257">Already-issued keys are invalidated by this operation and should not be subsequently used.</span></p></div></dd></dl><p><span class="yiyi-st" id="yiyi-258">Some <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> methods implemented by <a class="reference internal" href="#mailbox.MH" title="mailbox.MH"><code class="xref py py-class docutils literal"><span class="pre">MH</span></code></a> deserve special remarks:</span></p><dl class="method"><dt id="mailbox.MH.remove"><span class="yiyi-st" id="yiyi-259"> <code class="descname">remove</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dt id="mailbox.MH.__delitem__"><span class="yiyi-st" id="yiyi-260"> <code class="descname">__delitem__</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dt id="mailbox.MH.discard"><span class="yiyi-st" id="yiyi-261"> <code class="descname">discard</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-262">These methods immediately delete the message. </span><span class="yiyi-st" id="yiyi-263">The MH convention of marking a message for deletion by prepending a comma to its name is not used.</span></p></dd></dl><dl class="method"><dt id="mailbox.MH.lock"><span class="yiyi-st" id="yiyi-264"> <code class="descname">lock</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dt id="mailbox.MH.unlock"><span class="yiyi-st" id="yiyi-265"> <code class="descname">unlock</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-266">Three locking mechanisms are used—dot locking and, if available, the <code class="xref c c-func docutils literal"><span class="pre">flock()</span></code> and <code class="xref c c-func docutils literal"><span class="pre">lockf()</span></code> system calls. </span><span class="yiyi-st" id="yiyi-267">For MH mailboxes, locking the mailbox means locking the <code class="file docutils literal"><span class="pre">.mh_sequences</span></code> file and, only for the duration of any operations that affect them, locking individual message files.</span></p></dd></dl><dl class="method"><dt id="mailbox.MH.get_file"><span class="yiyi-st" id="yiyi-268"> <code class="descname">get_file</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-269">Depending upon the host platform, it may not be possible to remove the underlying message while the returned file remains open.</span></p></dd></dl><dl class="method"><dt id="mailbox.MH.flush"><span class="yiyi-st" id="yiyi-270"> <code class="descname">flush</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-271">All changes to MH mailboxes are immediately applied, so this method does nothing.</span></p></dd></dl><dl class="method"><dt id="mailbox.MH.close"><span class="yiyi-st" id="yiyi-272"> <code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-273"><a class="reference internal" href="#mailbox.MH" title="mailbox.MH"><code class="xref py py-class docutils literal"><span class="pre">MH</span></code></a> instances do not keep any open files, so this method is equivalent to <a class="reference internal" href="#mailbox.MH.unlock" title="mailbox.MH.unlock"><code class="xref py py-meth docutils literal"><span class="pre">unlock()</span></code></a>.</span></p></dd></dl></dd></dl><div class="admonition seealso"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-274">See also</span></p><dl class="last docutils"><dt><span class="yiyi-st" id="yiyi-275"><a class="reference external" href="http://www.nongnu.org/nmh/">nmh - Message Handling System</a></span></dt><dd><span class="yiyi-st" id="yiyi-276">Home page of <strong class="program">nmh</strong>, an updated version of the original <strong class="program">mh</strong>.</span></dd><dt><span class="yiyi-st" id="yiyi-277"><a class="reference external" href="http://rand-mh.sourceforge.net/book/">MH &amp; nmh: Email for Users &amp; Programmers</a></span></dt><dd><span class="yiyi-st" id="yiyi-278">A GPL-licensed book on <strong class="program">mh</strong> and <strong class="program">nmh</strong>, with some information on the mailbox format.</span></dd></dl></div></div><div class="section" id="babyl"><h3><span class="yiyi-st" id="yiyi-279">19.4.1.4. </span><span class="yiyi-st" id="yiyi-280"><a class="reference internal" href="#mailbox.Babyl" title="mailbox.Babyl"><code class="xref py py-class docutils literal"><span class="pre">Babyl</span></code></a></span></h3><dl class="class"><dt id="mailbox.Babyl"><span class="yiyi-st" id="yiyi-281"> <em class="property">class </em><code class="descclassname">mailbox.</code><code class="descname">Babyl</code><span class="sig-paren">(</span><em>path</em>, <em>factory=None</em>, <em>create=True</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-282">A subclass of <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> for mailboxes in Babyl format. </span><span class="yiyi-st" id="yiyi-283">Parameter <em>factory</em> is a callable object that accepts a file-like message representation (which behaves as if opened in binary mode) and returns a custom representation. </span><span class="yiyi-st" id="yiyi-284">If <em>factory</em> is <code class="docutils literal"><span class="pre">None</span></code>, <a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal"><span class="pre">BabylMessage</span></code></a> is used as the default message representation. </span><span class="yiyi-st" id="yiyi-285">If <em>create</em> is <code class="docutils literal"><span class="pre">True</span></code>, the mailbox is created if it does not exist.</span></p><p><span class="yiyi-st" id="yiyi-286">Babyl is a single-file mailbox format used by the Rmail mail user agent included with Emacs. </span><span class="yiyi-st" id="yiyi-287">The beginning of a message is indicated by a line containing the two characters Control-Underscore (<code class="docutils literal"><span class="pre">'\037'</span></code>) and Control-L (<code class="docutils literal"><span class="pre">'\014'</span></code>). </span><span class="yiyi-st" id="yiyi-288">The end of a message is indicated by the start of the next message or, in the case of the last message, a line containing a Control-Underscore (<code class="docutils literal"><span class="pre">'\037'</span></code>) character.</span></p><p><span class="yiyi-st" id="yiyi-289">Messages in a Babyl mailbox have two sets of headers, original headers and so-called visible headers. </span><span class="yiyi-st" id="yiyi-290">Visible headers are typically a subset of the original headers that have been reformatted or abridged to be more attractive. </span><span class="yiyi-st" id="yiyi-291">Each message in a Babyl mailbox also has an accompanying list of <em class="dfn">labels</em>, or short strings that record extra information about the message, and a list of all user-defined labels found in the mailbox is kept in the Babyl options section.</span></p><p><span class="yiyi-st" id="yiyi-292"><a class="reference internal" href="#mailbox.Babyl" title="mailbox.Babyl"><code class="xref py py-class docutils literal"><span class="pre">Babyl</span></code></a> instances have all of the methods of <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> in addition to the following:</span></p><dl class="method"><dt id="mailbox.Babyl.get_labels"><span class="yiyi-st" id="yiyi-293"> <code class="descname">get_labels</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-294">Return a list of the names of all user-defined labels used in the mailbox.</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-295">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-296">The actual messages are inspected to determine which labels exist in the mailbox rather than consulting the list of labels in the Babyl options section, but the Babyl section is updated whenever the mailbox is modified.</span></p></div></dd></dl><p><span class="yiyi-st" id="yiyi-297">Some <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> methods implemented by <a class="reference internal" href="#mailbox.Babyl" title="mailbox.Babyl"><code class="xref py py-class docutils literal"><span class="pre">Babyl</span></code></a> deserve special remarks:</span></p><dl class="method"><dt id="mailbox.Babyl.get_file"><span class="yiyi-st" id="yiyi-298"> <code class="descname">get_file</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-299">In Babyl mailboxes, the headers of a message are not stored contiguously with the body of the message. </span><span class="yiyi-st" id="yiyi-300">To generate a file-like representation, the headers and body are copied together into an <a class="reference internal" href="io.html#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal"><span class="pre">io.BytesIO</span></code></a> instance, which has an API identical to that of a file. </span><span class="yiyi-st" id="yiyi-301">As a result, the file-like object is truly independent of the underlying mailbox but does not save memory compared to a string representation.</span></p></dd></dl><dl class="method"><dt id="mailbox.Babyl.lock"><span class="yiyi-st" id="yiyi-302"> <code class="descname">lock</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dt id="mailbox.Babyl.unlock"><span class="yiyi-st" id="yiyi-303"> <code class="descname">unlock</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-304">Three locking mechanisms are used—dot locking and, if available, the <code class="xref c c-func docutils literal"><span class="pre">flock()</span></code> and <code class="xref c c-func docutils literal"><span class="pre">lockf()</span></code> system calls.</span></p></dd></dl></dd></dl><div class="admonition seealso"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-305">See also</span></p><dl class="last docutils"><dt><span class="yiyi-st" id="yiyi-306"><a class="reference external" href="https://quimby.gnus.org/notes/BABYL">Format of Version 5 Babyl Files</a></span></dt><dd><span class="yiyi-st" id="yiyi-307">A specification of the Babyl format.</span></dd><dt><span class="yiyi-st" id="yiyi-308"><a class="reference external" href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Rmail.html">Reading Mail with Rmail</a></span></dt><dd><span class="yiyi-st" id="yiyi-309">The Rmail manual, with some information on Babyl semantics.</span></dd></dl></div></div><div class="section" id="mmdf"><h3><span class="yiyi-st" id="yiyi-310">19.4.1.5. </span><span class="yiyi-st" id="yiyi-311"><a class="reference internal" href="#mailbox.MMDF" title="mailbox.MMDF"><code class="xref py py-class docutils literal"><span class="pre">MMDF</span></code></a></span></h3><dl class="class"><dt id="mailbox.MMDF"><span class="yiyi-st" id="yiyi-312"> <em class="property">class </em><code class="descclassname">mailbox.</code><code class="descname">MMDF</code><span class="sig-paren">(</span><em>path</em>, <em>factory=None</em>, <em>create=True</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-313">A subclass of <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> for mailboxes in MMDF format. </span><span class="yiyi-st" id="yiyi-314">Parameter <em>factory</em> is a callable object that accepts a file-like message representation (which behaves as if opened in binary mode) and returns a custom representation. </span><span class="yiyi-st" id="yiyi-315">If <em>factory</em> is <code class="docutils literal"><span class="pre">None</span></code>, <a class="reference internal" href="#mailbox.MMDFMessage" title="mailbox.MMDFMessage"><code class="xref py py-class docutils literal"><span class="pre">MMDFMessage</span></code></a> is used as the default message representation. </span><span class="yiyi-st" id="yiyi-316">If <em>create</em> is <code class="docutils literal"><span class="pre">True</span></code>, the mailbox is created if it does not exist.</span></p><p><span class="yiyi-st" id="yiyi-317">MMDF is a single-file mailbox format invented for the Multichannel Memorandum Distribution Facility, a mail transfer agent. </span><span class="yiyi-st" id="yiyi-318">Each message is in the same form as an mbox message but is bracketed before and after by lines containing four Control-A (<code class="docutils literal"><span class="pre">'\001'</span></code>) characters. </span><span class="yiyi-st" id="yiyi-319">As with the mbox format, the beginning of each message is indicated by a line whose first five characters are “From ”, but additional occurrences of “From ” are not transformed to “&gt;From ” when storing messages because the extra message separator lines prevent mistaking such occurrences for the starts of subsequent messages.</span></p><p><span class="yiyi-st" id="yiyi-320">Some <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> methods implemented by <a class="reference internal" href="#mailbox.MMDF" title="mailbox.MMDF"><code class="xref py py-class docutils literal"><span class="pre">MMDF</span></code></a> deserve special remarks:</span></p><dl class="method"><dt id="mailbox.MMDF.get_file"><span class="yiyi-st" id="yiyi-321"> <code class="descname">get_file</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-322">Using the file after calling <code class="xref py py-meth docutils literal"><span class="pre">flush()</span></code> or <code class="xref py py-meth docutils literal"><span class="pre">close()</span></code> on the <a class="reference internal" href="#mailbox.MMDF" title="mailbox.MMDF"><code class="xref py py-class docutils literal"><span class="pre">MMDF</span></code></a> instance may yield unpredictable results or raise an exception.</span></p></dd></dl><dl class="method"><dt id="mailbox.MMDF.lock"><span class="yiyi-st" id="yiyi-323"> <code class="descname">lock</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dt id="mailbox.MMDF.unlock"><span class="yiyi-st" id="yiyi-324"> <code class="descname">unlock</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-325">Three locking mechanisms are used—dot locking and, if available, the <code class="xref c c-func docutils literal"><span class="pre">flock()</span></code> and <code class="xref c c-func docutils literal"><span class="pre">lockf()</span></code> system calls.</span></p></dd></dl></dd></dl><div class="admonition seealso"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-326">See also</span></p><dl class="last docutils"><dt><span class="yiyi-st" id="yiyi-327"><a class="reference external" href="http://www.tin.org/bin/man.cgi?section=5&amp;topic=mmdf">mmdf man page from tin</a></span></dt><dd><span class="yiyi-st" id="yiyi-328">A specification of MMDF format from the documentation of tin, a newsreader.</span></dd><dt><span class="yiyi-st" id="yiyi-329"><a class="reference external" href="https://en.wikipedia.org/wiki/MMDF">MMDF</a></span></dt><dd><span class="yiyi-st" id="yiyi-330">A Wikipedia article describing the Multichannel Memorandum Distribution Facility.</span></dd></dl></div></div></div><div class="section" id="message-objects"><h2><span class="yiyi-st" id="yiyi-331">19.4.2. </span><span class="yiyi-st" id="yiyi-332"><a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> objects</span></h2><dl class="class"><dt id="mailbox.Message"><span class="yiyi-st" id="yiyi-333"> <em class="property">class </em><code class="descclassname">mailbox.</code><code class="descname">Message</code><span class="sig-paren">(</span><em>message=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-334">A subclass of the <a class="reference internal" href="email.message.html#module-email.message" title="email.message: The base class representing email messages."><code class="xref py py-mod docutils literal"><span class="pre">email.message</span></code></a> module’s <a class="reference internal" href="email.message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a>. </span><span class="yiyi-st" id="yiyi-335">Subclasses of <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">mailbox.Message</span></code></a> add mailbox-format-specific state and behavior.</span></p><p><span class="yiyi-st" id="yiyi-336">If <em>message</em> is omitted, the new instance is created in a default, empty state. </span><span class="yiyi-st" id="yiyi-337">If <em>message</em> is an <a class="reference internal" href="email.message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal"><span class="pre">email.message.Message</span></code></a> instance, its contents are copied; furthermore, any format-specific information is converted insofar as possible if <em>message</em> is a <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> instance. </span><span class="yiyi-st" id="yiyi-338">If <em>message</em> is a string, a byte string, or a file, it should contain an <span class="target" id="index-0"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2822.html"><strong>RFC 2822</strong></a>-compliant message, which is read and parsed. </span><span class="yiyi-st" id="yiyi-339">Files should be open in binary mode, but text mode files are accepted for backward compatibility.</span></p><p><span class="yiyi-st" id="yiyi-340">The format-specific state and behaviors offered by subclasses vary, but in general it is only the properties that are not specific to a particular mailbox that are supported (although presumably the properties are specific to a particular mailbox format). </span><span class="yiyi-st" id="yiyi-341">For example, file offsets for single-file mailbox formats and file names for directory-based mailbox formats are not retained, because they are only applicable to the original mailbox. </span><span class="yiyi-st" id="yiyi-342">But state such as whether a message has been read by the user or marked as important is retained, because it applies to the message itself.</span></p><p><span class="yiyi-st" id="yiyi-343">There is no requirement that <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> instances be used to represent messages retrieved using <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> instances. </span><span class="yiyi-st" id="yiyi-344">In some situations, the time and memory required to generate <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> representations might not be acceptable. </span><span class="yiyi-st" id="yiyi-345">For such situations, <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> instances also offer string and file-like representations, and a custom message factory may be specified when a <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> instance is initialized.</span></p></dd></dl><div class="section" id="maildirmessage"><h3><span class="yiyi-st" id="yiyi-346">19.4.2.1. </span><span class="yiyi-st" id="yiyi-347"><a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal"><span class="pre">MaildirMessage</span></code></a></span></h3><dl class="class"><dt id="mailbox.MaildirMessage"><span class="yiyi-st" id="yiyi-348"> <em class="property">class </em><code class="descclassname">mailbox.</code><code class="descname">MaildirMessage</code><span class="sig-paren">(</span><em>message=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-349">A message with Maildir-specific behaviors. </span><span class="yiyi-st" id="yiyi-350">Parameter <em>message</em> has the same meaning as with the <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> constructor.</span></p><p><span class="yiyi-st" id="yiyi-351">Typically, a mail user agent application moves all of the messages in the <code class="file docutils literal"><span class="pre">new</span></code> subdirectory to the <code class="file docutils literal"><span class="pre">cur</span></code> subdirectory after the first time the user opens and closes the mailbox, recording that the messages are old whether or not they’ve actually been read. </span><span class="yiyi-st" id="yiyi-352">Each message in <code class="file docutils literal"><span class="pre">cur</span></code> has an “info” section added to its file name to store information about its state. </span><span class="yiyi-st" id="yiyi-353">(Some mail readers may also add an “info” section to messages in <code class="file docutils literal"><span class="pre">new</span></code>.) </span><span class="yiyi-st" id="yiyi-354">The “info” section may take one of two forms: it may contain “2,” followed by a list of standardized flags (e.g., “2,FR”) or it may contain “1,” followed by so-called experimental information. </span><span class="yiyi-st" id="yiyi-355">Standard flags for Maildir messages are as follows:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-356">Flag</span></th><th class="head"><span class="yiyi-st" id="yiyi-357">Meaning</span></th><th class="head"><span class="yiyi-st" id="yiyi-358">Explanation</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-359">D</span></td><td><span class="yiyi-st" id="yiyi-360">Draft</span></td><td><span class="yiyi-st" id="yiyi-361">Under composition</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-362">F</span></td><td><span class="yiyi-st" id="yiyi-363">Flagged</span></td><td><span class="yiyi-st" id="yiyi-364">Marked as important</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-365">P</span></td><td><span class="yiyi-st" id="yiyi-366">Passed</span></td><td><span class="yiyi-st" id="yiyi-367">Forwarded, resent, or bounced</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-368">R</span></td><td><span class="yiyi-st" id="yiyi-369">Replied</span></td><td><span class="yiyi-st" id="yiyi-370">Replied to</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-371">S</span></td><td><span class="yiyi-st" id="yiyi-372">Seen</span></td><td><span class="yiyi-st" id="yiyi-373">Read</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-374">T</span></td><td><span class="yiyi-st" id="yiyi-375">Trashed</span></td><td><span class="yiyi-st" id="yiyi-376">Marked for subsequent deletion</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-377"><a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal"><span class="pre">MaildirMessage</span></code></a> instances offer the following methods:</span></p><dl class="method"><dt id="mailbox.MaildirMessage.get_subdir"><span class="yiyi-st" id="yiyi-378"> <code class="descname">get_subdir</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-379">Return either “new” (if the message should be stored in the <code class="file docutils literal"><span class="pre">new</span></code> subdirectory) or “cur” (if the message should be stored in the <code class="file docutils literal"><span class="pre">cur</span></code> subdirectory).</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-380">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-381">A message is typically moved from <code class="file docutils literal"><span class="pre">new</span></code> to <code class="file docutils literal"><span class="pre">cur</span></code> after its mailbox has been accessed, whether or not the message is has been read. </span><span class="yiyi-st" id="yiyi-382">A message <code class="docutils literal"><span class="pre">msg</span></code> has been read if <code class="docutils literal"><span class="pre">"S"</span> <span class="pre">in</span> <span class="pre">msg.get_flags()</span></code> is <code class="docutils literal"><span class="pre">True</span></code>.</span></p></div></dd></dl><dl class="method"><dt id="mailbox.MaildirMessage.set_subdir"><span class="yiyi-st" id="yiyi-383"> <code class="descname">set_subdir</code><span class="sig-paren">(</span><em>subdir</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-384">Set the subdirectory the message should be stored in. </span><span class="yiyi-st" id="yiyi-385">Parameter <em>subdir</em> must be either “new” or “cur”.</span></p></dd></dl><dl class="method"><dt id="mailbox.MaildirMessage.get_flags"><span class="yiyi-st" id="yiyi-386"> <code class="descname">get_flags</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-387">Return a string specifying the flags that are currently set. </span><span class="yiyi-st" id="yiyi-388">If the message complies with the standard Maildir format, the result is the concatenation in alphabetical order of zero or one occurrence of each of <code class="docutils literal"><span class="pre">'D'</span></code>, <code class="docutils literal"><span class="pre">'F'</span></code>, <code class="docutils literal"><span class="pre">'P'</span></code>, <code class="docutils literal"><span class="pre">'R'</span></code>, <code class="docutils literal"><span class="pre">'S'</span></code>, and <code class="docutils literal"><span class="pre">'T'</span></code>. </span><span class="yiyi-st" id="yiyi-389">The empty string is returned if no flags are set or if “info” contains experimental semantics.</span></p></dd></dl><dl class="method"><dt id="mailbox.MaildirMessage.set_flags"><span class="yiyi-st" id="yiyi-390"> <code class="descname">set_flags</code><span class="sig-paren">(</span><em>flags</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-391">Set the flags specified by <em>flags</em> and unset all others.</span></p></dd></dl><dl class="method"><dt id="mailbox.MaildirMessage.add_flag"><span class="yiyi-st" id="yiyi-392"> <code class="descname">add_flag</code><span class="sig-paren">(</span><em>flag</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-393">Set the flag(s) specified by <em>flag</em> without changing other flags. </span><span class="yiyi-st" id="yiyi-394">To add more than one flag at a time, <em>flag</em> may be a string of more than one character. </span><span class="yiyi-st" id="yiyi-395">The current “info” is overwritten whether or not it contains experimental information rather than flags.</span></p></dd></dl><dl class="method"><dt id="mailbox.MaildirMessage.remove_flag"><span class="yiyi-st" id="yiyi-396"> <code class="descname">remove_flag</code><span class="sig-paren">(</span><em>flag</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-397">Unset the flag(s) specified by <em>flag</em> without changing other flags. </span><span class="yiyi-st" id="yiyi-398">To remove more than one flag at a time, <em>flag</em> maybe a string of more than one character. </span><span class="yiyi-st" id="yiyi-399">If “info” contains experimental information rather than flags, the current “info” is not modified.</span></p></dd></dl><dl class="method"><dt id="mailbox.MaildirMessage.get_date"><span class="yiyi-st" id="yiyi-400"> <code class="descname">get_date</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-401">Return the delivery date of the message as a floating-point number representing seconds since the epoch.</span></p></dd></dl><dl class="method"><dt id="mailbox.MaildirMessage.set_date"><span class="yiyi-st" id="yiyi-402"> <code class="descname">set_date</code><span class="sig-paren">(</span><em>date</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-403">Set the delivery date of the message to <em>date</em>, a floating-point number representing seconds since the epoch.</span></p></dd></dl><dl class="method"><dt id="mailbox.MaildirMessage.get_info"><span class="yiyi-st" id="yiyi-404"> <code class="descname">get_info</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-405">Return a string containing the “info” for a message. </span><span class="yiyi-st" id="yiyi-406">This is useful for accessing and modifying “info” that is experimental (i.e., not a list of flags).</span></p></dd></dl><dl class="method"><dt id="mailbox.MaildirMessage.set_info"><span class="yiyi-st" id="yiyi-407"> <code class="descname">set_info</code><span class="sig-paren">(</span><em>info</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-408">Set “info” to <em>info</em>, which should be a string.</span></p></dd></dl></dd></dl><p><span class="yiyi-st" id="yiyi-409">When a <a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal"><span class="pre">MaildirMessage</span></code></a> instance is created based upon an <a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a> or <a class="reference internal" href="#mailbox.MMDFMessage" title="mailbox.MMDFMessage"><code class="xref py py-class docutils literal"><span class="pre">MMDFMessage</span></code></a> instance, the <em class="mailheader">Status</em> and <em class="mailheader">X-Status</em> headers are omitted and the following conversions take place:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-410">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-411"><a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a> or <a class="reference internal" href="#mailbox.MMDFMessage" title="mailbox.MMDFMessage"><code class="xref py py-class docutils literal"><span class="pre">MMDFMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-412">“cur” subdirectory</span></td><td><span class="yiyi-st" id="yiyi-413">O flag</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-414">F flag</span></td><td><span class="yiyi-st" id="yiyi-415">F flag</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-416">R flag</span></td><td><span class="yiyi-st" id="yiyi-417">A flag</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-418">S flag</span></td><td><span class="yiyi-st" id="yiyi-419">R flag</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-420">T flag</span></td><td><span class="yiyi-st" id="yiyi-421">D flag</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-422">When a <a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal"><span class="pre">MaildirMessage</span></code></a> instance is created based upon an <a class="reference internal" href="#mailbox.MHMessage" title="mailbox.MHMessage"><code class="xref py py-class docutils literal"><span class="pre">MHMessage</span></code></a> instance, the following conversions take place:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-423">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-424"><a class="reference internal" href="#mailbox.MHMessage" title="mailbox.MHMessage"><code class="xref py py-class docutils literal"><span class="pre">MHMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-425">“cur” subdirectory</span></td><td><span class="yiyi-st" id="yiyi-426">“unseen” sequence</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-427">“cur” subdirectory and S flag</span></td><td><span class="yiyi-st" id="yiyi-428">no “unseen” sequence</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-429">F flag</span></td><td><span class="yiyi-st" id="yiyi-430">“flagged” sequence</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-431">R flag</span></td><td><span class="yiyi-st" id="yiyi-432">“replied” sequence</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-433">When a <a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal"><span class="pre">MaildirMessage</span></code></a> instance is created based upon a <a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal"><span class="pre">BabylMessage</span></code></a> instance, the following conversions take place:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-434">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-435"><a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal"><span class="pre">BabylMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-436">“cur” subdirectory</span></td><td><span class="yiyi-st" id="yiyi-437">“unseen” label</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-438">“cur” subdirectory and S flag</span></td><td><span class="yiyi-st" id="yiyi-439">no “unseen” label</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-440">P flag</span></td><td><span class="yiyi-st" id="yiyi-441">“forwarded” or “resent” label</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-442">R flag</span></td><td><span class="yiyi-st" id="yiyi-443">“answered” label</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-444">T flag</span></td><td><span class="yiyi-st" id="yiyi-445">“deleted” label</span></td></tr></tbody></table></div><div class="section" id="mboxmessage"><h3><span class="yiyi-st" id="yiyi-446">19.4.2.2. <a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a></span></h3><dl class="class"><dt id="mailbox.mboxMessage"><span class="yiyi-st" id="yiyi-447"> <em class="property">class </em><code class="descclassname">mailbox.</code><code class="descname">mboxMessage</code><span class="sig-paren">(</span><em>message=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-448">A message with mbox-specific behaviors. </span><span class="yiyi-st" id="yiyi-449">Parameter <em>message</em> has the same meaning as with the <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> constructor.</span></p><p><span class="yiyi-st" id="yiyi-450">Messages in an mbox mailbox are stored together in a single file. </span><span class="yiyi-st" id="yiyi-451">The sender’s envelope address and the time of delivery are typically stored in a line beginning with “From ” that is used to indicate the start of a message, though there is considerable variation in the exact format of this data among mbox implementations. </span><span class="yiyi-st" id="yiyi-452">Flags that indicate the state of the message, such as whether it has been read or marked as important, are typically stored in <em class="mailheader">Status</em> and <em class="mailheader">X-Status</em> headers.</span></p><p><span class="yiyi-st" id="yiyi-453">Conventional flags for mbox messages are as follows:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-454">Flag</span></th><th class="head"><span class="yiyi-st" id="yiyi-455">Meaning</span></th><th class="head"><span class="yiyi-st" id="yiyi-456">Explanation</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-457">R</span></td><td><span class="yiyi-st" id="yiyi-458">Read</span></td><td><span class="yiyi-st" id="yiyi-459">Read</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-460">O</span></td><td><span class="yiyi-st" id="yiyi-461">Old</span></td><td><span class="yiyi-st" id="yiyi-462">Previously detected by MUA</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-463">D</span></td><td><span class="yiyi-st" id="yiyi-464">Deleted</span></td><td><span class="yiyi-st" id="yiyi-465">Marked for subsequent deletion</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-466">F</span></td><td><span class="yiyi-st" id="yiyi-467">Flagged</span></td><td><span class="yiyi-st" id="yiyi-468">Marked as important</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-469">A</span></td><td><span class="yiyi-st" id="yiyi-470">Answered</span></td><td><span class="yiyi-st" id="yiyi-471">Replied to</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-472">The “R” and “O” flags are stored in the <em class="mailheader">Status</em> header, and the “D”, “F”, and “A” flags are stored in the <em class="mailheader">X-Status</em> header. </span><span class="yiyi-st" id="yiyi-473">The flags and headers typically appear in the order mentioned.</span></p><p><span class="yiyi-st" id="yiyi-474"><a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a> instances offer the following methods:</span></p><dl class="method"><dt id="mailbox.mboxMessage.get_from"><span class="yiyi-st" id="yiyi-475"> <code class="descname">get_from</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-476">Return a string representing the “From ” line that marks the start of the message in an mbox mailbox. </span><span class="yiyi-st" id="yiyi-477">The leading “From ” and the trailing newline are excluded.</span></p></dd></dl><dl class="method"><dt id="mailbox.mboxMessage.set_from"><span class="yiyi-st" id="yiyi-478"> <code class="descname">set_from</code><span class="sig-paren">(</span><em>from_</em>, <em>time_=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-479">Set the “From ” line to <em>from_</em>, which should be specified without a leading “From ” or trailing newline. </span><span class="yiyi-st" id="yiyi-480">For convenience, <em>time_</em> may be specified and will be formatted appropriately and appended to <em>from_</em>. </span><span class="yiyi-st" id="yiyi-481">If <em>time_</em> is specified, it should be a <a class="reference internal" href="time.html#time.struct_time" title="time.struct_time"><code class="xref py py-class docutils literal"><span class="pre">time.struct_time</span></code></a> instance, a tuple suitable for passing to <a class="reference internal" href="time.html#time.strftime" title="time.strftime"><code class="xref py py-meth docutils literal"><span class="pre">time.strftime()</span></code></a>, or <code class="docutils literal"><span class="pre">True</span></code> (to use <a class="reference internal" href="time.html#time.gmtime" title="time.gmtime"><code class="xref py py-meth docutils literal"><span class="pre">time.gmtime()</span></code></a>).</span></p></dd></dl><dl class="method"><dt id="mailbox.mboxMessage.get_flags"><span class="yiyi-st" id="yiyi-482"> <code class="descname">get_flags</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-483">Return a string specifying the flags that are currently set. </span><span class="yiyi-st" id="yiyi-484">If the message complies with the conventional format, the result is the concatenation in the following order of zero or one occurrence of each of <code class="docutils literal"><span class="pre">'R'</span></code>, <code class="docutils literal"><span class="pre">'O'</span></code>, <code class="docutils literal"><span class="pre">'D'</span></code>, <code class="docutils literal"><span class="pre">'F'</span></code>, and <code class="docutils literal"><span class="pre">'A'</span></code>.</span></p></dd></dl><dl class="method"><dt id="mailbox.mboxMessage.set_flags"><span class="yiyi-st" id="yiyi-485"> <code class="descname">set_flags</code><span class="sig-paren">(</span><em>flags</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-486">Set the flags specified by <em>flags</em> and unset all others. </span><span class="yiyi-st" id="yiyi-487">Parameter <em>flags</em> should be the concatenation in any order of zero or more occurrences of each of <code class="docutils literal"><span class="pre">'R'</span></code>, <code class="docutils literal"><span class="pre">'O'</span></code>, <code class="docutils literal"><span class="pre">'D'</span></code>, <code class="docutils literal"><span class="pre">'F'</span></code>, and <code class="docutils literal"><span class="pre">'A'</span></code>.</span></p></dd></dl><dl class="method"><dt id="mailbox.mboxMessage.add_flag"><span class="yiyi-st" id="yiyi-488"> <code class="descname">add_flag</code><span class="sig-paren">(</span><em>flag</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-489">Set the flag(s) specified by <em>flag</em> without changing other flags. </span><span class="yiyi-st" id="yiyi-490">To add more than one flag at a time, <em>flag</em> may be a string of more than one character.</span></p></dd></dl><dl class="method"><dt id="mailbox.mboxMessage.remove_flag"><span class="yiyi-st" id="yiyi-491"> <code class="descname">remove_flag</code><span class="sig-paren">(</span><em>flag</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-492">Unset the flag(s) specified by <em>flag</em> without changing other flags. </span><span class="yiyi-st" id="yiyi-493">To remove more than one flag at a time, <em>flag</em> maybe a string of more than one character.</span></p></dd></dl></dd></dl><p><span class="yiyi-st" id="yiyi-494">When an <a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a> instance is created based upon a <a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal"><span class="pre">MaildirMessage</span></code></a> instance, a “From ” line is generated based upon the <a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal"><span class="pre">MaildirMessage</span></code></a> instance’s delivery date, and the following conversions take place:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-495">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-496"><a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal"><span class="pre">MaildirMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-497">R flag</span></td><td><span class="yiyi-st" id="yiyi-498">S flag</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-499">O flag</span></td><td><span class="yiyi-st" id="yiyi-500">“cur” subdirectory</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-501">D flag</span></td><td><span class="yiyi-st" id="yiyi-502">T flag</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-503">F flag</span></td><td><span class="yiyi-st" id="yiyi-504">F flag</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-505">A flag</span></td><td><span class="yiyi-st" id="yiyi-506">R flag</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-507">When an <a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a> instance is created based upon an <a class="reference internal" href="#mailbox.MHMessage" title="mailbox.MHMessage"><code class="xref py py-class docutils literal"><span class="pre">MHMessage</span></code></a> instance, the following conversions take place:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-508">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-509"><a class="reference internal" href="#mailbox.MHMessage" title="mailbox.MHMessage"><code class="xref py py-class docutils literal"><span class="pre">MHMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-510">R flag and O flag</span></td><td><span class="yiyi-st" id="yiyi-511">no “unseen” sequence</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-512">O flag</span></td><td><span class="yiyi-st" id="yiyi-513">“unseen” sequence</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-514">F flag</span></td><td><span class="yiyi-st" id="yiyi-515">“flagged” sequence</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-516">A flag</span></td><td><span class="yiyi-st" id="yiyi-517">“replied” sequence</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-518">When an <a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a> instance is created based upon a <a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal"><span class="pre">BabylMessage</span></code></a> instance, the following conversions take place:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-519">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-520"><a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal"><span class="pre">BabylMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-521">R flag and O flag</span></td><td><span class="yiyi-st" id="yiyi-522">no “unseen” label</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-523">O flag</span></td><td><span class="yiyi-st" id="yiyi-524">“unseen” label</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-525">D flag</span></td><td><span class="yiyi-st" id="yiyi-526">“deleted” label</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-527">A flag</span></td><td><span class="yiyi-st" id="yiyi-528">“answered” label</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-529">When a <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> instance is created based upon an <a class="reference internal" href="#mailbox.MMDFMessage" title="mailbox.MMDFMessage"><code class="xref py py-class docutils literal"><span class="pre">MMDFMessage</span></code></a> instance, the “From ” line is copied and all flags directly correspond:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-530">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-531"><a class="reference internal" href="#mailbox.MMDFMessage" title="mailbox.MMDFMessage"><code class="xref py py-class docutils literal"><span class="pre">MMDFMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-532">R flag</span></td><td><span class="yiyi-st" id="yiyi-533">R flag</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-534">O flag</span></td><td><span class="yiyi-st" id="yiyi-535">O flag</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-536">D flag</span></td><td><span class="yiyi-st" id="yiyi-537">D flag</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-538">F flag</span></td><td><span class="yiyi-st" id="yiyi-539">F flag</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-540">A flag</span></td><td><span class="yiyi-st" id="yiyi-541">A flag</span></td></tr></tbody></table></div><div class="section" id="mhmessage"><h3><span class="yiyi-st" id="yiyi-542">19.4.2.3. </span><span class="yiyi-st" id="yiyi-543"><a class="reference internal" href="#mailbox.MHMessage" title="mailbox.MHMessage"><code class="xref py py-class docutils literal"><span class="pre">MHMessage</span></code></a></span></h3><dl class="class"><dt id="mailbox.MHMessage"><span class="yiyi-st" id="yiyi-544"> <em class="property">class </em><code class="descclassname">mailbox.</code><code class="descname">MHMessage</code><span class="sig-paren">(</span><em>message=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-545">A message with MH-specific behaviors. </span><span class="yiyi-st" id="yiyi-546">Parameter <em>message</em> has the same meaning as with the <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> constructor.</span></p><p><span class="yiyi-st" id="yiyi-547">MH messages do not support marks or flags in the traditional sense, but they do support sequences, which are logical groupings of arbitrary messages. </span><span class="yiyi-st" id="yiyi-548">Some mail reading programs (although not the standard <strong class="program">mh</strong> and <strong class="program">nmh</strong>) use sequences in much the same way flags are used with other formats, as follows:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-549">Sequence</span></th><th class="head"><span class="yiyi-st" id="yiyi-550">Explanation</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-551">unseen</span></td><td><span class="yiyi-st" id="yiyi-552">Not read, but previously detected by MUA</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-553">replied</span></td><td><span class="yiyi-st" id="yiyi-554">Replied to</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-555">flagged</span></td><td><span class="yiyi-st" id="yiyi-556">Marked as important</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-557"><a class="reference internal" href="#mailbox.MHMessage" title="mailbox.MHMessage"><code class="xref py py-class docutils literal"><span class="pre">MHMessage</span></code></a> instances offer the following methods:</span></p><dl class="method"><dt id="mailbox.MHMessage.get_sequences"><span class="yiyi-st" id="yiyi-558"> <code class="descname">get_sequences</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-559">Return a list of the names of sequences that include this message.</span></p></dd></dl><dl class="method"><dt id="mailbox.MHMessage.set_sequences"><span class="yiyi-st" id="yiyi-560"> <code class="descname">set_sequences</code><span class="sig-paren">(</span><em>sequences</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-561">Set the list of sequences that include this message.</span></p></dd></dl><dl class="method"><dt id="mailbox.MHMessage.add_sequence"><span class="yiyi-st" id="yiyi-562"> <code class="descname">add_sequence</code><span class="sig-paren">(</span><em>sequence</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-563">Add <em>sequence</em> to the list of sequences that include this message.</span></p></dd></dl><dl class="method"><dt id="mailbox.MHMessage.remove_sequence"><span class="yiyi-st" id="yiyi-564"> <code class="descname">remove_sequence</code><span class="sig-paren">(</span><em>sequence</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-565">Remove <em>sequence</em> from the list of sequences that include this message.</span></p></dd></dl></dd></dl><p><span class="yiyi-st" id="yiyi-566">When an <a class="reference internal" href="#mailbox.MHMessage" title="mailbox.MHMessage"><code class="xref py py-class docutils literal"><span class="pre">MHMessage</span></code></a> instance is created based upon a <a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal"><span class="pre">MaildirMessage</span></code></a> instance, the following conversions take place:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-567">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-568"><a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal"><span class="pre">MaildirMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-569">“unseen” sequence</span></td><td><span class="yiyi-st" id="yiyi-570">no S flag</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-571">“replied” sequence</span></td><td><span class="yiyi-st" id="yiyi-572">R flag</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-573">“flagged” sequence</span></td><td><span class="yiyi-st" id="yiyi-574">F flag</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-575">When an <a class="reference internal" href="#mailbox.MHMessage" title="mailbox.MHMessage"><code class="xref py py-class docutils literal"><span class="pre">MHMessage</span></code></a> instance is created based upon an <a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a> or <a class="reference internal" href="#mailbox.MMDFMessage" title="mailbox.MMDFMessage"><code class="xref py py-class docutils literal"><span class="pre">MMDFMessage</span></code></a> instance, the <em class="mailheader">Status</em> and <em class="mailheader">X-Status</em> headers are omitted and the following conversions take place:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-576">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-577"><a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a> or <a class="reference internal" href="#mailbox.MMDFMessage" title="mailbox.MMDFMessage"><code class="xref py py-class docutils literal"><span class="pre">MMDFMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-578">“unseen” sequence</span></td><td><span class="yiyi-st" id="yiyi-579">no R flag</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-580">“replied” sequence</span></td><td><span class="yiyi-st" id="yiyi-581">A flag</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-582">“flagged” sequence</span></td><td><span class="yiyi-st" id="yiyi-583">F flag</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-584">When an <a class="reference internal" href="#mailbox.MHMessage" title="mailbox.MHMessage"><code class="xref py py-class docutils literal"><span class="pre">MHMessage</span></code></a> instance is created based upon a <a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal"><span class="pre">BabylMessage</span></code></a> instance, the following conversions take place:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-585">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-586"><a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal"><span class="pre">BabylMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-587">“unseen” sequence</span></td><td><span class="yiyi-st" id="yiyi-588">“unseen” label</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-589">“replied” sequence</span></td><td><span class="yiyi-st" id="yiyi-590">“answered” label</span></td></tr></tbody></table></div><div class="section" id="babylmessage"><h3><span class="yiyi-st" id="yiyi-591">19.4.2.4. </span><span class="yiyi-st" id="yiyi-592"><a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal"><span class="pre">BabylMessage</span></code></a></span></h3><dl class="class"><dt id="mailbox.BabylMessage"><span class="yiyi-st" id="yiyi-593"> <em class="property">class </em><code class="descclassname">mailbox.</code><code class="descname">BabylMessage</code><span class="sig-paren">(</span><em>message=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-594">A message with Babyl-specific behaviors. </span><span class="yiyi-st" id="yiyi-595">Parameter <em>message</em> has the same meaning as with the <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> constructor.</span></p><p><span class="yiyi-st" id="yiyi-596">Certain message labels, called <em class="dfn">attributes</em>, are defined by convention to have special meanings. </span><span class="yiyi-st" id="yiyi-597">The attributes are as follows:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-598">Label</span></th><th class="head"><span class="yiyi-st" id="yiyi-599">Explanation</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-600">unseen</span></td><td><span class="yiyi-st" id="yiyi-601">Not read, but previously detected by MUA</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-602">deleted</span></td><td><span class="yiyi-st" id="yiyi-603">Marked for subsequent deletion</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-604">filed</span></td><td><span class="yiyi-st" id="yiyi-605">Copied to another file or mailbox</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-606">answered</span></td><td><span class="yiyi-st" id="yiyi-607">Replied to</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-608">forwarded</span></td><td><span class="yiyi-st" id="yiyi-609">Forwarded</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-610">edited</span></td><td><span class="yiyi-st" id="yiyi-611">Modified by the user</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-612">resent</span></td><td><span class="yiyi-st" id="yiyi-613">Resent</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-614">By default, Rmail displays only visible headers. </span><span class="yiyi-st" id="yiyi-615">The <a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal"><span class="pre">BabylMessage</span></code></a> class, though, uses the original headers because they are more complete. </span><span class="yiyi-st" id="yiyi-616">Visible headers may be accessed explicitly if desired.</span></p><p><span class="yiyi-st" id="yiyi-617"><a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal"><span class="pre">BabylMessage</span></code></a> instances offer the following methods:</span></p><dl class="method"><dt id="mailbox.BabylMessage.get_labels"><span class="yiyi-st" id="yiyi-618"> <code class="descname">get_labels</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-619">Return a list of labels on the message.</span></p></dd></dl><dl class="method"><dt id="mailbox.BabylMessage.set_labels"><span class="yiyi-st" id="yiyi-620"> <code class="descname">set_labels</code><span class="sig-paren">(</span><em>labels</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-621">Set the list of labels on the message to <em>labels</em>.</span></p></dd></dl><dl class="method"><dt id="mailbox.BabylMessage.add_label"><span class="yiyi-st" id="yiyi-622"> <code class="descname">add_label</code><span class="sig-paren">(</span><em>label</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-623">Add <em>label</em> to the list of labels on the message.</span></p></dd></dl><dl class="method"><dt id="mailbox.BabylMessage.remove_label"><span class="yiyi-st" id="yiyi-624"> <code class="descname">remove_label</code><span class="sig-paren">(</span><em>label</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-625">Remove <em>label</em> from the list of labels on the message.</span></p></dd></dl><dl class="method"><dt id="mailbox.BabylMessage.get_visible"><span class="yiyi-st" id="yiyi-626"> <code class="descname">get_visible</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-627">Return an <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> instance whose headers are the message’s visible headers and whose body is empty.</span></p></dd></dl><dl class="method"><dt id="mailbox.BabylMessage.set_visible"><span class="yiyi-st" id="yiyi-628"> <code class="descname">set_visible</code><span class="sig-paren">(</span><em>visible</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-629">Set the message’s visible headers to be the same as the headers in <em>message</em>. </span><span class="yiyi-st" id="yiyi-630">Parameter <em>visible</em> should be a <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> instance, an <a class="reference internal" href="email.message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal"><span class="pre">email.message.Message</span></code></a> instance, a string, or a file-like object (which should be open in text mode).</span></p></dd></dl><dl class="method"><dt id="mailbox.BabylMessage.update_visible"><span class="yiyi-st" id="yiyi-631"> <code class="descname">update_visible</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-632">When a <a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal"><span class="pre">BabylMessage</span></code></a> instance’s original headers are modified, the visible headers are not automatically modified to correspond. </span><span class="yiyi-st" id="yiyi-633">This method updates the visible headers as follows: each visible header with a corresponding original header is set to the value of the original header, each visible header without a corresponding original header is removed, and any of <em class="mailheader">Date</em>, <em class="mailheader">From</em>, <em class="mailheader">Reply-To</em>, <em class="mailheader">To</em>, <em class="mailheader">CC</em>, and <em class="mailheader">Subject</em> that are present in the original headers but not the visible headers are added to the visible headers.</span></p></dd></dl></dd></dl><p><span class="yiyi-st" id="yiyi-634">When a <a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal"><span class="pre">BabylMessage</span></code></a> instance is created based upon a <a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal"><span class="pre">MaildirMessage</span></code></a> instance, the following conversions take place:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-635">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-636"><a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal"><span class="pre">MaildirMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-637">“unseen” label</span></td><td><span class="yiyi-st" id="yiyi-638">no S flag</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-639">“deleted” label</span></td><td><span class="yiyi-st" id="yiyi-640">T flag</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-641">“answered” label</span></td><td><span class="yiyi-st" id="yiyi-642">R flag</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-643">“forwarded” label</span></td><td><span class="yiyi-st" id="yiyi-644">P flag</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-645">When a <a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal"><span class="pre">BabylMessage</span></code></a> instance is created based upon an <a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a> or <a class="reference internal" href="#mailbox.MMDFMessage" title="mailbox.MMDFMessage"><code class="xref py py-class docutils literal"><span class="pre">MMDFMessage</span></code></a> instance, the <em class="mailheader">Status</em> and <em class="mailheader">X-Status</em> headers are omitted and the following conversions take place:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-646">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-647"><a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a> or <a class="reference internal" href="#mailbox.MMDFMessage" title="mailbox.MMDFMessage"><code class="xref py py-class docutils literal"><span class="pre">MMDFMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-648">“unseen” label</span></td><td><span class="yiyi-st" id="yiyi-649">no R flag</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-650">“deleted” label</span></td><td><span class="yiyi-st" id="yiyi-651">D flag</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-652">“answered” label</span></td><td><span class="yiyi-st" id="yiyi-653">A flag</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-654">When a <a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal"><span class="pre">BabylMessage</span></code></a> instance is created based upon an <a class="reference internal" href="#mailbox.MHMessage" title="mailbox.MHMessage"><code class="xref py py-class docutils literal"><span class="pre">MHMessage</span></code></a> instance, the following conversions take place:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-655">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-656"><a class="reference internal" href="#mailbox.MHMessage" title="mailbox.MHMessage"><code class="xref py py-class docutils literal"><span class="pre">MHMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-657">“unseen” label</span></td><td><span class="yiyi-st" id="yiyi-658">“unseen” sequence</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-659">“answered” label</span></td><td><span class="yiyi-st" id="yiyi-660">“replied” sequence</span></td></tr></tbody></table></div><div class="section" id="mmdfmessage"><h3><span class="yiyi-st" id="yiyi-661">19.4.2.5. </span><span class="yiyi-st" id="yiyi-662"><a class="reference internal" href="#mailbox.MMDFMessage" title="mailbox.MMDFMessage"><code class="xref py py-class docutils literal"><span class="pre">MMDFMessage</span></code></a></span></h3><dl class="class"><dt id="mailbox.MMDFMessage"><span class="yiyi-st" id="yiyi-663"> <em class="property">class </em><code class="descclassname">mailbox.</code><code class="descname">MMDFMessage</code><span class="sig-paren">(</span><em>message=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-664">A message with MMDF-specific behaviors. </span><span class="yiyi-st" id="yiyi-665">Parameter <em>message</em> has the same meaning as with the <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal"><span class="pre">Message</span></code></a> constructor.</span></p><p><span class="yiyi-st" id="yiyi-666">As with message in an mbox mailbox, MMDF messages are stored with the sender’s address and the delivery date in an initial line beginning with “From ”. </span><span class="yiyi-st" id="yiyi-667">Likewise, flags that indicate the state of the message are typically stored in <em class="mailheader">Status</em> and <em class="mailheader">X-Status</em> headers.</span></p><p><span class="yiyi-st" id="yiyi-668">Conventional flags for MMDF messages are identical to those of mbox message and are as follows:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-669">Flag</span></th><th class="head"><span class="yiyi-st" id="yiyi-670">Meaning</span></th><th class="head"><span class="yiyi-st" id="yiyi-671">Explanation</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-672">R</span></td><td><span class="yiyi-st" id="yiyi-673">Read</span></td><td><span class="yiyi-st" id="yiyi-674">Read</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-675">O</span></td><td><span class="yiyi-st" id="yiyi-676">Old</span></td><td><span class="yiyi-st" id="yiyi-677">Previously detected by MUA</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-678">D</span></td><td><span class="yiyi-st" id="yiyi-679">Deleted</span></td><td><span class="yiyi-st" id="yiyi-680">Marked for subsequent deletion</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-681">F</span></td><td><span class="yiyi-st" id="yiyi-682">Flagged</span></td><td><span class="yiyi-st" id="yiyi-683">Marked as important</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-684">A</span></td><td><span class="yiyi-st" id="yiyi-685">Answered</span></td><td><span class="yiyi-st" id="yiyi-686">Replied to</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-687">The “R” and “O” flags are stored in the <em class="mailheader">Status</em> header, and the “D”, “F”, and “A” flags are stored in the <em class="mailheader">X-Status</em> header. </span><span class="yiyi-st" id="yiyi-688">The flags and headers typically appear in the order mentioned.</span></p><p><span class="yiyi-st" id="yiyi-689"><a class="reference internal" href="#mailbox.MMDFMessage" title="mailbox.MMDFMessage"><code class="xref py py-class docutils literal"><span class="pre">MMDFMessage</span></code></a> instances offer the following methods, which are identical to those offered by <a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a>:</span></p><dl class="method"><dt id="mailbox.MMDFMessage.get_from"><span class="yiyi-st" id="yiyi-690"> <code class="descname">get_from</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-691">Return a string representing the “From ” line that marks the start of the message in an mbox mailbox. </span><span class="yiyi-st" id="yiyi-692">The leading “From ” and the trailing newline are excluded.</span></p></dd></dl><dl class="method"><dt id="mailbox.MMDFMessage.set_from"><span class="yiyi-st" id="yiyi-693"> <code class="descname">set_from</code><span class="sig-paren">(</span><em>from_</em>, <em>time_=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-694">Set the “From ” line to <em>from_</em>, which should be specified without a leading “From ” or trailing newline. </span><span class="yiyi-st" id="yiyi-695">For convenience, <em>time_</em> may be specified and will be formatted appropriately and appended to <em>from_</em>. </span><span class="yiyi-st" id="yiyi-696">If <em>time_</em> is specified, it should be a <a class="reference internal" href="time.html#time.struct_time" title="time.struct_time"><code class="xref py py-class docutils literal"><span class="pre">time.struct_time</span></code></a> instance, a tuple suitable for passing to <a class="reference internal" href="time.html#time.strftime" title="time.strftime"><code class="xref py py-meth docutils literal"><span class="pre">time.strftime()</span></code></a>, or <code class="docutils literal"><span class="pre">True</span></code> (to use <a class="reference internal" href="time.html#time.gmtime" title="time.gmtime"><code class="xref py py-meth docutils literal"><span class="pre">time.gmtime()</span></code></a>).</span></p></dd></dl><dl class="method"><dt id="mailbox.MMDFMessage.get_flags"><span class="yiyi-st" id="yiyi-697"> <code class="descname">get_flags</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-698">Return a string specifying the flags that are currently set. </span><span class="yiyi-st" id="yiyi-699">If the message complies with the conventional format, the result is the concatenation in the following order of zero or one occurrence of each of <code class="docutils literal"><span class="pre">'R'</span></code>, <code class="docutils literal"><span class="pre">'O'</span></code>, <code class="docutils literal"><span class="pre">'D'</span></code>, <code class="docutils literal"><span class="pre">'F'</span></code>, and <code class="docutils literal"><span class="pre">'A'</span></code>.</span></p></dd></dl><dl class="method"><dt id="mailbox.MMDFMessage.set_flags"><span class="yiyi-st" id="yiyi-700"> <code class="descname">set_flags</code><span class="sig-paren">(</span><em>flags</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-701">Set the flags specified by <em>flags</em> and unset all others. </span><span class="yiyi-st" id="yiyi-702">Parameter <em>flags</em> should be the concatenation in any order of zero or more occurrences of each of <code class="docutils literal"><span class="pre">'R'</span></code>, <code class="docutils literal"><span class="pre">'O'</span></code>, <code class="docutils literal"><span class="pre">'D'</span></code>, <code class="docutils literal"><span class="pre">'F'</span></code>, and <code class="docutils literal"><span class="pre">'A'</span></code>.</span></p></dd></dl><dl class="method"><dt id="mailbox.MMDFMessage.add_flag"><span class="yiyi-st" id="yiyi-703"> <code class="descname">add_flag</code><span class="sig-paren">(</span><em>flag</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-704">Set the flag(s) specified by <em>flag</em> without changing other flags. </span><span class="yiyi-st" id="yiyi-705">To add more than one flag at a time, <em>flag</em> may be a string of more than one character.</span></p></dd></dl><dl class="method"><dt id="mailbox.MMDFMessage.remove_flag"><span class="yiyi-st" id="yiyi-706"> <code class="descname">remove_flag</code><span class="sig-paren">(</span><em>flag</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-707">Unset the flag(s) specified by <em>flag</em> without changing other flags. </span><span class="yiyi-st" id="yiyi-708">To remove more than one flag at a time, <em>flag</em> maybe a string of more than one character.</span></p></dd></dl></dd></dl><p><span class="yiyi-st" id="yiyi-709">When an <a class="reference internal" href="#mailbox.MMDFMessage" title="mailbox.MMDFMessage"><code class="xref py py-class docutils literal"><span class="pre">MMDFMessage</span></code></a> instance is created based upon a <a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal"><span class="pre">MaildirMessage</span></code></a> instance, a “From ” line is generated based upon the <a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal"><span class="pre">MaildirMessage</span></code></a> instance’s delivery date, and the following conversions take place:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-710">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-711"><a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal"><span class="pre">MaildirMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-712">R flag</span></td><td><span class="yiyi-st" id="yiyi-713">S flag</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-714">O flag</span></td><td><span class="yiyi-st" id="yiyi-715">“cur” subdirectory</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-716">D flag</span></td><td><span class="yiyi-st" id="yiyi-717">T flag</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-718">F flag</span></td><td><span class="yiyi-st" id="yiyi-719">F flag</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-720">A flag</span></td><td><span class="yiyi-st" id="yiyi-721">R flag</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-722">When an <a class="reference internal" href="#mailbox.MMDFMessage" title="mailbox.MMDFMessage"><code class="xref py py-class docutils literal"><span class="pre">MMDFMessage</span></code></a> instance is created based upon an <a class="reference internal" href="#mailbox.MHMessage" title="mailbox.MHMessage"><code class="xref py py-class docutils literal"><span class="pre">MHMessage</span></code></a> instance, the following conversions take place:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-723">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-724"><a class="reference internal" href="#mailbox.MHMessage" title="mailbox.MHMessage"><code class="xref py py-class docutils literal"><span class="pre">MHMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-725">R flag and O flag</span></td><td><span class="yiyi-st" id="yiyi-726">no “unseen” sequence</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-727">O flag</span></td><td><span class="yiyi-st" id="yiyi-728">“unseen” sequence</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-729">F flag</span></td><td><span class="yiyi-st" id="yiyi-730">“flagged” sequence</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-731">A flag</span></td><td><span class="yiyi-st" id="yiyi-732">“replied” sequence</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-733">When an <a class="reference internal" href="#mailbox.MMDFMessage" title="mailbox.MMDFMessage"><code class="xref py py-class docutils literal"><span class="pre">MMDFMessage</span></code></a> instance is created based upon a <a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal"><span class="pre">BabylMessage</span></code></a> instance, the following conversions take place:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-734">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-735"><a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal"><span class="pre">BabylMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-736">R flag and O flag</span></td><td><span class="yiyi-st" id="yiyi-737">no “unseen” label</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-738">O flag</span></td><td><span class="yiyi-st" id="yiyi-739">“unseen” label</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-740">D flag</span></td><td><span class="yiyi-st" id="yiyi-741">“deleted” label</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-742">A flag</span></td><td><span class="yiyi-st" id="yiyi-743">“answered” label</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-744">When an <a class="reference internal" href="#mailbox.MMDFMessage" title="mailbox.MMDFMessage"><code class="xref py py-class docutils literal"><span class="pre">MMDFMessage</span></code></a> instance is created based upon an <a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a> instance, the “From ” line is copied and all flags directly correspond:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-745">Resulting state</span></th><th class="head"><span class="yiyi-st" id="yiyi-746"><a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal"><span class="pre">mboxMessage</span></code></a> state</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-747">R flag</span></td><td><span class="yiyi-st" id="yiyi-748">R flag</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-749">O flag</span></td><td><span class="yiyi-st" id="yiyi-750">O flag</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-751">D flag</span></td><td><span class="yiyi-st" id="yiyi-752">D flag</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-753">F flag</span></td><td><span class="yiyi-st" id="yiyi-754">F flag</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-755">A flag</span></td><td><span class="yiyi-st" id="yiyi-756">A flag</span></td></tr></tbody></table></div></div><div class="section" id="exceptions"><h2><span class="yiyi-st" id="yiyi-757">19.4.3. </span><span class="yiyi-st" id="yiyi-758">Exceptions</span></h2><p><span class="yiyi-st" id="yiyi-759">The following exception classes are defined in the <a class="reference internal" href="#module-mailbox" title="mailbox: Manipulate mailboxes in various formats"><code class="xref py py-mod docutils literal"><span class="pre">mailbox</span></code></a> module:</span></p><dl class="exception"><dt id="mailbox.Error"><span class="yiyi-st" id="yiyi-760"> <em class="property">exception </em><code class="descclassname">mailbox.</code><code class="descname">Error</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-761">The based class for all other module-specific exceptions.</span></p></dd></dl><dl class="exception"><dt id="mailbox.NoSuchMailboxError"><span class="yiyi-st" id="yiyi-762"> <em class="property">exception </em><code class="descclassname">mailbox.</code><code class="descname">NoSuchMailboxError</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-763">Raised when a mailbox is expected but is not found, such as when instantiating a <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal"><span class="pre">Mailbox</span></code></a> subclass with a path that does not exist (and with the <em>create</em> parameter set to <code class="docutils literal"><span class="pre">False</span></code>), or when opening a folder that does not exist.</span></p></dd></dl><dl class="exception"><dt id="mailbox.NotEmptyError"><span class="yiyi-st" id="yiyi-764"> <em class="property">exception </em><code class="descclassname">mailbox.</code><code class="descname">NotEmptyError</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-765">Raised when a mailbox is not empty but is expected to be, such as when deleting a folder that contains messages.</span></p></dd></dl><dl class="exception"><dt id="mailbox.ExternalClashError"><span class="yiyi-st" id="yiyi-766"> <em class="property">exception </em><code class="descclassname">mailbox.</code><code class="descname">ExternalClashError</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-767">Raised when some mailbox-related condition beyond the control of the program causes it to be unable to proceed, such as when failing to acquire a lock that another program already holds a lock, or when a uniquely-generated file name already exists.</span></p></dd></dl><dl class="exception"><dt id="mailbox.FormatError"><span class="yiyi-st" id="yiyi-768"> <em class="property">exception </em><code class="descclassname">mailbox.</code><code class="descname">FormatError</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-769">Raised when the data in a file cannot be parsed, such as when an <a class="reference internal" href="#mailbox.MH" title="mailbox.MH"><code class="xref py py-class docutils literal"><span class="pre">MH</span></code></a> instance attempts to read a corrupted <code class="file docutils literal"><span class="pre">.mh_sequences</span></code> file.</span></p></dd></dl></div><div class="section" id="examples"><h2><span class="yiyi-st" id="yiyi-770">19.4.4. </span><span class="yiyi-st" id="yiyi-771">Examples</span></h2><p><span class="yiyi-st" id="yiyi-772">A simple example of printing the subjects of all messages in a mailbox that seem interesting:</span></p><pre><code class="language-python"><span></span><span class="kn">import</span> <span class="nn">mailbox</span>
<span class="k">for</span> <span class="n">message</span> <span class="ow">in</span> <span class="n">mailbox</span><span class="o">.</span><span class="n">mbox</span><span class="p">(</span><span class="s1">'~/mbox'</span><span class="p">):</span>
<span class="n">subject</span> <span class="o">=</span> <span class="n">message</span><span class="p">[</span><span class="s1">'subject'</span><span class="p">]</span> <span class="c1"># Could possibly be None.</span>
<span class="k">if</span> <span class="n">subject</span> <span class="ow">and</span> <span class="s1">'python'</span> <span class="ow">in</span> <span class="n">subject</span><span class="o">.</span><span class="n">lower</span><span class="p">():</span>
<span class="nb">print</span><span class="p">(</span><span class="n">subject</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-773">To copy all mail from a Babyl mailbox to an MH mailbox, converting all of the format-specific information that can be converted:</span></p><pre><code class="language-python"><span></span><span class="kn">import</span> <span class="nn">mailbox</span>
<span class="n">destination</span> <span class="o">=</span> <span class="n">mailbox</span><span class="o">.</span><span class="n">MH</span><span class="p">(</span><span class="s1">'~/Mail'</span><span class="p">)</span>
<span class="n">destination</span><span class="o">.</span><span class="n">lock</span><span class="p">()</span>
<span class="k">for</span> <span class="n">message</span> <span class="ow">in</span> <span class="n">mailbox</span><span class="o">.</span><span class="n">Babyl</span><span class="p">(</span><span class="s1">'~/RMAIL'</span><span class="p">):</span>
<span class="n">destination</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">mailbox</span><span class="o">.</span><span class="n">MHMessage</span><span class="p">(</span><span class="n">message</span><span class="p">))</span>
<span class="n">destination</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span>
<span class="n">destination</span><span class="o">.</span><span class="n">unlock</span><span class="p">()</span>
</code></pre><p><span class="yiyi-st" id="yiyi-774">This example sorts mail from several mailing lists into different mailboxes, being careful to avoid mail corruption due to concurrent modification by other programs, mail loss due to interruption of the program, or premature termination due to malformed messages in the mailbox:</span></p><pre><code class="language-python"><span></span><span class="kn">import</span> <span class="nn">mailbox</span>
<span class="kn">import</span> <span class="nn">email.errors</span>
<span class="n">list_names</span> <span class="o">=</span> <span class="p">(</span><span class="s1">'python-list'</span><span class="p">,</span> <span class="s1">'python-dev'</span><span class="p">,</span> <span class="s1">'python-bugs'</span><span class="p">)</span>
<span class="n">boxes</span> <span class="o">=</span> <span class="p">{</span><span class="n">name</span><span class="p">:</span> <span class="n">mailbox</span><span class="o">.</span><span class="n">mbox</span><span class="p">(</span><span class="s1">'~/email/</span><span class="si">%s</span><span class="s1">'</span> <span class="o">%</span> <span class="n">name</span><span class="p">)</span> <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">list_names</span><span class="p">}</span>
<span class="n">inbox</span> <span class="o">=</span> <span class="n">mailbox</span><span class="o">.</span><span class="n">Maildir</span><span class="p">(</span><span class="s1">'~/Maildir'</span><span class="p">,</span> <span class="n">factory</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>
<span class="k">for</span> <span class="n">key</span> <span class="ow">in</span> <span class="n">inbox</span><span class="o">.</span><span class="n">iterkeys</span><span class="p">():</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">message</span> <span class="o">=</span> <span class="n">inbox</span><span class="p">[</span><span class="n">key</span><span class="p">]</span>
<span class="k">except</span> <span class="n">email</span><span class="o">.</span><span class="n">errors</span><span class="o">.</span><span class="n">MessageParseError</span><span class="p">:</span>
<span class="k">continue</span> <span class="c1"># The message is malformed. Just leave it.</span>
<span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">list_names</span><span class="p">:</span>
<span class="n">list_id</span> <span class="o">=</span> <span class="n">message</span><span class="p">[</span><span class="s1">'list-id'</span><span class="p">]</span>
<span class="k">if</span> <span class="n">list_id</span> <span class="ow">and</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">list_id</span><span class="p">:</span>
<span class="c1"># Get mailbox to use</span>
<span class="n">box</span> <span class="o">=</span> <span class="n">boxes</span><span class="p">[</span><span class="n">name</span><span class="p">]</span>
<span class="c1"># Write copy to disk before removing original.</span>
<span class="c1"># If there's a crash, you might duplicate a message, but</span>
<span class="c1"># that's better than losing a message completely.</span>
<span class="n">box</span><span class="o">.</span><span class="n">lock</span><span class="p">()</span>
<span class="n">box</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>
<span class="n">box</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span>
<span class="n">box</span><span class="o">.</span><span class="n">unlock</span><span class="p">()</span>
<span class="c1"># Remove original message</span>
<span class="n">inbox</span><span class="o">.</span><span class="n">lock</span><span class="p">()</span>
<span class="n">inbox</span><span class="o">.</span><span class="n">discard</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
<span class="n">inbox</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span>
<span class="n">inbox</span><span class="o">.</span><span class="n">unlock</span><span class="p">()</span>
<span class="k">break</span> <span class="c1"># Found destination, so stop looking.</span>
<span class="k">for</span> <span class="n">box</span> <span class="ow">in</span> <span class="n">boxes</span><span class="o">.</span><span class="n">itervalues</span><span class="p">():</span>
<span class="n">box</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</code></pre></div></div></div>
Reference in New Issue View Git Blame Copy Permalink