Team Ai
Apppublic

parthtamu/rag-code-assistant

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
email.parser.html689 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="email.parser: Parsing email messages" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/email.parser.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/email/parser.py Message object structures can be created in one of two ways: they can be created from whole cloth by creating an EmailMessage object, adding headers using the dicti..." />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_email.parser_bac284ac.png" />15<meta property="og:image:alt" content="Source code: Lib/email/parser.py Message object structures can be created in one of two ways: they can be created from whole cloth by creating an EmailMessage object, adding headers using the dicti..." />16<meta name="description" content="Source code: Lib/email/parser.py Message object structures can be created in one of two ways: they can be created from whole cloth by creating an EmailMessage object, adding headers using the dicti..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20    <title>email.parser: Parsing email messages &#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="email.generator: Generating MIME documents" href="email.generator.html" />43    <link rel="prev" title="email.message: Representing an email message" href="email.message.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/email.parser.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">email.parser</span></code>: Parsing email messages</a><ul>108<li><a class="reference internal" href="#feedparser-api">FeedParser API</a></li>109<li><a class="reference internal" href="#parser-api">Parser API</a></li>110<li><a class="reference internal" href="#additional-notes">Additional notes</a></li>111</ul>112</li>113</ul>114 115  </div>116  <div>117    <h4>Previous topic</h4>118    <p class="topless"><a href="email.message.html"119                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.message</span></code>: Representing an email message</a></p>120  </div>121  <div>122    <h4>Next topic</h4>123    <p class="topless"><a href="email.generator.html"124                          title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.generator</span></code>: Generating MIME documents</a></p>125  </div>126  <script>127    document.addEventListener('DOMContentLoaded', () => {128        const title = document.querySelector('meta[property="og:title"]').content;129        const elements = document.querySelectorAll('.improvepage');130        const pageurl = window.location.href.split('?')[0];131        elements.forEach(element => {132            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));133            url.searchParams.set('pagetitle', title);134            url.searchParams.set('pageurl', pageurl);135            url.searchParams.set('pagesource', "library/email.parser.rst");136            element.href = url.toString();137        });138    });139  </script>140  <div role="note" aria-label="source link">141    <h3>This page</h3>142    <ul class="this-page-menu">143      <li><a href="../bugs.html">Report a bug</a></li>144      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>145      <li>146        <a href="https://github.com/python/cpython/blob/main/Doc/library/email.parser.rst?plain=1"147            rel="nofollow">Show source148        </a>149      </li>150      151    </ul>152  </div>153        </nav>154    </div>155</div>156 157  158    <div class="related" role="navigation" aria-label="Related">159      <h3>Navigation</h3>160      <ul>161        <li class="right" style="margin-right: 10px">162          <a href="../genindex.html" title="General Index"163             accesskey="I">index</a></li>164        <li class="right" >165          <a href="../py-modindex.html" title="Python Module Index"166             >modules</a> |</li>167        <li class="right" >168          <a href="email.generator.html" title="email.generator: Generating MIME documents"169             accesskey="N">next</a> |</li>170        <li class="right" >171          <a href="email.message.html" title="email.message: Representing an email message"172             accesskey="P">previous</a> |</li>173 174          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>175          <li><a href="https://www.python.org/">Python</a> &#187;</li>176          <li class="switchers">177            <div class="language_switcher_placeholder"></div>178            <div class="version_switcher_placeholder"></div>179          </li>180          <li>181              182          </li>183    <li id="cpython-language-and-version">184      <a href="../index.html">3.15.0a6 Documentation</a> &#187;185    </li>186 187          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>188          <li class="nav-item nav-item-2"><a href="netdata.html" >Internet Data Handling</a> &#187;</li>189          <li class="nav-item nav-item-3"><a href="email.html" accesskey="U"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email</span></code> — An email and MIME handling package</a> &#187;</li>190        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.parser</span></code>: Parsing email messages</a></li>191                <li class="right">192                    193 194    <div class="inline-search" role="search">195        <form class="inline-search" action="../search.html" method="get">196          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">197          <input type="submit" value="Go">198        </form>199    </div>200                     |201                </li>202            <li class="right">203<label class="theme-selector-label">204    Theme205    <select class="theme-selector" oninput="activateTheme(this.value)">206        <option value="auto" selected>Auto</option>207        <option value="light">Light</option>208        <option value="dark">Dark</option>209    </select>210</label> |</li>211            212      </ul>213    </div>    214 215    <div class="document">216      <div class="documentwrapper">217        <div class="bodywrapper">218          <div class="body" role="main">219            220  <section id="module-email.parser">221<span id="email-parser-parsing-email-messages"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.parser</span></code>: Parsing email messages<a class="headerlink" href="#module-email.parser" title="Link to this heading">¶</a></h1>222<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/email/parser.py">Lib/email/parser.py</a></p>223<hr class="docutils" />224<p>Message object structures can be created in one of two ways: they can be225created from whole cloth by creating an <a class="reference internal" href="email.message.html#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a>226object, adding headers using the dictionary interface, and adding payload(s)227using <a class="reference internal" href="email.message.html#email.message.EmailMessage.set_content" title="email.message.EmailMessage.set_content"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_content()</span></code></a> and related methods, or228they can be created by parsing a serialized representation of the email229message.</p>230<p>The <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> package provides a standard parser that understands most email231document structures, including MIME documents.  You can pass the parser a232bytes, string or file object, and the parser will return to you the root233<a class="reference internal" href="email.message.html#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> instance of the object structure.  For234simple, non-MIME messages the payload of this root object will likely be a235string containing the text of the message.  For MIME messages, the root object236will return <code class="docutils literal notranslate"><span class="pre">True</span></code> from its <a class="reference internal" href="email.message.html#email.message.EmailMessage.is_multipart" title="email.message.EmailMessage.is_multipart"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code></a>237method, and the subparts can be accessed via the payload manipulation methods,238such as <a class="reference internal" href="email.message.html#email.message.EmailMessage.get_body" title="email.message.EmailMessage.get_body"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_body()</span></code></a>,239<a class="reference internal" href="email.message.html#email.message.EmailMessage.iter_parts" title="email.message.EmailMessage.iter_parts"><code class="xref py py-meth docutils literal notranslate"><span class="pre">iter_parts()</span></code></a>, and240<a class="reference internal" href="email.message.html#email.message.EmailMessage.walk" title="email.message.EmailMessage.walk"><code class="xref py py-meth docutils literal notranslate"><span class="pre">walk()</span></code></a>.</p>241<p>There are actually two parser interfaces available for use, the <a class="reference internal" href="#email.parser.Parser" title="email.parser.Parser"><code class="xref py py-class docutils literal notranslate"><span class="pre">Parser</span></code></a>242API and the incremental <a class="reference internal" href="#email.parser.FeedParser" title="email.parser.FeedParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">FeedParser</span></code></a> API.  The <code class="xref py py-class docutils literal notranslate"><span class="pre">Parser</span></code> API is243most useful if you have the entire text of the message in memory, or if the244entire message lives in a file on the file system.  <code class="xref py py-class docutils literal notranslate"><span class="pre">FeedParser</span></code> is more245appropriate when you are reading the message from a stream which might block246waiting for more input (such as reading an email message from a socket).  The247<code class="xref py py-class docutils literal notranslate"><span class="pre">FeedParser</span></code> can consume and parse the message incrementally, and only248returns the root object when you close the parser.</p>249<p>Note that the parser can be extended in limited ways, and of course you can250implement your own parser completely from scratch.  All of the logic that251connects the <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> package’s bundled parser and the252<a class="reference internal" href="email.message.html#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> class is embodied in the <a class="reference internal" href="email.policy.html#email.policy.Policy" title="email.policy.Policy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Policy</span></code></a>253class, so a custom parser can create message object trees any way it finds254necessary by implementing custom versions of the appropriate <code class="xref py py-class docutils literal notranslate"><span class="pre">Policy</span></code>255methods.</p>256<section id="feedparser-api">257<h2>FeedParser API<a class="headerlink" href="#feedparser-api" title="Link to this heading">¶</a></h2>258<p>The <a class="reference internal" href="#email.parser.BytesFeedParser" title="email.parser.BytesFeedParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesFeedParser</span></code></a>, imported from the <code class="xref py py-mod docutils literal notranslate"><span class="pre">email.feedparser</span></code> module,259provides an API that is conducive to incremental parsing of email messages,260such as would be necessary when reading the text of an email message from a261source that can block (such as a socket).  The <code class="xref py py-class docutils literal notranslate"><span class="pre">BytesFeedParser</span></code> can of262course be used to parse an email message fully contained in a <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like263object</span></a>, string, or file, but the <a class="reference internal" href="#email.parser.BytesParser" title="email.parser.BytesParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesParser</span></code></a> API may be more264convenient for such use cases.  The semantics and results of the two parser265APIs are identical.</p>266<p>The <a class="reference internal" href="#email.parser.BytesFeedParser" title="email.parser.BytesFeedParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesFeedParser</span></code></a>’s API is simple; you create an instance, feed it a267bunch of bytes until there’s no more to feed it, then close the parser to268retrieve the root message object.  The <code class="xref py py-class docutils literal notranslate"><span class="pre">BytesFeedParser</span></code> is extremely269accurate when parsing standards-compliant messages, and it does a very good job270of parsing non-compliant messages, providing information about how a message271was deemed broken.  It will populate a message object’s272<a class="reference internal" href="email.message.html#email.message.EmailMessage.defects" title="email.message.EmailMessage.defects"><code class="xref py py-attr docutils literal notranslate"><span class="pre">defects</span></code></a> attribute with a list of any273problems it found in a message.  See the <a class="reference internal" href="email.errors.html#module-email.errors" title="email.errors: The exception classes used by the email package."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.errors</span></code></a> module for the274list of defects that it can find.</p>275<p>Here is the API for the <a class="reference internal" href="#email.parser.BytesFeedParser" title="email.parser.BytesFeedParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesFeedParser</span></code></a>:</p>276<dl class="py class">277<dt class="sig sig-object py" id="email.parser.BytesFeedParser">278<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">email.parser.</span></span><span class="sig-name descname"><span class="pre">BytesFeedParser</span></span><span class="sig-paren">(</span><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="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">policy.compat32</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.parser.BytesFeedParser" title="Link to this definition">¶</a></dt>279<dd><p>Create a <code class="xref py py-class docutils literal notranslate"><span class="pre">BytesFeedParser</span></code> instance.  Optional <em>_factory</em> is a280no-argument callable; if not specified use the281<a class="reference internal" href="email.policy.html#email.policy.Policy.message_factory" title="email.policy.Policy.message_factory"><code class="xref py py-attr docutils literal notranslate"><span class="pre">message_factory</span></code></a> from the <em>policy</em>.  Call282<em>_factory</em> whenever a new message object is needed.</p>283<p>If <em>policy</em> is specified use the rules it specifies to update the284representation of the message.  If <em>policy</em> is not set, use the285<a class="reference internal" href="email.policy.html#email.policy.Compat32" title="email.policy.Compat32"><code class="xref py py-class docutils literal notranslate"><span class="pre">compat32</span></code></a> policy, which maintains backward286compatibility with the Python 3.2 version of the email package and provides287<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> as the default factory.  All other policies288provide <a class="reference internal" href="email.message.html#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> as the default <em>_factory</em>. For289more information on what else <em>policy</em> controls, see the290<a class="reference internal" href="email.policy.html#module-email.policy" title="email.policy: Controlling the parsing and generating of messages"><code class="xref py py-mod docutils literal notranslate"><span class="pre">policy</span></code></a> documentation.</p>291<p>Note: <strong>The policy keyword should always be specified</strong>; The default will292change to <a class="reference internal" href="email.policy.html#email.policy.default" title="email.policy.default"><code class="xref py py-data docutils literal notranslate"><span class="pre">email.policy.default</span></code></a> in a future version of Python.</p>293<div class="versionadded">294<p><span class="versionmodified added">Added in version 3.2.</span></p>295</div>296<div class="versionchanged">297<p><span class="versionmodified changed">Changed in version 3.3: </span>Added the <em>policy</em> keyword.</p>298</div>299<div class="versionchanged">300<p><span class="versionmodified changed">Changed in version 3.6: </span><em>_factory</em> defaults to the policy <code class="docutils literal notranslate"><span class="pre">message_factory</span></code>.</p>301</div>302<dl class="py method">303<dt class="sig sig-object py" id="email.parser.BytesFeedParser.feed">304<span class="sig-name descname"><span class="pre">feed</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.parser.BytesFeedParser.feed" title="Link to this definition">¶</a></dt>305<dd><p>Feed the parser some more data.  <em>data</em> should be a <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like306object</span></a> containing one or more lines.  The lines can be partial and the307parser will stitch such partial lines together properly.  The lines can308have any of the three common line endings: carriage return, newline, or309carriage return and newline (they can even be mixed).</p>310</dd></dl>311 312<dl class="py method">313<dt class="sig sig-object py" id="email.parser.BytesFeedParser.close">314<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="#email.parser.BytesFeedParser.close" title="Link to this definition">¶</a></dt>315<dd><p>Complete the parsing of all previously fed data and return the root316message object.  It is undefined what happens if <a class="reference internal" href="#email.parser.BytesFeedParser.feed" title="email.parser.BytesFeedParser.feed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">feed()</span></code></a> is called317after this method has been called.</p>318</dd></dl>319 320</dd></dl>321 322<dl class="py class">323<dt class="sig sig-object py" id="email.parser.FeedParser">324<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">email.parser.</span></span><span class="sig-name descname"><span class="pre">FeedParser</span></span><span class="sig-paren">(</span><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="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">policy.compat32</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.parser.FeedParser" title="Link to this definition">¶</a></dt>325<dd><p>Works like <a class="reference internal" href="#email.parser.BytesFeedParser" title="email.parser.BytesFeedParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesFeedParser</span></code></a> except that the input to the326<a class="reference internal" href="#email.parser.BytesFeedParser.feed" title="email.parser.BytesFeedParser.feed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">feed()</span></code></a> method must be a string.  This is of limited327utility, since the only way for such a message to be valid is for it to328contain only ASCII text or, if <a class="reference internal" href="email.policy.html#email.policy.EmailPolicy.utf8" title="email.policy.EmailPolicy.utf8"><code class="xref py py-attr docutils literal notranslate"><span class="pre">utf8</span></code></a> is329<code class="docutils literal notranslate"><span class="pre">True</span></code>, no binary attachments.</p>330<div class="versionchanged">331<p><span class="versionmodified changed">Changed in version 3.3: </span>Added the <em>policy</em> keyword.</p>332</div>333</dd></dl>334 335</section>336<section id="parser-api">337<h2>Parser API<a class="headerlink" href="#parser-api" title="Link to this heading">¶</a></h2>338<p>The <a class="reference internal" href="#email.parser.BytesParser" title="email.parser.BytesParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesParser</span></code></a> class, imported from the <code class="xref py py-mod docutils literal notranslate"><span class="pre">email.parser</span></code> module,339provides an API that can be used to parse a message when the complete contents340of the message are available in a <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a> or file.  The341<code class="xref py py-mod docutils literal notranslate"><span class="pre">email.parser</span></code> module also provides <a class="reference internal" href="#email.parser.Parser" title="email.parser.Parser"><code class="xref py py-class docutils literal notranslate"><span class="pre">Parser</span></code></a> for parsing strings,342and header-only parsers, <a class="reference internal" href="#email.parser.BytesHeaderParser" title="email.parser.BytesHeaderParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesHeaderParser</span></code></a> and343<a class="reference internal" href="#email.parser.HeaderParser" title="email.parser.HeaderParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">HeaderParser</span></code></a>, which can be used if you’re only interested in the344headers of the message.  <code class="xref py py-class docutils literal notranslate"><span class="pre">BytesHeaderParser</span></code> and <code class="xref py py-class docutils literal notranslate"><span class="pre">HeaderParser</span></code>345can be much faster in these situations, since they do not attempt to parse the346message body, instead setting the payload to the raw body.</p>347<dl class="py class">348<dt class="sig sig-object py" id="email.parser.BytesParser">349<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">email.parser.</span></span><span class="sig-name descname"><span class="pre">BytesParser</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">_class</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="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">policy.compat32</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.parser.BytesParser" title="Link to this definition">¶</a></dt>350<dd><p>Create a <code class="xref py py-class docutils literal notranslate"><span class="pre">BytesParser</span></code> instance.  The <em>_class</em> and <em>policy</em>351arguments have the same meaning and semantics as the <em>_factory</em>352and <em>policy</em> arguments of <a class="reference internal" href="#email.parser.BytesFeedParser" title="email.parser.BytesFeedParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesFeedParser</span></code></a>.</p>353<p>Note: <strong>The policy keyword should always be specified</strong>; The default will354change to <a class="reference internal" href="email.policy.html#email.policy.default" title="email.policy.default"><code class="xref py py-data docutils literal notranslate"><span class="pre">email.policy.default</span></code></a> in a future version of Python.</p>355<div class="versionchanged">356<p><span class="versionmodified changed">Changed in version 3.3: </span>Removed the <em>strict</em> argument that was deprecated in 2.4.  Added the357<em>policy</em> keyword.</p>358</div>359<div class="versionchanged">360<p><span class="versionmodified changed">Changed in version 3.6: </span><em>_class</em> defaults to the policy <code class="docutils literal notranslate"><span class="pre">message_factory</span></code>.</p>361</div>362<dl class="py method">363<dt class="sig sig-object py" id="email.parser.BytesParser.parse">364<span class="sig-name descname"><span class="pre">parse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fp</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">headersonly</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="#email.parser.BytesParser.parse" title="Link to this definition">¶</a></dt>365<dd><p>Read all the data from the binary file-like object <em>fp</em>, parse the366resulting bytes, and return the message object.  <em>fp</em> must support367both the <a class="reference internal" href="io.html#io.IOBase.readline" title="io.IOBase.readline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a> and the <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code>368methods.</p>369<p>The bytes contained in <em>fp</em> must be formatted as a block of <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>370(or, if <a class="reference internal" href="email.policy.html#email.policy.EmailPolicy.utf8" title="email.policy.EmailPolicy.utf8"><code class="xref py py-attr docutils literal notranslate"><span class="pre">utf8</span></code></a> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc6532.html"><strong>RFC 6532</strong></a>)371style headers and header continuation lines, optionally preceded by an372envelope header.  The header block is terminated either by the end of the373data or by a blank line.  Following the header block is the body of the374message (which may contain MIME-encoded subparts, including subparts375with a <em class="mailheader">Content-Transfer-Encoding</em> of <code class="docutils literal notranslate"><span class="pre">8bit</span></code>).</p>376<p>Optional <em>headersonly</em> is a flag specifying whether to stop parsing after377reading the headers or not.  The default is <code class="docutils literal notranslate"><span class="pre">False</span></code>, meaning it parses378the entire contents of the file.</p>379</dd></dl>380 381<dl class="py method">382<dt class="sig sig-object py" id="email.parser.BytesParser.parsebytes">383<span class="sig-name descname"><span class="pre">parsebytes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">bytes</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">headersonly</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="#email.parser.BytesParser.parsebytes" title="Link to this definition">¶</a></dt>384<dd><p>Similar to the <a class="reference internal" href="#email.parser.BytesParser.parse" title="email.parser.BytesParser.parse"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse()</span></code></a> method, except it takes a <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like385object</span></a> instead of a file-like object.  Calling this method on a386<span class="xref std std-term">bytes-like object</span> is equivalent to wrapping <em>bytes</em> in a387<a class="reference internal" href="io.html#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a> instance first and calling <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse()</span></code>.</p>388<p>Optional <em>headersonly</em> is as with the <a class="reference internal" href="#email.parser.BytesParser.parse" title="email.parser.BytesParser.parse"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse()</span></code></a> method.</p>389</dd></dl>390 391<div class="versionadded">392<p><span class="versionmodified added">Added in version 3.2.</span></p>393</div>394</dd></dl>395 396<dl class="py class">397<dt class="sig sig-object py" id="email.parser.BytesHeaderParser">398<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">email.parser.</span></span><span class="sig-name descname"><span class="pre">BytesHeaderParser</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">_class</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="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">policy.compat32</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.parser.BytesHeaderParser" title="Link to this definition">¶</a></dt>399<dd><p>Exactly like <a class="reference internal" href="#email.parser.BytesParser" title="email.parser.BytesParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesParser</span></code></a>, except that <em>headersonly</em>400defaults to <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>401<div class="versionadded">402<p><span class="versionmodified added">Added in version 3.3.</span></p>403</div>404</dd></dl>405 406<dl class="py class">407<dt class="sig sig-object py" id="email.parser.Parser">408<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">email.parser.</span></span><span class="sig-name descname"><span class="pre">Parser</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">_class</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="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">policy.compat32</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.parser.Parser" title="Link to this definition">¶</a></dt>409<dd><p>This class is parallel to <a class="reference internal" href="#email.parser.BytesParser" title="email.parser.BytesParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesParser</span></code></a>, but handles string input.</p>410<div class="versionchanged">411<p><span class="versionmodified changed">Changed in version 3.3: </span>Removed the <em>strict</em> argument.  Added the <em>policy</em> keyword.</p>412</div>413<div class="versionchanged">414<p><span class="versionmodified changed">Changed in version 3.6: </span><em>_class</em> defaults to the policy <code class="docutils literal notranslate"><span class="pre">message_factory</span></code>.</p>415</div>416<dl class="py method">417<dt class="sig sig-object py" id="email.parser.Parser.parse">418<span class="sig-name descname"><span class="pre">parse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fp</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">headersonly</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="#email.parser.Parser.parse" title="Link to this definition">¶</a></dt>419<dd><p>Read all the data from the text-mode file-like object <em>fp</em>, parse the420resulting text, and return the root message object.  <em>fp</em> must support421both the <a class="reference internal" href="io.html#io.TextIOBase.readline" title="io.TextIOBase.readline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a> and the422<a class="reference internal" href="io.html#io.TextIOBase.read" title="io.TextIOBase.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a> methods on file-like objects.</p>423<p>Other than the text mode requirement, this method operates like424<a class="reference internal" href="#email.parser.BytesParser.parse" title="email.parser.BytesParser.parse"><code class="xref py py-meth docutils literal notranslate"><span class="pre">BytesParser.parse()</span></code></a>.</p>425</dd></dl>426 427<dl class="py method">428<dt class="sig sig-object py" id="email.parser.Parser.parsestr">429<span class="sig-name descname"><span class="pre">parsestr</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">text</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">headersonly</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="#email.parser.Parser.parsestr" title="Link to this definition">¶</a></dt>430<dd><p>Similar to the <a class="reference internal" href="#email.parser.Parser.parse" title="email.parser.Parser.parse"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse()</span></code></a> method, except it takes a string object431instead of a file-like object.  Calling this method on a string is432equivalent to wrapping <em>text</em> in a <a class="reference internal" href="io.html#io.StringIO" title="io.StringIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">StringIO</span></code></a> instance first433and calling <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse()</span></code>.</p>434<p>Optional <em>headersonly</em> is as with the <a class="reference internal" href="#email.parser.Parser.parse" title="email.parser.Parser.parse"><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse()</span></code></a> method.</p>435</dd></dl>436 437</dd></dl>438 439<dl class="py class">440<dt class="sig sig-object py" id="email.parser.HeaderParser">441<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">email.parser.</span></span><span class="sig-name descname"><span class="pre">HeaderParser</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">_class</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="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">policy.compat32</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.parser.HeaderParser" title="Link to this definition">¶</a></dt>442<dd><p>Exactly like <a class="reference internal" href="#email.parser.Parser" title="email.parser.Parser"><code class="xref py py-class docutils literal notranslate"><span class="pre">Parser</span></code></a>, except that <em>headersonly</em>443defaults to <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>444</dd></dl>445 446<p>Since creating a message object structure from a string or a file object is such447a common task, four functions are provided as a convenience.  They are available448in the top-level <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> package namespace.</p>449<dl class="py function">450<dt class="sig sig-object py" id="email.message_from_bytes">451<span class="sig-prename descclassname"><span class="pre">email.</span></span><span class="sig-name descname"><span class="pre">message_from_bytes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">s</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">_class</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="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">policy.compat32</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message_from_bytes" title="Link to this definition">¶</a></dt>452<dd><p>Return a message object structure from a <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>.  This is453equivalent to <code class="docutils literal notranslate"><span class="pre">BytesParser().parsebytes(s)</span></code>.  Optional <em>_class</em> and454<em>policy</em> are interpreted as with the <a class="reference internal" href="#email.parser.BytesParser" title="email.parser.BytesParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesParser</span></code></a> class455constructor.</p>456<div class="versionadded">457<p><span class="versionmodified added">Added in version 3.2.</span></p>458</div>459<div class="versionchanged">460<p><span class="versionmodified changed">Changed in version 3.3: </span>Removed the <em>strict</em> argument.  Added the <em>policy</em> keyword.</p>461</div>462</dd></dl>463 464<dl class="py function">465<dt class="sig sig-object py" id="email.message_from_binary_file">466<span class="sig-prename descclassname"><span class="pre">email.</span></span><span class="sig-name descname"><span class="pre">message_from_binary_file</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fp</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">_class</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="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">policy.compat32</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message_from_binary_file" title="Link to this definition">¶</a></dt>467<dd><p>Return a message object structure tree from an open binary <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file468object</span></a>.  This is equivalent to <code class="docutils literal notranslate"><span class="pre">BytesParser().parse(fp)</span></code>.  <em>_class</em> and469<em>policy</em> are interpreted as with the <a class="reference internal" href="#email.parser.BytesParser" title="email.parser.BytesParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesParser</span></code></a> class470constructor.</p>471<div class="versionadded">472<p><span class="versionmodified added">Added in version 3.2.</span></p>473</div>474<div class="versionchanged">475<p><span class="versionmodified changed">Changed in version 3.3: </span>Removed the <em>strict</em> argument.  Added the <em>policy</em> keyword.</p>476</div>477</dd></dl>478 479<dl class="py function">480<dt class="sig sig-object py" id="email.message_from_string">481<span class="sig-prename descclassname"><span class="pre">email.</span></span><span class="sig-name descname"><span class="pre">message_from_string</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">s</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">_class</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="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">policy.compat32</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message_from_string" title="Link to this definition">¶</a></dt>482<dd><p>Return a message object structure from a string.  This is equivalent to483<code class="docutils literal notranslate"><span class="pre">Parser().parsestr(s)</span></code>.  <em>_class</em> and <em>policy</em> are interpreted as484with the <a class="reference internal" href="#email.parser.Parser" title="email.parser.Parser"><code class="xref py py-class docutils literal notranslate"><span class="pre">Parser</span></code></a> class constructor.</p>485<div class="versionchanged">486<p><span class="versionmodified changed">Changed in version 3.3: </span>Removed the <em>strict</em> argument.  Added the <em>policy</em> keyword.</p>487</div>488</dd></dl>489 490<dl class="py function">491<dt class="sig sig-object py" id="email.message_from_file">492<span class="sig-prename descclassname"><span class="pre">email.</span></span><span class="sig-name descname"><span class="pre">message_from_file</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fp</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">_class</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="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">policy.compat32</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message_from_file" title="Link to this definition">¶</a></dt>493<dd><p>Return a message object structure tree from an open <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>.494This is equivalent to <code class="docutils literal notranslate"><span class="pre">Parser().parse(fp)</span></code>.  <em>_class</em> and <em>policy</em> are495interpreted as with the <a class="reference internal" href="#email.parser.Parser" title="email.parser.Parser"><code class="xref py py-class docutils literal notranslate"><span class="pre">Parser</span></code></a> class constructor.</p>496<div class="versionchanged">497<p><span class="versionmodified changed">Changed in version 3.3: </span>Removed the <em>strict</em> argument.  Added the <em>policy</em> keyword.</p>498</div>499<div class="versionchanged">500<p><span class="versionmodified changed">Changed in version 3.6: </span><em>_class</em> defaults to the policy <code class="docutils literal notranslate"><span class="pre">message_factory</span></code>.</p>501</div>502</dd></dl>503 504<p>Here’s an example of how you might use <a class="reference internal" href="#email.message_from_bytes" title="email.message_from_bytes"><code class="xref py py-func docutils literal notranslate"><span class="pre">message_from_bytes()</span></code></a> at an505interactive Python prompt:</p>506<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span><span class="w"> </span><span class="nn">email</span>507<span class="gp">&gt;&gt;&gt; </span><span class="n">msg</span> <span class="o">=</span> <span class="n">email</span><span class="o">.</span><span class="n">message_from_bytes</span><span class="p">(</span><span class="n">myBytes</span><span class="p">)</span>508</pre></div>509</div>510</section>511<section id="additional-notes">512<h2>Additional notes<a class="headerlink" href="#additional-notes" title="Link to this heading">¶</a></h2>513<p>Here are some notes on the parsing semantics:</p>514<ul class="simple">515<li><p>Most non-<em class="mimetype">multipart</em> type messages are parsed as a single message516object with a string payload.  These objects will return <code class="docutils literal notranslate"><span class="pre">False</span></code> for517<a class="reference internal" href="email.message.html#email.message.EmailMessage.is_multipart" title="email.message.EmailMessage.is_multipart"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code></a>, and518<a class="reference internal" href="email.message.html#email.message.EmailMessage.iter_parts" title="email.message.EmailMessage.iter_parts"><code class="xref py py-meth docutils literal notranslate"><span class="pre">iter_parts()</span></code></a> will yield an empty list.</p></li>519<li><p>All <em class="mimetype">multipart</em> type messages will be parsed as a container message520object with a list of sub-message objects for their payload.  The outer521container message will return <code class="docutils literal notranslate"><span class="pre">True</span></code> for522<a class="reference internal" href="email.message.html#email.message.EmailMessage.is_multipart" title="email.message.EmailMessage.is_multipart"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code></a>, and523<a class="reference internal" href="email.message.html#email.message.EmailMessage.iter_parts" title="email.message.EmailMessage.iter_parts"><code class="xref py py-meth docutils literal notranslate"><span class="pre">iter_parts()</span></code></a> will yield a list of subparts.</p></li>524<li><p>Most messages with a content type of <em class="mimetype">message/*</em> (such as525<em class="mimetype">message/delivery-status</em> and <em class="mimetype">message/rfc822</em>) will also526be parsed as container object containing a list payload of length 1.  Their527<a class="reference internal" href="email.message.html#email.message.EmailMessage.is_multipart" title="email.message.EmailMessage.is_multipart"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code></a> method will return <code class="docutils literal notranslate"><span class="pre">True</span></code>.528The single element yielded by <a class="reference internal" href="email.message.html#email.message.EmailMessage.iter_parts" title="email.message.EmailMessage.iter_parts"><code class="xref py py-meth docutils literal notranslate"><span class="pre">iter_parts()</span></code></a>529will be a sub-message object.</p></li>530<li><p>Some non-standards-compliant messages may not be internally consistent about531their <em class="mimetype">multipart</em>-edness.  Such messages may have a532<em class="mailheader">Content-Type</em> header of type <em class="mimetype">multipart</em>, but their533<a class="reference internal" href="email.message.html#email.message.EmailMessage.is_multipart" title="email.message.EmailMessage.is_multipart"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code></a> method may return <code class="docutils literal notranslate"><span class="pre">False</span></code>.534If such messages were parsed with the <a class="reference internal" href="#email.parser.FeedParser" title="email.parser.FeedParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">FeedParser</span></code></a>,535they will have an instance of the536<a class="reference internal" href="email.errors.html#email.errors.MultipartInvariantViolationDefect" title="email.errors.MultipartInvariantViolationDefect"><code class="xref py py-class docutils literal notranslate"><span class="pre">MultipartInvariantViolationDefect</span></code></a> class in their537<em>defects</em> attribute list.  See <a class="reference internal" href="email.errors.html#module-email.errors" title="email.errors: The exception classes used by the email package."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.errors</span></code></a> for details.</p></li>538</ul>539</section>540</section>541 542 543            <div class="clearer"></div>544          </div>545        </div>546      </div>547      <div class="sphinxsidebar" role="navigation" aria-label="Main">548        <div class="sphinxsidebarwrapper">549  <div>550    <h3><a href="../contents.html">Table of Contents</a></h3>551    <ul>552<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.parser</span></code>: Parsing email messages</a><ul>553<li><a class="reference internal" href="#feedparser-api">FeedParser API</a></li>554<li><a class="reference internal" href="#parser-api">Parser API</a></li>555<li><a class="reference internal" href="#additional-notes">Additional notes</a></li>556</ul>557</li>558</ul>559 560  </div>561  <div>562    <h4>Previous topic</h4>563    <p class="topless"><a href="email.message.html"564                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.message</span></code>: Representing an email message</a></p>565  </div>566  <div>567    <h4>Next topic</h4>568    <p class="topless"><a href="email.generator.html"569                          title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.generator</span></code>: Generating MIME documents</a></p>570  </div>571  <script>572    document.addEventListener('DOMContentLoaded', () => {573        const title = document.querySelector('meta[property="og:title"]').content;574        const elements = document.querySelectorAll('.improvepage');575        const pageurl = window.location.href.split('?')[0];576        elements.forEach(element => {577            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));578            url.searchParams.set('pagetitle', title);579            url.searchParams.set('pageurl', pageurl);580            url.searchParams.set('pagesource', "library/email.parser.rst");581            element.href = url.toString();582        });583    });584  </script>585  <div role="note" aria-label="source link">586    <h3>This page</h3>587    <ul class="this-page-menu">588      <li><a href="../bugs.html">Report a bug</a></li>589      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>590      <li>591        <a href="https://github.com/python/cpython/blob/main/Doc/library/email.parser.rst?plain=1"592            rel="nofollow">Show source593        </a>594      </li>595      596    </ul>597  </div>598        </div>599<div id="sidebarbutton" title="Collapse sidebar">600<span>«</span>601</div>602 603      </div>604      <div class="clearer"></div>605    </div>  606    <div class="related" role="navigation" aria-label="Related">607      <h3>Navigation</h3>608      <ul>609        <li class="right" style="margin-right: 10px">610          <a href="../genindex.html" title="General Index"611             >index</a></li>612        <li class="right" >613          <a href="../py-modindex.html" title="Python Module Index"614             >modules</a> |</li>615        <li class="right" >616          <a href="email.generator.html" title="email.generator: Generating MIME documents"617             >next</a> |</li>618        <li class="right" >619          <a href="email.message.html" title="email.message: Representing an email message"620             >previous</a> |</li>621 622          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>623          <li><a href="https://www.python.org/">Python</a> &#187;</li>624          <li class="switchers">625            <div class="language_switcher_placeholder"></div>626            <div class="version_switcher_placeholder"></div>627          </li>628          <li>629              630          </li>631    <li id="cpython-language-and-version">632      <a href="../index.html">3.15.0a6 Documentation</a> &#187;633    </li>634 635          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>636          <li class="nav-item nav-item-2"><a href="netdata.html" >Internet Data Handling</a> &#187;</li>637          <li class="nav-item nav-item-3"><a href="email.html" ><code class="xref py py-mod docutils literal notranslate"><span class="pre">email</span></code> — An email and MIME handling package</a> &#187;</li>638        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.parser</span></code>: Parsing email messages</a></li>639                <li class="right">640                    641 642    <div class="inline-search" role="search">643        <form class="inline-search" action="../search.html" method="get">644          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">645          <input type="submit" value="Go">646        </form>647    </div>648                     |649                </li>650            <li class="right">651<label class="theme-selector-label">652    Theme653    <select class="theme-selector" oninput="activateTheme(this.value)">654        <option value="auto" selected>Auto</option>655        <option value="light">Light</option>656        <option value="dark">Dark</option>657    </select>658</label> |</li>659            660      </ul>661    </div>  662    <div class="footer">663    &copy; <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.664    <br>665    This page is licensed under the Python Software Foundation License Version 2.666    <br>667    Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.668    <br>669    670      See <a href="/license.html">History and License</a> for more information.<br>671    672    673    <br>674 675    The Python Software Foundation is a non-profit corporation.676<a href="https://www.python.org/psf/donations/">Please donate.</a>677<br>678    <br>679      Last updated on Mar 10, 2026 (08:58 UTC).680    681      <a href="/bugs.html">Found a bug</a>?682    683    <br>684 685    Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.686    </div>687 688  </body>689</html>