Team Ai
Apppublic

parthtamu/rag-code-assistant

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
mailbox.html2383 linesDownload Raw Back to docs
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4  <head>5    <meta charset="utf-8" />6    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="mailbox — Manipulate mailboxes in various formats" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/mailbox.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/mailbox.py This module defines two classes, Mailbox and Message, for accessing and manipulating on-disk mailboxes and the messages they contain. Mailbox offers a dictionary-like ma..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_mailbox_38ccd73f.png" />15<meta property="og:image:alt" content="Source code: Lib/mailbox.py This module defines two classes, Mailbox and Message, for accessing and manipulating on-disk mailboxes and the messages they contain. Mailbox offers a dictionary-like ma..." />16<meta name="description" content="Source code: Lib/mailbox.py This module defines two classes, Mailbox and Message, for accessing and manipulating on-disk mailboxes and the messages they contain. Mailbox offers a dictionary-like ma..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20    <title>mailbox — Manipulate mailboxes in various formats &#8212; Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21    22    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25    <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27    28    <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29    <script src="../_static/doctools.js?v=9bcbadda"></script>30    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31    <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32    33    <script src="../_static/sidebar.js"></script>34    35    <link rel="search" type="application/opensearchdescription+xml"36          title="Search within Python 3.15.0a6 documentation"37          href="../_static/opensearch.xml"/>38    <link rel="author" title="About these documents" href="../about.html" />39    <link rel="index" title="Index" href="../genindex.html" />40    <link rel="search" title="Search" href="../search.html" />41    <link rel="copyright" title="Copyright" href="../copyright.html" />42    <link rel="next" title="mimetypes — Map filenames to MIME types" href="mimetypes.html" />43    <link rel="prev" title="json — JSON encoder and decoder" href="json.html" />44    45      46      <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47      48      <link rel="canonical" href="https://docs.python.org/3/library/mailbox.html">49      50    51 52    53    <style>54      @media only screen {55        table.full-width-table {56            width: 100%;57        }58      }59    </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61    <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62            <script type="text/javascript" src="../_static/copybutton.js"></script>63            <script type="text/javascript" src="../_static/menu.js"></script>64            <script type="text/javascript" src="../_static/search-focus.js"></script>65            <script type="text/javascript" src="../_static/themetoggle.js"></script> 66            <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67            <meta name="readthedocs-addons-api-version" content="1">68 69  </head>70<body>71<div class="mobile-nav">72    <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73           aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74    <nav class="nav-content" role="navigation">75        <label for="menuToggler" class="toggler__label">76            <span></span>77        </label>78        <span class="nav-items-wrapper">79            <a href="https://www.python.org/" class="nav-logo">80                <img src="../_static/py.svg" alt="Python logo">81            </a>82            <span class="version_switcher_placeholder"></span>83            <form role="search" class="search" action="../search.html" method="get">84                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85                    <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86                </svg>87                <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88                <input type="submit" value="Go">89            </form>90        </span>91    </nav>92    <div class="menu-wrapper">93        <nav class="menu" role="navigation" aria-label="main navigation">94            <div class="language_switcher_placeholder"></div>95            96<label class="theme-selector-label">97    Theme98    <select class="theme-selector" oninput="activateTheme(this.value)">99        <option value="auto" selected>Auto</option>100        <option value="light">Light</option>101        <option value="dark">Dark</option>102    </select>103</label>104  <div>105    <h3><a href="../contents.html">Table of Contents</a></h3>106    <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">mailbox</span></code> — Manipulate mailboxes in various formats</a><ul>108<li><a class="reference internal" href="#mailbox-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> objects</a><ul>109<li><a class="reference internal" href="#maildir-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">Maildir</span></code> objects</a></li>110<li><a class="reference internal" href="#mbox-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">mbox</span></code> objects</a></li>111<li><a class="reference internal" href="#mh-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">MH</span></code> objects</a></li>112<li><a class="reference internal" href="#babyl-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">Babyl</span></code> objects</a></li>113<li><a class="reference internal" href="#mmdf-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">MMDF</span></code> objects</a></li>114</ul>115</li>116<li><a class="reference internal" href="#message-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code> objects</a><ul>117<li><a class="reference internal" href="#maildirmessage-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">MaildirMessage</span></code> objects</a></li>118<li><a class="reference internal" href="#mboxmessage-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">mboxMessage</span></code> objects</a></li>119<li><a class="reference internal" href="#mhmessage-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">MHMessage</span></code> objects</a></li>120<li><a class="reference internal" href="#babylmessage-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">BabylMessage</span></code> objects</a></li>121<li><a class="reference internal" href="#mmdfmessage-objects"><code class="xref py py-class docutils literal notranslate"><span class="pre">MMDFMessage</span></code> objects</a></li>122</ul>123</li>124<li><a class="reference internal" href="#exceptions">Exceptions</a></li>125<li><a class="reference internal" href="#examples">Examples</a></li>126</ul>127</li>128</ul>129 130  </div>131  <div>132    <h4>Previous topic</h4>133    <p class="topless"><a href="json.html"134                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">json</span></code> — JSON encoder and decoder</a></p>135  </div>136  <div>137    <h4>Next topic</h4>138    <p class="topless"><a href="mimetypes.html"139                          title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">mimetypes</span></code> — Map filenames to MIME types</a></p>140  </div>141  <script>142    document.addEventListener('DOMContentLoaded', () => {143        const title = document.querySelector('meta[property="og:title"]').content;144        const elements = document.querySelectorAll('.improvepage');145        const pageurl = window.location.href.split('?')[0];146        elements.forEach(element => {147            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));148            url.searchParams.set('pagetitle', title);149            url.searchParams.set('pageurl', pageurl);150            url.searchParams.set('pagesource', "library/mailbox.rst");151            element.href = url.toString();152        });153    });154  </script>155  <div role="note" aria-label="source link">156    <h3>This page</h3>157    <ul class="this-page-menu">158      <li><a href="../bugs.html">Report a bug</a></li>159      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>160      <li>161        <a href="https://github.com/python/cpython/blob/main/Doc/library/mailbox.rst?plain=1"162            rel="nofollow">Show source163        </a>164      </li>165      166    </ul>167  </div>168        </nav>169    </div>170</div>171 172  173    <div class="related" role="navigation" aria-label="Related">174      <h3>Navigation</h3>175      <ul>176        <li class="right" style="margin-right: 10px">177          <a href="../genindex.html" title="General Index"178             accesskey="I">index</a></li>179        <li class="right" >180          <a href="../py-modindex.html" title="Python Module Index"181             >modules</a> |</li>182        <li class="right" >183          <a href="mimetypes.html" title="mimetypes — Map filenames to MIME types"184             accesskey="N">next</a> |</li>185        <li class="right" >186          <a href="json.html" title="json — JSON encoder and decoder"187             accesskey="P">previous</a> |</li>188 189          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>190          <li><a href="https://www.python.org/">Python</a> &#187;</li>191          <li class="switchers">192            <div class="language_switcher_placeholder"></div>193            <div class="version_switcher_placeholder"></div>194          </li>195          <li>196              197          </li>198    <li id="cpython-language-and-version">199      <a href="../index.html">3.15.0a6 Documentation</a> &#187;200    </li>201 202          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>203          <li class="nav-item nav-item-2"><a href="netdata.html" accesskey="U">Internet Data Handling</a> &#187;</li>204        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">mailbox</span></code> — Manipulate mailboxes in various formats</a></li>205                <li class="right">206                    207 208    <div class="inline-search" role="search">209        <form class="inline-search" action="../search.html" method="get">210          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">211          <input type="submit" value="Go">212        </form>213    </div>214                     |215                </li>216            <li class="right">217<label class="theme-selector-label">218    Theme219    <select class="theme-selector" oninput="activateTheme(this.value)">220        <option value="auto" selected>Auto</option>221        <option value="light">Light</option>222        <option value="dark">Dark</option>223    </select>224</label> |</li>225            226      </ul>227    </div>    228 229    <div class="document">230      <div class="documentwrapper">231        <div class="bodywrapper">232          <div class="body" role="main">233            234  <section id="module-mailbox">235<span id="mailbox-manipulate-mailboxes-in-various-formats"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">mailbox</span></code> — Manipulate mailboxes in various formats<a class="headerlink" href="#module-mailbox" title="Link to this heading">¶</a></h1>236<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/mailbox.py">Lib/mailbox.py</a></p>237<hr class="docutils" />238<p>This module defines two classes, <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal notranslate"><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 notranslate"><span class="pre">Message</span></code></a>, for239accessing and manipulating on-disk mailboxes and the messages they contain.240<code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> offers a dictionary-like mapping from keys to messages.241<code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code> 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 notranslate"><span class="pre">email.message</span></code></a> module’s242<a class="reference internal" href="email.compat32-message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> class with format-specific state and behavior.243Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.</p>244<div class="admonition seealso">245<p class="admonition-title">See also</p>246<dl class="simple">247<dt>Module <a class="reference internal" href="email.html#module-email" title="email: Package supporting the parsing, manipulating, and generating email messages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email</span></code></a></dt><dd><p>Represent and manipulate messages.</p>248</dd>249</dl>250</div>251<section id="mailbox-objects">252<span id="id1"></span><h2><code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> objects<a class="headerlink" href="#mailbox-objects" title="Link to this heading">¶</a></h2>253<dl class="py class">254<dt class="sig sig-object py" id="mailbox.Mailbox">255<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">mailbox.</span></span><span class="sig-name descname"><span class="pre">Mailbox</span></span><a class="headerlink" href="#mailbox.Mailbox" title="Link to this definition">¶</a></dt>256<dd><p>A mailbox, which may be inspected and modified.</p>257<p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> class defines an interface and is not intended to be258instantiated.  Instead, format-specific subclasses should inherit from259<code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> and your code should instantiate a particular subclass.</p>260<p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> interface is dictionary-like, with small keys261corresponding to messages. Keys are issued by the <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> instance262with which they will be used and are only meaningful to that <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code>263instance. A key continues to identify a message even if the corresponding264message is modified, such as by replacing it with another message.</p>265<p>Messages may be added to a <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> instance using the set-like266method <a class="reference internal" href="#mailbox.Mailbox.add" title="mailbox.Mailbox.add"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add()</span></code></a> and removed using a <code class="docutils literal notranslate"><span class="pre">del</span></code> statement or the set-like267methods <a class="reference internal" href="#mailbox.Mailbox.remove" title="mailbox.Mailbox.remove"><code class="xref py py-meth docutils literal notranslate"><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 notranslate"><span class="pre">discard()</span></code></a>.</p>268<p><code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> interface semantics differ from dictionary semantics in some269noteworthy ways. Each time a message is requested, a new representation270(typically a <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> instance) is generated based upon the current271state of the mailbox. Similarly, when a message is added to a272<code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> instance, the provided message representation’s contents are273copied. In neither case is a reference to the message representation kept by274the <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> instance.</p>275<p>The default <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> iterates over message276representations, not keys as the default <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dictionary</span></code></a>277iterator does. Moreover, modification of a278mailbox during iteration is safe and well-defined. Messages added to the279mailbox after an iterator is created will not be seen by the280iterator. Messages removed from the mailbox before the iterator yields them281will be silently skipped, though using a key from an iterator may result in a282<a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> exception if the corresponding message is subsequently283removed.</p>284<div class="admonition warning">285<p class="admonition-title">Warning</p>286<p>Be very cautious when modifying mailboxes that might be simultaneously287changed by some other process.  The safest mailbox format to use for such288tasks is <a class="reference internal" href="#mailbox.Maildir" title="mailbox.Maildir"><code class="xref py py-class docutils literal notranslate"><span class="pre">Maildir</span></code></a>; try to avoid using single-file formats such as289<a class="reference internal" href="#mailbox.mbox" title="mailbox.mbox"><code class="xref py py-class docutils literal notranslate"><span class="pre">mbox</span></code></a> for290concurrent writing.  If you’re modifying a mailbox, you <em>must</em> lock it by291calling the <a class="reference internal" href="#mailbox.Mailbox.lock" title="mailbox.Mailbox.lock"><code class="xref py py-meth docutils literal notranslate"><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 notranslate"><span class="pre">unlock()</span></code></a> methods <em>before</em> reading any292messages in the file or making any changes by adding or deleting a293message.  Failing to lock the mailbox runs the risk of losing messages or294corrupting the entire mailbox.</p>295</div>296<p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> class supports the <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement.  When used297as a context manager, <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> calls <a class="reference internal" href="#mailbox.Mailbox.lock" title="mailbox.Mailbox.lock"><code class="xref py py-meth docutils literal notranslate"><span class="pre">lock()</span></code></a> when the context is entered,298returns the mailbox object as the context object, and at context end calls <a class="reference internal" href="#mailbox.Mailbox.close" title="mailbox.Mailbox.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a>,299thereby releasing the lock.</p>300<div class="versionchanged">301<p><span class="versionmodified changed">Changed in version 3.15.0a6 (unreleased): </span>Support for the <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement was added.</p>302</div>303<p><code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> instances have the following methods:</p>304<dl class="py method">305<dt class="sig sig-object py" id="mailbox.Mailbox.add">306<span class="sig-name descname"><span class="pre">add</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">message</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.add" title="Link to this definition">¶</a></dt>307<dd><p>Add <em>message</em> to the mailbox and return the key that has been assigned to308it.</p>309<p>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 notranslate"><span class="pre">Message</span></code></a> instance, an310<a class="reference internal" href="email.compat32-message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">email.message.Message</span></code></a> instance, a string, a byte string, or a311file-like object (which should be open in binary mode). If <em>message</em> is312an instance of the313appropriate format-specific <code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code> subclass (e.g., if it’s an314<a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal notranslate"><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 notranslate"><span class="pre">mbox</span></code></a> instance), its315format-specific information is used. Otherwise, reasonable defaults for316format-specific information are used.</p>317<div class="versionchanged">318<p><span class="versionmodified changed">Changed in version 3.2: </span>Support for binary input was added.</p>319</div>320</dd></dl>321 322<dl class="py method">323<dt class="sig sig-object py" id="mailbox.Mailbox.remove">324<span class="sig-name descname"><span class="pre">remove</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.remove" title="Link to this definition">¶</a></dt>325<dt class="sig sig-object py" id="mailbox.Mailbox.__delitem__">326<span class="sig-name descname"><span class="pre">__delitem__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.__delitem__" title="Link to this definition">¶</a></dt>327<dt class="sig sig-object py" id="mailbox.Mailbox.discard">328<span class="sig-name descname"><span class="pre">discard</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.discard" title="Link to this definition">¶</a></dt>329<dd><p>Delete the message corresponding to <em>key</em> from the mailbox.</p>330<p>If no such message exists, a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> exception is raised if the331method was called as <code class="xref py py-meth docutils literal notranslate"><span class="pre">remove()</span></code> or <code class="xref py py-meth docutils literal notranslate"><span class="pre">__delitem__()</span></code> but no332exception is raised if the method was called as <code class="xref py py-meth docutils literal notranslate"><span class="pre">discard()</span></code>. The333behavior of <code class="xref py py-meth docutils literal notranslate"><span class="pre">discard()</span></code> may be preferred if the underlying mailbox334format supports concurrent modification by other processes.</p>335</dd></dl>336 337<dl class="py method">338<dt class="sig sig-object py" id="mailbox.Mailbox.__setitem__">339<span class="sig-name descname"><span class="pre">__setitem__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">message</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.__setitem__" title="Link to this definition">¶</a></dt>340<dd><p>Replace the message corresponding to <em>key</em> with <em>message</em>. Raise a341<a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> exception if no message already corresponds to <em>key</em>.</p>342<p>As with <a class="reference internal" href="#mailbox.Mailbox.add" title="mailbox.Mailbox.add"><code class="xref py py-meth docutils literal notranslate"><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 notranslate"><span class="pre">Message</span></code></a>343instance, an <a class="reference internal" href="email.compat32-message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">email.message.Message</span></code></a> instance, a string, a byte344string, or a file-like object (which should be open in binary mode). If345<em>message</em> is an346instance of the appropriate format-specific <code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code> subclass347(e.g., if it’s an <a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">mboxMessage</span></code></a> instance and this is an348<a class="reference internal" href="#mailbox.mbox" title="mailbox.mbox"><code class="xref py py-class docutils literal notranslate"><span class="pre">mbox</span></code></a> instance), its format-specific information is349used. Otherwise, the format-specific information of the message that350currently corresponds to <em>key</em> is left unchanged.</p>351</dd></dl>352 353<dl class="py method">354<dt class="sig sig-object py" id="mailbox.Mailbox.iterkeys">355<span class="sig-name descname"><span class="pre">iterkeys</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.iterkeys" title="Link to this definition">¶</a></dt>356<dd><p>Return an <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> over all keys</p>357</dd></dl>358 359<dl class="py method">360<dt class="sig sig-object py" id="mailbox.Mailbox.keys">361<span class="sig-name descname"><span class="pre">keys</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.keys" title="Link to this definition">¶</a></dt>362<dd><p>The same as <a class="reference internal" href="#mailbox.Mailbox.iterkeys" title="mailbox.Mailbox.iterkeys"><code class="xref py py-meth docutils literal notranslate"><span class="pre">iterkeys()</span></code></a>, except that a <a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a> is returned363rather than an <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a></p>364</dd></dl>365 366<dl class="py method">367<dt class="sig sig-object py" id="mailbox.Mailbox.itervalues">368<span class="sig-name descname"><span class="pre">itervalues</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.itervalues" title="Link to this definition">¶</a></dt>369<dt class="sig sig-object py" id="mailbox.Mailbox.__iter__">370<span class="sig-name descname"><span class="pre">__iter__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.__iter__" title="Link to this definition">¶</a></dt>371<dd><p>Return an <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> over representations of all messages.372The messages are represented373as instances of the appropriate format-specific <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> subclass374unless a custom message factory was specified when the <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code>375instance was initialized.</p>376<div class="admonition note">377<p class="admonition-title">Note</p>378<p>The behavior of <code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code> is unlike that of dictionaries, which379iterate over keys.</p>380</div>381</dd></dl>382 383<dl class="py method">384<dt class="sig sig-object py" id="mailbox.Mailbox.values">385<span class="sig-name descname"><span class="pre">values</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.values" title="Link to this definition">¶</a></dt>386<dd><p>The same as <a class="reference internal" href="#mailbox.Mailbox.itervalues" title="mailbox.Mailbox.itervalues"><code class="xref py py-meth docutils literal notranslate"><span class="pre">itervalues()</span></code></a>, except that a <a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a> is returned387rather than an <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a></p>388</dd></dl>389 390<dl class="py method">391<dt class="sig sig-object py" id="mailbox.Mailbox.iteritems">392<span class="sig-name descname"><span class="pre">iteritems</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.iteritems" title="Link to this definition">¶</a></dt>393<dd><p>Return an <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> over (<em>key</em>, <em>message</em>) pairs, where <em>key</em> is394a key and <em>message</em> is a message representation. The messages are395represented as instances of the appropriate format-specific396<a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> subclass unless a custom message factory was specified397when the <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> instance was initialized.</p>398</dd></dl>399 400<dl class="py method">401<dt class="sig sig-object py" id="mailbox.Mailbox.items">402<span class="sig-name descname"><span class="pre">items</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.items" title="Link to this definition">¶</a></dt>403<dd><p>The same as <a class="reference internal" href="#mailbox.Mailbox.iteritems" title="mailbox.Mailbox.iteritems"><code class="xref py py-meth docutils literal notranslate"><span class="pre">iteritems()</span></code></a>, except that a <a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a> of pairs is404returned rather than an <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> of pairs.</p>405</dd></dl>406 407<dl class="py method">408<dt class="sig sig-object py" id="mailbox.Mailbox.get">409<span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.get" title="Link to this definition">¶</a></dt>410<dt class="sig sig-object py" id="mailbox.Mailbox.__getitem__">411<span class="sig-name descname"><span class="pre">__getitem__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.__getitem__" title="Link to this definition">¶</a></dt>412<dd><p>Return a representation of the message corresponding to <em>key</em>. If no such413message exists, <em>default</em> is returned if the method was called as414<code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code> and a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> exception is raised if the method was415called as <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code>. The message is represented as an instance416of the appropriate format-specific <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> subclass unless a417custom message factory was specified when the <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> instance418was initialized.</p>419</dd></dl>420 421<dl class="py method">422<dt class="sig sig-object py" id="mailbox.Mailbox.get_message">423<span class="sig-name descname"><span class="pre">get_message</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.get_message" title="Link to this definition">¶</a></dt>424<dd><p>Return a representation of the message corresponding to <em>key</em> as an425instance of the appropriate format-specific <a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> subclass, or426raise a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> exception if no such message exists.</p>427</dd></dl>428 429<dl class="py method">430<dt class="sig sig-object py" id="mailbox.Mailbox.get_bytes">431<span class="sig-name descname"><span class="pre">get_bytes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.get_bytes" title="Link to this definition">¶</a></dt>432<dd><p>Return a byte representation of the message corresponding to <em>key</em>, or433raise a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> exception if no such message exists.</p>434<div class="versionadded">435<p><span class="versionmodified added">Added in version 3.2.</span></p>436</div>437</dd></dl>438 439<dl class="py method">440<dt class="sig sig-object py" id="mailbox.Mailbox.get_string">441<span class="sig-name descname"><span class="pre">get_string</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.get_string" title="Link to this definition">¶</a></dt>442<dd><p>Return a string representation of the message corresponding to <em>key</em>, or443raise a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> exception if no such message exists.  The444message is processed through <a class="reference internal" href="email.compat32-message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">email.message.Message</span></code></a> to445convert it to a 7bit clean representation.</p>446</dd></dl>447 448<dl class="py method">449<dt class="sig sig-object py" id="mailbox.Mailbox.get_file">450<span class="sig-name descname"><span class="pre">get_file</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.get_file" title="Link to this definition">¶</a></dt>451<dd><p>Return a <a class="reference internal" href="../glossary.html#term-file-like-object"><span class="xref std std-term">file-like</span></a> representation of the452message corresponding to <em>key</em>,453or raise a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> exception if no such message exists.  The454file-like object behaves as if open in binary mode.  This file should be455closed once it is no longer needed.</p>456<div class="versionchanged">457<p><span class="versionmodified changed">Changed in version 3.2: </span>The file object really is a <a class="reference internal" href="../glossary.html#term-binary-file"><span class="xref std std-term">binary file</span></a>; previously it was458incorrectly returned in text mode.  Also, the <a class="reference internal" href="../glossary.html#term-file-like-object"><span class="xref std std-term">file-like object</span></a>459now supports the <a class="reference internal" href="../glossary.html#term-context-manager"><span class="xref std std-term">context manager</span></a> protocol: you can use a460<a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement to automatically close it.</p>461</div>462<div class="admonition note">463<p class="admonition-title">Note</p>464<p>Unlike other representations of messages,465<a class="reference internal" href="../glossary.html#term-file-like-object"><span class="xref std std-term">file-like</span></a> representations are not466necessarily independent of the <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> instance that467created them or of the underlying mailbox.  More specific documentation468is provided by each subclass.</p>469</div>470</dd></dl>471 472<dl class="py method">473<dt class="sig sig-object py" id="mailbox.Mailbox.__contains__">474<span class="sig-name descname"><span class="pre">__contains__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.__contains__" title="Link to this definition">¶</a></dt>475<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>key</em> corresponds to a message, <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise.</p>476</dd></dl>477 478<dl class="py method">479<dt class="sig sig-object py" id="mailbox.Mailbox.__len__">480<span class="sig-name descname"><span class="pre">__len__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.__len__" title="Link to this definition">¶</a></dt>481<dd><p>Return a count of messages in the mailbox.</p>482</dd></dl>483 484<dl class="py method">485<dt class="sig sig-object py" id="mailbox.Mailbox.clear">486<span class="sig-name descname"><span class="pre">clear</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.clear" title="Link to this definition">¶</a></dt>487<dd><p>Delete all messages from the mailbox.</p>488</dd></dl>489 490<dl class="py method">491<dt class="sig sig-object py" id="mailbox.Mailbox.pop">492<span class="sig-name descname"><span class="pre">pop</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.pop" title="Link to this definition">¶</a></dt>493<dd><p>Return a representation of the message corresponding to <em>key</em> and delete494the message. If no such message exists, return <em>default</em>. The message is495represented as an instance of the appropriate format-specific496<a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> subclass unless a custom message factory was specified497when the <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> instance was initialized.</p>498</dd></dl>499 500<dl class="py method">501<dt class="sig sig-object py" id="mailbox.Mailbox.popitem">502<span class="sig-name descname"><span class="pre">popitem</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.popitem" title="Link to this definition">¶</a></dt>503<dd><p>Return an arbitrary (<em>key</em>, <em>message</em>) pair, where <em>key</em> is a key and504<em>message</em> is a message representation, and delete the corresponding505message. 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 notranslate"><span class="pre">KeyError</span></code></a> exception. The506message is represented as an instance of the appropriate format-specific507<a class="reference internal" href="#mailbox.Message" title="mailbox.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> subclass unless a custom message factory was specified508when the <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> instance was initialized.</p>509</dd></dl>510 511<dl class="py method">512<dt class="sig sig-object py" id="mailbox.Mailbox.update">513<span class="sig-name descname"><span class="pre">update</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">arg</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.update" title="Link to this definition">¶</a></dt>514<dd><p>Parameter <em>arg</em> should be a <em>key</em>-to-<em>message</em> mapping or an iterable of515(<em>key</em>, <em>message</em>) pairs. Updates the mailbox so that, for each given516<em>key</em> and <em>message</em>, the message corresponding to <em>key</em> is set to517<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 notranslate"><span class="pre">__setitem__()</span></code></a>. As with <code class="xref py py-meth docutils literal notranslate"><span class="pre">__setitem__()</span></code>,518each <em>key</em> must already correspond to a message in the mailbox or else a519<a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> exception will be raised, so in general it is incorrect520for <em>arg</em> to be a <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> instance.</p>521<div class="admonition note">522<p class="admonition-title">Note</p>523<p>Unlike with dictionaries, keyword arguments are not supported.</p>524</div>525</dd></dl>526 527<dl class="py method">528<dt class="sig sig-object py" id="mailbox.Mailbox.flush">529<span class="sig-name descname"><span class="pre">flush</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.flush" title="Link to this definition">¶</a></dt>530<dd><p>Write any pending changes to the filesystem. For some <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code>531subclasses, changes are always written immediately and <code class="xref py py-meth docutils literal notranslate"><span class="pre">flush()</span></code> does532nothing, but you should still make a habit of calling this method.</p>533</dd></dl>534 535<dl class="py method">536<dt class="sig sig-object py" id="mailbox.Mailbox.lock">537<span class="sig-name descname"><span class="pre">lock</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.lock" title="Link to this definition">¶</a></dt>538<dd><p>Acquire an exclusive advisory lock on the mailbox so that other processes539know not to modify it. An <a class="reference internal" href="#mailbox.ExternalClashError" title="mailbox.ExternalClashError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ExternalClashError</span></code></a> is raised if the lock540is not available. The particular locking mechanisms used depend upon the541mailbox format.  You should <em>always</em> lock the mailbox before making any542modifications to its contents.</p>543</dd></dl>544 545<dl class="py method">546<dt class="sig sig-object py" id="mailbox.Mailbox.unlock">547<span class="sig-name descname"><span class="pre">unlock</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.unlock" title="Link to this definition">¶</a></dt>548<dd><p>Release the lock on the mailbox, if any.</p>549</dd></dl>550 551<dl class="py method">552<dt class="sig sig-object py" id="mailbox.Mailbox.close">553<span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Mailbox.close" title="Link to this definition">¶</a></dt>554<dd><p>Flush the mailbox, unlock it if necessary, and close any open files. For555some <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> subclasses, this method does nothing.</p>556</dd></dl>557 558</dd></dl>559 560<section id="maildir-objects">561<span id="mailbox-maildir"></span><h3><code class="xref py py-class docutils literal notranslate"><span class="pre">Maildir</span></code> objects<a class="headerlink" href="#maildir-objects" title="Link to this heading">¶</a></h3>562<dl class="py class">563<dt class="sig sig-object py" id="mailbox.Maildir">564<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">mailbox.</span></span><span class="sig-name descname"><span class="pre">Maildir</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dirname</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">factory</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">create</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir" title="Link to this definition">¶</a></dt>565<dd><p>A subclass of <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code></a> for mailboxes in Maildir format. Parameter566<em>factory</em> is a callable object that accepts a file-like message representation567(which behaves as if opened in binary mode) and returns a custom representation.568If <em>factory</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">MaildirMessage</span></code></a> is used as the default message569representation. If <em>create</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the mailbox is created if it does not570exist.</p>571<p>If <em>create</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code> and the <em>dirname</em> path exists, it will be treated as572an existing maildir without attempting to verify its directory layout.</p>573<p>It is for historical reasons that <em>dirname</em> is named as such rather than <em>path</em>.</p>574<p>Maildir is a directory-based mailbox format invented for the qmail mail575transfer agent and now widely supported by other programs. Messages in a576Maildir mailbox are stored in separate files within a common directory577structure. This design allows Maildir mailboxes to be accessed and modified578by multiple unrelated programs without data corruption, so file locking is579unnecessary.</p>580<p>Maildir mailboxes contain three subdirectories, namely: <code class="file docutils literal notranslate"><span class="pre">tmp</span></code>,581<code class="file docutils literal notranslate"><span class="pre">new</span></code>, and <code class="file docutils literal notranslate"><span class="pre">cur</span></code>. Messages are created momentarily in the582<code class="file docutils literal notranslate"><span class="pre">tmp</span></code> subdirectory and then moved to the <code class="file docutils literal notranslate"><span class="pre">new</span></code> subdirectory to583finalize delivery. A mail user agent may subsequently move the message to the584<code class="file docutils literal notranslate"><span class="pre">cur</span></code> subdirectory and store information about the state of the message585in a special “info” section appended to its file name.</p>586<p>Folders of the style introduced by the Courier mail transfer agent are also587supported. Any subdirectory of the main mailbox is considered a folder if588<code class="docutils literal notranslate"><span class="pre">'.'</span></code> is the first character in its name. Folder names are represented by589<code class="xref py py-class docutils literal notranslate"><span class="pre">Maildir</span></code> without the leading <code class="docutils literal notranslate"><span class="pre">'.'</span></code>. Each folder is itself a Maildir590mailbox but should not contain other folders. Instead, a logical nesting is591indicated using <code class="docutils literal notranslate"><span class="pre">'.'</span></code> to delimit levels, e.g., “Archived.2005.07”.</p>592<dl class="py attribute">593<dt class="sig sig-object py" id="mailbox.Maildir.colon">594<span class="sig-name descname"><span class="pre">colon</span></span><a class="headerlink" href="#mailbox.Maildir.colon" title="Link to this definition">¶</a></dt>595<dd><p>The Maildir specification requires the use of a colon (<code class="docutils literal notranslate"><span class="pre">':'</span></code>) in certain596message file names. However, some operating systems do not permit this597character in file names, If you wish to use a Maildir-like format on such598an operating system, you should specify another character to use599instead. The exclamation point (<code class="docutils literal notranslate"><span class="pre">'!'</span></code>) is a popular choice. For600example:</p>601<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">mailbox</span>602<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">&#39;!&#39;</span>603</pre></div>604</div>605<p>The <code class="xref py py-attr docutils literal notranslate"><span class="pre">colon</span></code> attribute may also be set on a per-instance basis.</p>606</dd></dl>607 608<div class="versionchanged">609<p><span class="versionmodified changed">Changed in version 3.13: </span><code class="xref py py-class docutils literal notranslate"><span class="pre">Maildir</span></code> now ignores files with a leading dot.</p>610</div>611<p><code class="xref py py-class docutils literal notranslate"><span class="pre">Maildir</span></code> 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 notranslate"><span class="pre">Mailbox</span></code></a> in612addition to the following:</p>613<dl class="py method">614<dt class="sig sig-object py" id="mailbox.Maildir.list_folders">615<span class="sig-name descname"><span class="pre">list_folders</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.list_folders" title="Link to this definition">¶</a></dt>616<dd><p>Return a list of the names of all folders.</p>617</dd></dl>618 619<dl class="py method">620<dt class="sig sig-object py" id="mailbox.Maildir.get_folder">621<span class="sig-name descname"><span class="pre">get_folder</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">folder</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.get_folder" title="Link to this definition">¶</a></dt>622<dd><p>Return a <code class="xref py py-class docutils literal notranslate"><span class="pre">Maildir</span></code> instance representing the folder whose name is623<em>folder</em>. A <a class="reference internal" href="#mailbox.NoSuchMailboxError" title="mailbox.NoSuchMailboxError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NoSuchMailboxError</span></code></a> exception is raised if the folder624does not exist.</p>625</dd></dl>626 627<dl class="py method">628<dt class="sig sig-object py" id="mailbox.Maildir.add_folder">629<span class="sig-name descname"><span class="pre">add_folder</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">folder</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.add_folder" title="Link to this definition">¶</a></dt>630<dd><p>Create a folder whose name is <em>folder</em> and return a <code class="xref py py-class docutils literal notranslate"><span class="pre">Maildir</span></code>631instance representing it.</p>632</dd></dl>633 634<dl class="py method">635<dt class="sig sig-object py" id="mailbox.Maildir.remove_folder">636<span class="sig-name descname"><span class="pre">remove_folder</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">folder</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.remove_folder" title="Link to this definition">¶</a></dt>637<dd><p>Delete the folder whose name is <em>folder</em>. If the folder contains any638messages, a <a class="reference internal" href="#mailbox.NotEmptyError" title="mailbox.NotEmptyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotEmptyError</span></code></a> exception will be raised and the folder639will not be deleted.</p>640</dd></dl>641 642<dl class="py method">643<dt class="sig sig-object py" id="mailbox.Maildir.clean">644<span class="sig-name descname"><span class="pre">clean</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.clean" title="Link to this definition">¶</a></dt>645<dd><p>Delete temporary files from the mailbox that have not been accessed in the646last 36 hours. The Maildir specification says that mail-reading programs647should do this occasionally.</p>648</dd></dl>649 650<dl class="py method">651<dt class="sig sig-object py" id="mailbox.Maildir.get_flags">652<span class="sig-name descname"><span class="pre">get_flags</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.get_flags" title="Link to this definition">¶</a></dt>653<dd><p>Return as a string the flags that are set on the message654corresponding to <em>key</em>.655This is the same as <code class="docutils literal notranslate"><span class="pre">get_message(key).get_flags()</span></code> but much656faster, because it does not open the message file.657Use this method when iterating over the keys to determine which658messages are interesting to get.</p>659<p>If you do have a <a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">MaildirMessage</span></code></a> object, use660its <a class="reference internal" href="#mailbox.MaildirMessage.get_flags" title="mailbox.MaildirMessage.get_flags"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_flags()</span></code></a> method instead, because661changes made by the message’s <a class="reference internal" href="#mailbox.MaildirMessage.set_flags" title="mailbox.MaildirMessage.set_flags"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_flags()</span></code></a>,662<a class="reference internal" href="#mailbox.MaildirMessage.add_flag" title="mailbox.MaildirMessage.add_flag"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_flag()</span></code></a> and <a class="reference internal" href="#mailbox.MaildirMessage.remove_flag" title="mailbox.MaildirMessage.remove_flag"><code class="xref py py-meth docutils literal notranslate"><span class="pre">remove_flag()</span></code></a>663methods are not reflected here until the mailbox’s664<a class="reference internal" href="#mailbox.Maildir.__setitem__" title="mailbox.Maildir.__setitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setitem__()</span></code></a> method is called.</p>665<div class="versionadded">666<p><span class="versionmodified added">Added in version 3.13.</span></p>667</div>668</dd></dl>669 670<dl class="py method">671<dt class="sig sig-object py" id="mailbox.Maildir.set_flags">672<span class="sig-name descname"><span class="pre">set_flags</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">flags</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.set_flags" title="Link to this definition">¶</a></dt>673<dd><p>On the message corresponding to <em>key</em>, set the flags specified674by <em>flags</em> and unset all others.675Calling <code class="docutils literal notranslate"><span class="pre">some_mailbox.set_flags(key,</span> <span class="pre">flags)</span></code> is similar to</p>676<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">one_message</span> <span class="o">=</span> <span class="n">some_mailbox</span><span class="o">.</span><span class="n">get_message</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>677<span class="n">one_message</span><span class="o">.</span><span class="n">set_flags</span><span class="p">(</span><span class="n">flags</span><span class="p">)</span>678<span class="n">some_mailbox</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">one_message</span>679</pre></div>680</div>681<p>but faster, because it does not open the message file.</p>682<p>If you do have a <a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">MaildirMessage</span></code></a> object, use683its <a class="reference internal" href="#mailbox.MaildirMessage.set_flags" title="mailbox.MaildirMessage.set_flags"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_flags()</span></code></a> method instead, because684changes made with this mailbox method will not be visible to the685message object’s method, <a class="reference internal" href="#mailbox.MaildirMessage.get_flags" title="mailbox.MaildirMessage.get_flags"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_flags()</span></code></a>.</p>686<div class="versionadded">687<p><span class="versionmodified added">Added in version 3.13.</span></p>688</div>689</dd></dl>690 691<dl class="py method">692<dt class="sig sig-object py" id="mailbox.Maildir.add_flag">693<span class="sig-name descname"><span class="pre">add_flag</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">flag</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.add_flag" title="Link to this definition">¶</a></dt>694<dd><p>On the message corresponding to <em>key</em>, set the flags specified695by <em>flag</em> without changing other flags. To add more than one696flag at a time, <em>flag</em> may be a string of more than one character.</p>697<p>Considerations for using this method versus the message object’s698<a class="reference internal" href="#mailbox.MaildirMessage.add_flag" title="mailbox.MaildirMessage.add_flag"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_flag()</span></code></a> method are similar to699those for <a class="reference internal" href="#mailbox.Maildir.set_flags" title="mailbox.Maildir.set_flags"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_flags()</span></code></a>; see the discussion there.</p>700<div class="versionadded">701<p><span class="versionmodified added">Added in version 3.13.</span></p>702</div>703</dd></dl>704 705<dl class="py method">706<dt class="sig sig-object py" id="mailbox.Maildir.remove_flag">707<span class="sig-name descname"><span class="pre">remove_flag</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">flag</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.remove_flag" title="Link to this definition">¶</a></dt>708<dd><p>On the message corresponding to <em>key</em>, unset the flags specified709by <em>flag</em> without changing other flags. To remove more than one710flag at a time, <em>flag</em> may be a string of more than one character.</p>711<p>Considerations for using this method versus the message object’s712<a class="reference internal" href="#mailbox.MaildirMessage.remove_flag" title="mailbox.MaildirMessage.remove_flag"><code class="xref py py-meth docutils literal notranslate"><span class="pre">remove_flag()</span></code></a> method are similar to713those for <a class="reference internal" href="#mailbox.Maildir.set_flags" title="mailbox.Maildir.set_flags"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_flags()</span></code></a>; see the discussion there.</p>714<div class="versionadded">715<p><span class="versionmodified added">Added in version 3.13.</span></p>716</div>717</dd></dl>718 719<dl class="py method">720<dt class="sig sig-object py" id="mailbox.Maildir.get_info">721<span class="sig-name descname"><span class="pre">get_info</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.get_info" title="Link to this definition">¶</a></dt>722<dd><p>Return a string containing the info for the message723corresponding to <em>key</em>.724This is the same as <code class="docutils literal notranslate"><span class="pre">get_message(key).get_info()</span></code> but much725faster, because it does not open the message file.726Use this method when iterating over the keys to determine which727messages are interesting to get.</p>728<p>If you do have a <a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">MaildirMessage</span></code></a> object, use729its <a class="reference internal" href="#mailbox.MaildirMessage.get_info" title="mailbox.MaildirMessage.get_info"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_info()</span></code></a> method instead, because730changes made by the message’s <a class="reference internal" href="#mailbox.MaildirMessage.set_info" title="mailbox.MaildirMessage.set_info"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_info()</span></code></a> method731are not reflected here until the mailbox’s <a class="reference internal" href="#mailbox.Maildir.__setitem__" title="mailbox.Maildir.__setitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setitem__()</span></code></a> method732is called.</p>733<div class="versionadded">734<p><span class="versionmodified added">Added in version 3.13.</span></p>735</div>736</dd></dl>737 738<dl class="py method">739<dt class="sig sig-object py" id="mailbox.Maildir.set_info">740<span class="sig-name descname"><span class="pre">set_info</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">info</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.set_info" title="Link to this definition">¶</a></dt>741<dd><p>Set the info of the message corresponding to <em>key</em> to <em>info</em>.742Calling <code class="docutils literal notranslate"><span class="pre">some_mailbox.set_info(key,</span> <span class="pre">flags)</span></code> is similar to</p>743<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">one_message</span> <span class="o">=</span> <span class="n">some_mailbox</span><span class="o">.</span><span class="n">get_message</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>744<span class="n">one_message</span><span class="o">.</span><span class="n">set_info</span><span class="p">(</span><span class="n">info</span><span class="p">)</span>745<span class="n">some_mailbox</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">one_message</span>746</pre></div>747</div>748<p>but faster, because it does not open the message file.</p>749<p>If you do have a <a class="reference internal" href="#mailbox.MaildirMessage" title="mailbox.MaildirMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">MaildirMessage</span></code></a> object, use750its <a class="reference internal" href="#mailbox.MaildirMessage.set_info" title="mailbox.MaildirMessage.set_info"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_info()</span></code></a> method instead, because751changes made with this mailbox method will not be visible to the752message object’s method, <a class="reference internal" href="#mailbox.MaildirMessage.get_info" title="mailbox.MaildirMessage.get_info"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_info()</span></code></a>.</p>753<div class="versionadded">754<p><span class="versionmodified added">Added in version 3.13.</span></p>755</div>756</dd></dl>757 758<p>Some <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code></a> methods implemented by <code class="xref py py-class docutils literal notranslate"><span class="pre">Maildir</span></code> deserve special759remarks:</p>760<dl class="py method">761<dt class="sig sig-object py" id="mailbox.Maildir.add">762<span class="sig-name descname"><span class="pre">add</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">message</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.add" title="Link to this definition">¶</a></dt>763<dt class="sig sig-object py" id="mailbox.Maildir.__setitem__">764<span class="sig-name descname"><span class="pre">__setitem__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">message</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.__setitem__" title="Link to this definition">¶</a></dt>765<dt class="sig sig-object py" id="mailbox.Maildir.update">766<span class="sig-name descname"><span class="pre">update</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">arg</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.update" title="Link to this definition">¶</a></dt>767<dd><div class="admonition warning">768<p class="admonition-title">Warning</p>769<p>These methods generate unique file names based upon the current process770ID. When using multiple threads, undetected name clashes may occur and771cause corruption of the mailbox unless threads are coordinated to avoid772using these methods to manipulate the same mailbox simultaneously.</p>773</div>774</dd></dl>775 776<dl class="py method">777<dt class="sig sig-object py" id="mailbox.Maildir.flush">778<span class="sig-name descname"><span class="pre">flush</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.flush" title="Link to this definition">¶</a></dt>779<dd><p>All changes to Maildir mailboxes are immediately applied, so this method780does nothing.</p>781</dd></dl>782 783<dl class="py method">784<dt class="sig sig-object py" id="mailbox.Maildir.lock">785<span class="sig-name descname"><span class="pre">lock</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.lock" title="Link to this definition">¶</a></dt>786<dt class="sig sig-object py" id="mailbox.Maildir.unlock">787<span class="sig-name descname"><span class="pre">unlock</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.unlock" title="Link to this definition">¶</a></dt>788<dd><p>Maildir mailboxes do not support (or require) locking, so these methods do789nothing.</p>790</dd></dl>791 792<dl class="py method">793<dt class="sig sig-object py" id="mailbox.Maildir.close">794<span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.close" title="Link to this definition">¶</a></dt>795<dd><p><code class="xref py py-class docutils literal notranslate"><span class="pre">Maildir</span></code> instances do not keep any open files and the underlying796mailboxes do not support locking, so this method does nothing.</p>797</dd></dl>798 799<dl class="py method">800<dt class="sig sig-object py" id="mailbox.Maildir.get_file">801<span class="sig-name descname"><span class="pre">get_file</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Maildir.get_file" title="Link to this definition">¶</a></dt>802<dd><p>Depending upon the host platform, it may not be possible to modify or803remove the underlying message while the returned file remains open.</p>804</dd></dl>805 806</dd></dl>807 808<div class="admonition seealso">809<p class="admonition-title">See also</p>810<dl class="simple">811<dt><a class="reference external" href="https://www.courier-mta.org/maildir.html">maildir man page from Courier</a></dt><dd><p>A specification of the format. Describes a common extension for812supporting folders.</p>813</dd>814<dt><a class="reference external" href="https://cr.yp.to/proto/maildir.html">Using maildir format</a></dt><dd><p>Notes on Maildir by its inventor. Includes an updated name-creation scheme and815details on “info” semantics.</p>816</dd>817</dl>818</div>819</section>820<section id="mbox-objects">821<span id="mailbox-mbox"></span><h3><code class="xref py py-class docutils literal notranslate"><span class="pre">mbox</span></code> objects<a class="headerlink" href="#mbox-objects" title="Link to this heading">¶</a></h3>822<dl class="py class">823<dt class="sig sig-object py" id="mailbox.mbox">824<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">mailbox.</span></span><span class="sig-name descname"><span class="pre">mbox</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">factory</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">create</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.mbox" title="Link to this definition">¶</a></dt>825<dd><p>A subclass of <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code></a> for mailboxes in mbox format. Parameter <em>factory</em>826is a callable object that accepts a file-like message representation (which827behaves as if opened in binary mode) and returns a custom representation. If828<em>factory</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">mboxMessage</span></code></a> is used as the default message829representation. If <em>create</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the mailbox is created if it does not830exist.</p>831<p>The mbox format is the classic format for storing mail on Unix systems. All832messages in an mbox mailbox are stored in a single file with the beginning of833each message indicated by a line whose first five characters are “From “.</p>834<p>Several variations of the mbox format exist to address perceived shortcomings in835the original. In the interest of compatibility, <code class="xref py py-class docutils literal notranslate"><span class="pre">mbox</span></code> implements the836original format, which is sometimes referred to as <em class="dfn">mboxo</em>. This means that837the <em class="mailheader">Content-Length</em> header, if present, is ignored and that any838occurrences of “From “ at the beginning of a line in a message body are839transformed to “&gt;From “ when storing the message, although occurrences of “&gt;From840“ are not transformed to “From “ when reading the message.</p>841<p>Some <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code></a> methods implemented by <code class="xref py py-class docutils literal notranslate"><span class="pre">mbox</span></code> deserve special842remarks:</p>843<dl class="py method">844<dt class="sig sig-object py" id="mailbox.mbox.get_bytes">845<span class="sig-name descname"><span class="pre">get_bytes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">from_</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.mbox.get_bytes" title="Link to this definition">¶</a></dt>846<dd><p>Note: This method has an extra parameter (<em>from_</em>) compared with other classes.847The first line of an mbox file entry is the Unix “From “ line.848If <em>from_</em> is False, the first line of the file is dropped.</p>849</dd></dl>850 851<dl class="py method">852<dt class="sig sig-object py" id="mailbox.mbox.get_file">853<span class="sig-name descname"><span class="pre">get_file</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">from_</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.mbox.get_file" title="Link to this definition">¶</a></dt>854<dd><p>Using the file after calling <a class="reference internal" href="#mailbox.Mailbox.flush" title="mailbox.Mailbox.flush"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flush()</span></code></a> or855<a class="reference internal" href="#mailbox.Mailbox.close" title="mailbox.Mailbox.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> on the <code class="xref py py-class docutils literal notranslate"><span class="pre">mbox</span></code> instance may yield856unpredictable results or raise an exception.</p>857<p>Note: This method has an extra parameter (<em>from_</em>) compared with other classes.858The first line of an mbox file entry is the Unix “From “ line.859If <em>from_</em> is False, the first line of the file is dropped.</p>860</dd></dl>861 862<dl class="py method">863<dt class="sig sig-object py" id="mailbox.mbox.get_string">864<span class="sig-name descname"><span class="pre">get_string</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">from_</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.mbox.get_string" title="Link to this definition">¶</a></dt>865<dd><p>Note: This method has an extra parameter (<em>from_</em>) compared with other classes.866The first line of an mbox file entry is the Unix “From “ line.867If <em>from_</em> is False, the first line of the file is dropped.</p>868</dd></dl>869 870<dl class="py method">871<dt class="sig sig-object py" id="mailbox.mbox.lock">872<span class="sig-name descname"><span class="pre">lock</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.mbox.lock" title="Link to this definition">¶</a></dt>873<dt class="sig sig-object py" id="mailbox.mbox.unlock">874<span class="sig-name descname"><span class="pre">unlock</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.mbox.unlock" title="Link to this definition">¶</a></dt>875<dd><p>Three locking mechanisms are used—dot locking and, if available, the876<code class="xref c c-func docutils literal notranslate"><span class="pre">flock()</span></code> and <code class="xref c c-func docutils literal notranslate"><span class="pre">lockf()</span></code> system calls.</p>877</dd></dl>878 879</dd></dl>880 881<div class="admonition seealso">882<p class="admonition-title">See also</p>883<dl class="simple">884<dt><a class="reference external" href="http://www.tin.org/bin/man.cgi?section=5&amp;topic=mbox">mbox man page from tin</a></dt><dd><p>A specification of the format, with details on locking.</p>885</dd>886<dt><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></dt><dd><p>An argument for using the original mbox format rather than a variation.</p>887</dd>888<dt><a class="reference external" href="https://www.loc.gov/preservation/digital/formats/fdd/fdd000383.shtml">“mbox” is a family of several mutually incompatible mailbox formats</a></dt><dd><p>A history of mbox variations.</p>889</dd>890</dl>891</div>892</section>893<section id="mh-objects">894<span id="mailbox-mh"></span><h3><code class="xref py py-class docutils literal notranslate"><span class="pre">MH</span></code> objects<a class="headerlink" href="#mh-objects" title="Link to this heading">¶</a></h3>895<dl class="py class">896<dt class="sig sig-object py" id="mailbox.MH">897<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">mailbox.</span></span><span class="sig-name descname"><span class="pre">MH</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">factory</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">create</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MH" title="Link to this definition">¶</a></dt>898<dd><p>A subclass of <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code></a> for mailboxes in MH format. Parameter <em>factory</em>899is a callable object that accepts a file-like message representation (which900behaves as if opened in binary mode) and returns a custom representation. If901<em>factory</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="#mailbox.MHMessage" title="mailbox.MHMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">MHMessage</span></code></a> is used as the default message902representation. If <em>create</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the mailbox is created if it does not903exist.</p>904<p>MH is a directory-based mailbox format invented for the MH Message Handling905System, a mail user agent. Each message in an MH mailbox resides in its own906file. An MH mailbox may contain other MH mailboxes (called <em class="dfn">folders</em>) in907addition to messages. Folders may be nested indefinitely. MH mailboxes also908support <em class="dfn">sequences</em>, which are named lists used to logically group909messages without moving them to sub-folders. Sequences are defined in a file910called <code class="file docutils literal notranslate"><span class="pre">.mh_sequences</span></code> in each folder.</p>911<p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">MH</span></code> class manipulates MH mailboxes, but it does not attempt to912emulate all of <strong class="program">mh</strong>’s behaviors. In particular, it does not modify913and is not affected by the <code class="file docutils literal notranslate"><span class="pre">context</span></code> or <code class="file docutils literal notranslate"><span class="pre">.mh_profile</span></code> files that914are used by <strong class="program">mh</strong> to store its state and configuration.</p>915<p><code class="xref py py-class docutils literal notranslate"><span class="pre">MH</span></code> 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 notranslate"><span class="pre">Mailbox</span></code></a> in addition916to the following:</p>917<div class="versionchanged">918<p><span class="versionmodified changed">Changed in version 3.13: </span>Supported folders that don’t contain a <code class="file docutils literal notranslate"><span class="pre">.mh_sequences</span></code> file.</p>919</div>920<dl class="py method">921<dt class="sig sig-object py" id="mailbox.MH.list_folders">922<span class="sig-name descname"><span class="pre">list_folders</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MH.list_folders" title="Link to this definition">¶</a></dt>923<dd><p>Return a list of the names of all folders.</p>924</dd></dl>925 926<dl class="py method">927<dt class="sig sig-object py" id="mailbox.MH.get_folder">928<span class="sig-name descname"><span class="pre">get_folder</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">folder</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MH.get_folder" title="Link to this definition">¶</a></dt>929<dd><p>Return an <code class="xref py py-class docutils literal notranslate"><span class="pre">MH</span></code> instance representing the folder whose name is930<em>folder</em>. A <a class="reference internal" href="#mailbox.NoSuchMailboxError" title="mailbox.NoSuchMailboxError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NoSuchMailboxError</span></code></a> exception is raised if the folder931does not exist.</p>932</dd></dl>933 934<dl class="py method">935<dt class="sig sig-object py" id="mailbox.MH.add_folder">936<span class="sig-name descname"><span class="pre">add_folder</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">folder</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MH.add_folder" title="Link to this definition">¶</a></dt>937<dd><p>Create a folder whose name is <em>folder</em> and return an <code class="xref py py-class docutils literal notranslate"><span class="pre">MH</span></code> instance938representing it.</p>939</dd></dl>940 941<dl class="py method">942<dt class="sig sig-object py" id="mailbox.MH.remove_folder">943<span class="sig-name descname"><span class="pre">remove_folder</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">folder</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MH.remove_folder" title="Link to this definition">¶</a></dt>944<dd><p>Delete the folder whose name is <em>folder</em>. If the folder contains any945messages, a <a class="reference internal" href="#mailbox.NotEmptyError" title="mailbox.NotEmptyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotEmptyError</span></code></a> exception will be raised and the folder946will not be deleted.</p>947</dd></dl>948 949<dl class="py method">950<dt class="sig sig-object py" id="mailbox.MH.get_sequences">951<span class="sig-name descname"><span class="pre">get_sequences</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MH.get_sequences" title="Link to this definition">¶</a></dt>952<dd><p>Return a dictionary of sequence names mapped to key lists. If there are no953sequences, the empty dictionary is returned.</p>954</dd></dl>955 956<dl class="py method">957<dt class="sig sig-object py" id="mailbox.MH.set_sequences">958<span class="sig-name descname"><span class="pre">set_sequences</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sequences</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MH.set_sequences" title="Link to this definition">¶</a></dt>959<dd><p>Re-define the sequences that exist in the mailbox based upon <em>sequences</em>,960a dictionary of names mapped to key lists, like returned by961<a class="reference internal" href="#mailbox.MH.get_sequences" title="mailbox.MH.get_sequences"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_sequences()</span></code></a>.</p>962</dd></dl>963 964<dl class="py method">965<dt class="sig sig-object py" id="mailbox.MH.pack">966<span class="sig-name descname"><span class="pre">pack</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MH.pack" title="Link to this definition">¶</a></dt>967<dd><p>Rename messages in the mailbox as necessary to eliminate gaps in968numbering.  Entries in the sequences list are updated correspondingly.</p>969<div class="admonition note">970<p class="admonition-title">Note</p>971<p>Already-issued keys are invalidated by this operation and should not be972subsequently used.</p>973</div>974</dd></dl>975 976<p>Some <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code></a> methods implemented by <code class="xref py py-class docutils literal notranslate"><span class="pre">MH</span></code> deserve special977remarks:</p>978<dl class="py method">979<dt class="sig sig-object py" id="mailbox.MH.remove">980<span class="sig-name descname"><span class="pre">remove</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MH.remove" title="Link to this definition">¶</a></dt>981<dt class="sig sig-object py" id="mailbox.MH.__delitem__">982<span class="sig-name descname"><span class="pre">__delitem__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MH.__delitem__" title="Link to this definition">¶</a></dt>983<dt class="sig sig-object py" id="mailbox.MH.discard">984<span class="sig-name descname"><span class="pre">discard</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MH.discard" title="Link to this definition">¶</a></dt>985<dd><p>These methods immediately delete the message. The MH convention of marking986a message for deletion by prepending a comma to its name is not used.</p>987</dd></dl>988 989<dl class="py method">990<dt class="sig sig-object py" id="mailbox.MH.lock">991<span class="sig-name descname"><span class="pre">lock</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MH.lock" title="Link to this definition">¶</a></dt>992<dt class="sig sig-object py" id="mailbox.MH.unlock">993<span class="sig-name descname"><span class="pre">unlock</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MH.unlock" title="Link to this definition">¶</a></dt>994<dd><p>Three locking mechanisms are used—dot locking and, if available, the995<code class="xref c c-func docutils literal notranslate"><span class="pre">flock()</span></code> and <code class="xref c c-func docutils literal notranslate"><span class="pre">lockf()</span></code> system calls. For MH mailboxes, locking996the mailbox means locking the <code class="file docutils literal notranslate"><span class="pre">.mh_sequences</span></code> file and, only for the997duration of any operations that affect them, locking individual message998files.</p>999</dd></dl>1000 1001<dl class="py method">1002<dt class="sig sig-object py" id="mailbox.MH.get_file">1003<span class="sig-name descname"><span class="pre">get_file</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MH.get_file" title="Link to this definition">¶</a></dt>1004<dd><p>Depending upon the host platform, it may not be possible to remove the1005underlying message while the returned file remains open.</p>1006</dd></dl>1007 1008<dl class="py method">1009<dt class="sig sig-object py" id="mailbox.MH.flush">1010<span class="sig-name descname"><span class="pre">flush</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MH.flush" title="Link to this definition">¶</a></dt>1011<dd><p>All changes to MH mailboxes are immediately applied, so this method does1012nothing.</p>1013</dd></dl>1014 1015<dl class="py method">1016<dt class="sig sig-object py" id="mailbox.MH.close">1017<span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MH.close" title="Link to this definition">¶</a></dt>1018<dd><p><code class="xref py py-class docutils literal notranslate"><span class="pre">MH</span></code> instances do not keep any open files, so this method is1019equivalent to <a class="reference internal" href="#mailbox.MH.unlock" title="mailbox.MH.unlock"><code class="xref py py-meth docutils literal notranslate"><span class="pre">unlock()</span></code></a>.</p>1020</dd></dl>1021 1022</dd></dl>1023 1024<div class="admonition seealso">1025<p class="admonition-title">See also</p>1026<dl class="simple">1027<dt><a class="reference external" href="https://www.nongnu.org/nmh/">nmh - Message Handling System</a></dt><dd><p>Home page of <strong class="program">nmh</strong>, an updated version of the original <strong class="program">mh</strong>.</p>1028</dd>1029<dt><a class="reference external" href="https://rand-mh.sourceforge.io/book/">MH &amp; nmh: Email for Users &amp; Programmers</a></dt><dd><p>A GPL-licensed book on <strong class="program">mh</strong> and <strong class="program">nmh</strong>, with some information1030on the mailbox format.</p>1031</dd>1032</dl>1033</div>1034</section>1035<section id="babyl-objects">1036<span id="mailbox-babyl"></span><h3><code class="xref py py-class docutils literal notranslate"><span class="pre">Babyl</span></code> objects<a class="headerlink" href="#babyl-objects" title="Link to this heading">¶</a></h3>1037<dl class="py class">1038<dt class="sig sig-object py" id="mailbox.Babyl">1039<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">mailbox.</span></span><span class="sig-name descname"><span class="pre">Babyl</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">factory</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">create</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Babyl" title="Link to this definition">¶</a></dt>1040<dd><p>A subclass of <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code></a> for mailboxes in Babyl format. Parameter1041<em>factory</em> is a callable object that accepts a file-like message representation1042(which behaves as if opened in binary mode) and returns a custom representation.1043If <em>factory</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="#mailbox.BabylMessage" title="mailbox.BabylMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">BabylMessage</span></code></a> is used as the default message1044representation. If <em>create</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the mailbox is created if it does not1045exist.</p>1046<p>Babyl is a single-file mailbox format used by the Rmail mail user agent1047included with Emacs. The beginning of a message is indicated by a line1048containing the two characters Control-Underscore (<code class="docutils literal notranslate"><span class="pre">'\037'</span></code>) and Control-L1049(<code class="docutils literal notranslate"><span class="pre">'\014'</span></code>). The end of a message is indicated by the start of the next1050message or, in the case of the last message, a line containing a1051Control-Underscore (<code class="docutils literal notranslate"><span class="pre">'\037'</span></code>) character.</p>1052<p>Messages in a Babyl mailbox have two sets of headers, original headers and1053so-called visible headers. Visible headers are typically a subset of the1054original headers that have been reformatted or abridged to be more1055attractive. Each message in a Babyl mailbox also has an accompanying list of1056<em class="dfn">labels</em>, or short strings that record extra information about the1057message, and a list of all user-defined labels found in the mailbox is kept1058in the Babyl options section.</p>1059<p><code class="xref py py-class docutils literal notranslate"><span class="pre">Babyl</span></code> 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 notranslate"><span class="pre">Mailbox</span></code></a> in1060addition to the following:</p>1061<dl class="py method">1062<dt class="sig sig-object py" id="mailbox.Babyl.get_labels">1063<span class="sig-name descname"><span class="pre">get_labels</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Babyl.get_labels" title="Link to this definition">¶</a></dt>1064<dd><p>Return a list of the names of all user-defined labels used in the mailbox.</p>1065<div class="admonition note">1066<p class="admonition-title">Note</p>1067<p>The actual messages are inspected to determine which labels exist in1068the mailbox rather than consulting the list of labels in the Babyl1069options section, but the Babyl section is updated whenever the mailbox1070is modified.</p>1071</div>1072</dd></dl>1073 1074<p>Some <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code></a> methods implemented by <code class="xref py py-class docutils literal notranslate"><span class="pre">Babyl</span></code> deserve special1075remarks:</p>1076<dl class="py method">1077<dt class="sig sig-object py" id="mailbox.Babyl.get_file">1078<span class="sig-name descname"><span class="pre">get_file</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Babyl.get_file" title="Link to this definition">¶</a></dt>1079<dd><p>In Babyl mailboxes, the headers of a message are not stored contiguously1080with the body of the message. To generate a file-like representation, the1081headers 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 notranslate"><span class="pre">io.BytesIO</span></code></a> instance,1082which has an API identical to that of a1083file. As a result, the file-like object is truly independent of the1084underlying mailbox but does not save memory compared to a string1085representation.</p>1086</dd></dl>1087 1088<dl class="py method">1089<dt class="sig sig-object py" id="mailbox.Babyl.lock">1090<span class="sig-name descname"><span class="pre">lock</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Babyl.lock" title="Link to this definition">¶</a></dt>1091<dt class="sig sig-object py" id="mailbox.Babyl.unlock">1092<span class="sig-name descname"><span class="pre">unlock</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Babyl.unlock" title="Link to this definition">¶</a></dt>1093<dd><p>Three locking mechanisms are used—dot locking and, if available, the1094<code class="xref c c-func docutils literal notranslate"><span class="pre">flock()</span></code> and <code class="xref c c-func docutils literal notranslate"><span class="pre">lockf()</span></code> system calls.</p>1095</dd></dl>1096 1097</dd></dl>1098 1099<div class="admonition seealso">1100<p class="admonition-title">See also</p>1101<dl class="simple">1102<dt><a class="reference external" href="https://quimby.gnus.org/notes/BABYL">Format of Version 5 Babyl Files</a></dt><dd><p>A specification of the Babyl format.</p>1103</dd>1104<dt><a class="reference external" href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Rmail.html">Reading Mail with Rmail</a></dt><dd><p>The Rmail manual, with some information on Babyl semantics.</p>1105</dd>1106</dl>1107</div>1108</section>1109<section id="mmdf-objects">1110<span id="mailbox-mmdf"></span><h3><code class="xref py py-class docutils literal notranslate"><span class="pre">MMDF</span></code> objects<a class="headerlink" href="#mmdf-objects" title="Link to this heading">¶</a></h3>1111<dl class="py class">1112<dt class="sig sig-object py" id="mailbox.MMDF">1113<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">mailbox.</span></span><span class="sig-name descname"><span class="pre">MMDF</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">factory</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">create</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MMDF" title="Link to this definition">¶</a></dt>1114<dd><p>A subclass of <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code></a> for mailboxes in MMDF format. Parameter <em>factory</em>1115is a callable object that accepts a file-like message representation (which1116behaves as if opened in binary mode) and returns a custom representation. If1117<em>factory</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="#mailbox.MMDFMessage" title="mailbox.MMDFMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">MMDFMessage</span></code></a> is used as the default message1118representation. If <em>create</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the mailbox is created if it does not1119exist.</p>1120<p>MMDF is a single-file mailbox format invented for the Multichannel Memorandum1121Distribution Facility, a mail transfer agent. Each message is in the same1122form as an mbox message but is bracketed before and after by lines containing1123four Control-A (<code class="docutils literal notranslate"><span class="pre">'\001'</span></code>) characters. As with the mbox format, the1124beginning of each message is indicated by a line whose first five characters1125are “From “, but additional occurrences of “From “ are not transformed to1126“&gt;From “ when storing messages because the extra message separator lines1127prevent mistaking such occurrences for the starts of subsequent messages.</p>1128<p>Some <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code></a> methods implemented by <code class="xref py py-class docutils literal notranslate"><span class="pre">MMDF</span></code> deserve special1129remarks:</p>1130<dl class="py method">1131<dt class="sig sig-object py" id="mailbox.MMDF.get_bytes">1132<span class="sig-name descname"><span class="pre">get_bytes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">from_</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MMDF.get_bytes" title="Link to this definition">¶</a></dt>1133<dd><p>Note: This method has an extra parameter (<em>from_</em>) compared with other classes.1134The first line of an mbox file entry is the Unix “From “ line.1135If <em>from_</em> is False, the first line of the file is dropped.</p>1136</dd></dl>1137 1138<dl class="py method">1139<dt class="sig sig-object py" id="mailbox.MMDF.get_file">1140<span class="sig-name descname"><span class="pre">get_file</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">from_</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MMDF.get_file" title="Link to this definition">¶</a></dt>1141<dd><p>Using the file after calling <a class="reference internal" href="#mailbox.Mailbox.flush" title="mailbox.Mailbox.flush"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flush()</span></code></a> or1142<a class="reference internal" href="#mailbox.Mailbox.close" title="mailbox.Mailbox.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> on the <code class="xref py py-class docutils literal notranslate"><span class="pre">MMDF</span></code> instance may yield1143unpredictable results or raise an exception.</p>1144<p>Note: This method has an extra parameter (<em>from_</em>) compared with other classes.1145The first line of an mbox file entry is the Unix “From “ line.1146If <em>from_</em> is False, the first line of the file is dropped.</p>1147</dd></dl>1148 1149<dl class="py method">1150<dt class="sig sig-object py" id="mailbox.MMDF.lock">1151<span class="sig-name descname"><span class="pre">lock</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MMDF.lock" title="Link to this definition">¶</a></dt>1152<dt class="sig sig-object py" id="mailbox.MMDF.unlock">1153<span class="sig-name descname"><span class="pre">unlock</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.MMDF.unlock" title="Link to this definition">¶</a></dt>1154<dd><p>Three locking mechanisms are used—dot locking and, if available, the1155<code class="xref c c-func docutils literal notranslate"><span class="pre">flock()</span></code> and <code class="xref c c-func docutils literal notranslate"><span class="pre">lockf()</span></code> system calls.</p>1156</dd></dl>1157 1158</dd></dl>1159 1160<div class="admonition seealso">1161<p class="admonition-title">See also</p>1162<dl class="simple">1163<dt><a class="reference external" href="http://www.tin.org/bin/man.cgi?section=5&amp;topic=mmdf">mmdf man page from tin</a></dt><dd><p>A specification of MMDF format from the documentation of tin, a newsreader.</p>1164</dd>1165<dt><a class="reference external" href="https://en.wikipedia.org/wiki/MMDF">MMDF</a></dt><dd><p>A Wikipedia article describing the Multichannel Memorandum Distribution1166Facility.</p>1167</dd>1168</dl>1169</div>1170</section>1171</section>1172<section id="message-objects">1173<span id="mailbox-message-objects"></span><h2><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code> objects<a class="headerlink" href="#message-objects" title="Link to this heading">¶</a></h2>1174<dl class="py class">1175<dt class="sig sig-object py" id="mailbox.Message">1176<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">mailbox.</span></span><span class="sig-name descname"><span class="pre">Message</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">message</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#mailbox.Message" title="Link to this definition">¶</a></dt>1177<dd><p>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 notranslate"><span class="pre">email.message</span></code></a> module’s1178<a class="reference internal" href="email.compat32-message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a>. Subclasses of <code class="xref py py-class docutils literal notranslate"><span class="pre">mailbox.Message</span></code> add1179mailbox-format-specific state and behavior.</p>1180<p>If <em>message</em> is omitted, the new instance is created in a default, empty state.1181If <em>message</em> is an <a class="reference internal" href="email.compat32-message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">email.message.Message</span></code></a> instance, its contents are1182copied; furthermore, any format-specific information is converted insofar as1183possible if <em>message</em> is a <code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code> instance. If <em>message</em> is a string,1184a byte string,1185or a file, it should contain an <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5322.html"><strong>RFC 5322</strong></a>-compliant message, which is read1186and parsed.  Files should be open in binary mode, but text mode files1187are accepted for backward compatibility.</p>1188<p>The format-specific state and behaviors offered by subclasses vary, but in1189general it is only the properties that are not specific to a particular1190mailbox that are supported (although presumably the properties are specific1191to a particular mailbox format). For example, file offsets for single-file1192mailbox formats and file names for directory-based mailbox formats are not1193retained, because they are only applicable to the original mailbox. But state1194such as whether a message has been read by the user or marked as important is1195retained, because it applies to the message itself.</p>1196<p>There is no requirement that <code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code> instances be used to represent1197messages retrieved using <a class="reference internal" href="#mailbox.Mailbox" title="mailbox.Mailbox"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code></a> instances. In some situations, the1198time and memory required to generate <code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code> representations might1199not be acceptable. For such situations, <code class="xref py py-class docutils literal notranslate"><span class="pre">Mailbox</span></code> instances also1200offer string and file-like representations, and a custom message factory may

Showing the first 1,200 of 2383 lines. Download the file for the rest.