921 lines
84 KiB
HTML
921 lines
84 KiB
HTML
|
|
|||
|
|
<!DOCTYPE html>
|
|||
|
|
|
|||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|||
|
|
<head>
|
|||
|
|
<meta charset="utf-8" />
|
|||
|
|
<title>email.message.Message: Representing an email message using the compat32 API — Python 3.7.4 documentation</title>
|
|||
|
|
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
|||
|
|
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
|||
|
|
|
|||
|
|
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/jquery.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/underscore.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/doctools.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/language_data.js"></script>
|
|||
|
|
|
|||
|
|
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
|||
|
|
|
|||
|
|
<link rel="search" type="application/opensearchdescription+xml"
|
|||
|
|
title="Search within Python 3.7.4 documentation"
|
|||
|
|
href="../_static/opensearch.xml"/>
|
|||
|
|
<link rel="author" title="About these documents" href="../about.html" />
|
|||
|
|
<link rel="index" title="Index" href="../genindex.html" />
|
|||
|
|
<link rel="search" title="Search" href="../search.html" />
|
|||
|
|
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
|||
|
|
<link rel="next" title="email.mime: Creating email and MIME objects from scratch" href="email.mime.html" />
|
|||
|
|
<link rel="prev" title="email: Examples" href="email.examples.html" />
|
|||
|
|
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
|||
|
|
<link rel="canonical" href="https://docs.python.org/3/library/email.compat32-message.html" />
|
|||
|
|
|
|||
|
|
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/switchers.js"></script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
<style>
|
|||
|
|
@media only screen {
|
|||
|
|
table.full-width-table {
|
|||
|
|
width: 100%;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
</style>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</head><body>
|
|||
|
|
|
|||
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
accesskey="I">index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="email.mime.html" title="email.mime: Creating email and MIME objects from scratch"
|
|||
|
|
accesskey="N">next</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="email.examples.html" title="email: Examples"
|
|||
|
|
accesskey="P">previous</a> |</li>
|
|||
|
|
<li><img src="../_static/py.png" alt=""
|
|||
|
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
|
<li>
|
|||
|
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
|
<a href="../index.html">Documentation </a> »
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-2"><a href="netdata.html" >Internet Data Handling</a> »</li>
|
|||
|
|
<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> »</li>
|
|||
|
|
<li class="right">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
|
<input type="hidden" name="area" value="default" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="document">
|
|||
|
|
<div class="documentwrapper">
|
|||
|
|
<div class="bodywrapper">
|
|||
|
|
<div class="body" role="main">
|
|||
|
|
|
|||
|
|
<div class="section" id="email-message-message-representing-an-email-message-using-the-compat32-api">
|
|||
|
|
<span id="compat32-message"></span><h1><a class="reference internal" href="#email.message.Message" title="email.message.Message"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.message.Message</span></code></a>: Representing an email message using the <a class="reference internal" href="email.policy.html#email.policy.compat32" title="email.policy.compat32"><code class="xref py py-data docutils literal notranslate"><span class="pre">compat32</span></code></a> API<a class="headerlink" href="#email-message-message-representing-an-email-message-using-the-compat32-api" title="Permalink to this headline">¶</a></h1>
|
|||
|
|
<p>The <a class="reference internal" href="#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> class is very similar to the
|
|||
|
|
<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, without the methods added by that
|
|||
|
|
class, and with the default behavior of certain other methods being slightly
|
|||
|
|
different. We also document here some methods that, while supported by the
|
|||
|
|
<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, are not recommended unless you are
|
|||
|
|
dealing with legacy code.</p>
|
|||
|
|
<p>The philosophy and structure of the two classes is otherwise the same.</p>
|
|||
|
|
<p>This document describes the behavior under the default (for <a class="reference internal" href="#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a>)
|
|||
|
|
policy <a class="reference internal" href="email.policy.html#email.policy.Compat32" title="email.policy.Compat32"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Compat32</span></code></a>. If you are going to use another policy,
|
|||
|
|
you should be using the <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 instead.</p>
|
|||
|
|
<p>An email message consists of <em>headers</em> and a <em>payload</em>. Headers must be
|
|||
|
|
<span class="target" id="index-0"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc5233.html"><strong>RFC 5233</strong></a> style names and values, where the field name and value are
|
|||
|
|
separated by a colon. The colon is not part of either the field name or the
|
|||
|
|
field value. The payload may be a simple text message, or a binary object, or
|
|||
|
|
a structured sequence of sub-messages each with their own set of headers and
|
|||
|
|
their own payload. The latter type of payload is indicated by the message
|
|||
|
|
having a MIME type such as <em class="mimetype">multipart/*</em> or
|
|||
|
|
<em class="mimetype">message/rfc822</em>.</p>
|
|||
|
|
<p>The conceptual model provided by a <a class="reference internal" href="#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> object is that of an
|
|||
|
|
ordered dictionary of headers with additional methods for accessing both
|
|||
|
|
specialized information from the headers, for accessing the payload, for
|
|||
|
|
generating a serialized version of the message, and for recursively walking
|
|||
|
|
over the object tree. Note that duplicate headers are supported but special
|
|||
|
|
methods must be used to access them.</p>
|
|||
|
|
<p>The <a class="reference internal" href="#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> pseudo-dictionary is indexed by the header names, which
|
|||
|
|
must be ASCII values. The values of the dictionary are strings that are
|
|||
|
|
supposed to contain only ASCII characters; there is some special handling for
|
|||
|
|
non-ASCII input, but it doesn’t always produce the correct results. Headers
|
|||
|
|
are stored and returned in case-preserving form, but field names are matched
|
|||
|
|
case-insensitively. There may also be a single envelope header, also known as
|
|||
|
|
the <em>Unix-From</em> header or the <code class="docutils literal notranslate"><span class="pre">From_</span></code> header. The <em>payload</em> is either a
|
|||
|
|
string or bytes, in the case of simple message objects, or a list of
|
|||
|
|
<a class="reference internal" href="#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> objects, for MIME container documents (e.g.
|
|||
|
|
<em class="mimetype">multipart/*</em> and <em class="mimetype">message/rfc822</em>).</p>
|
|||
|
|
<p>Here are the methods of the <a class="reference internal" href="#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> class:</p>
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="email.message.Message">
|
|||
|
|
<em class="property">class </em><code class="descclassname">email.message.</code><code class="descname">Message</code><span class="sig-paren">(</span><em>policy=compat32</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>If <em>policy</em> is specified (it must be an instance of a <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>
|
|||
|
|
class) use the rules it specifies to update and serialize the representation
|
|||
|
|
of the message. If <em>policy</em> is not set, use the <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 backward compatibility with
|
|||
|
|
the Python 3.2 version of the email package. For more information see the
|
|||
|
|
<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>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.3: </span>The <em>policy</em> keyword argument was added.</p>
|
|||
|
|
</div>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.as_string">
|
|||
|
|
<code class="descname">as_string</code><span class="sig-paren">(</span><em>unixfrom=False</em>, <em>maxheaderlen=0</em>, <em>policy=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.as_string" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the entire message flattened as a string. When optional <em>unixfrom</em>
|
|||
|
|
is true, the envelope header is included in the returned string.
|
|||
|
|
<em>unixfrom</em> defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>. For backward compatibility reasons,
|
|||
|
|
<em>maxheaderlen</em> defaults to <code class="docutils literal notranslate"><span class="pre">0</span></code>, so if you want a different value you
|
|||
|
|
must override it explicitly (the value specified for <em>max_line_length</em> in
|
|||
|
|
the policy will be ignored by this method). The <em>policy</em> argument may be
|
|||
|
|
used to override the default policy obtained from the message instance.
|
|||
|
|
This can be used to control some of the formatting produced by the
|
|||
|
|
method, since the specified <em>policy</em> will be passed to the <code class="docutils literal notranslate"><span class="pre">Generator</span></code>.</p>
|
|||
|
|
<p>Flattening the message may trigger changes to the <a class="reference internal" href="#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> if
|
|||
|
|
defaults need to be filled in to complete the transformation to a string
|
|||
|
|
(for example, MIME boundaries may be generated or modified).</p>
|
|||
|
|
<p>Note that this method is provided as a convenience and may not always
|
|||
|
|
format the message the way you want. For example, by default it does
|
|||
|
|
not do the mangling of lines that begin with <code class="docutils literal notranslate"><span class="pre">From</span></code> that is
|
|||
|
|
required by the unix mbox format. For more flexibility, instantiate a
|
|||
|
|
<a class="reference internal" href="email.generator.html#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a> instance and use its
|
|||
|
|
<a class="reference internal" href="email.generator.html#email.generator.Generator.flatten" title="email.generator.Generator.flatten"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flatten()</span></code></a> method directly. For example:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">io</span> <span class="k">import</span> <span class="n">StringIO</span>
|
|||
|
|
<span class="kn">from</span> <span class="nn">email.generator</span> <span class="k">import</span> <span class="n">Generator</span>
|
|||
|
|
<span class="n">fp</span> <span class="o">=</span> <span class="n">StringIO</span><span class="p">()</span>
|
|||
|
|
<span class="n">g</span> <span class="o">=</span> <span class="n">Generator</span><span class="p">(</span><span class="n">fp</span><span class="p">,</span> <span class="n">mangle_from_</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">maxheaderlen</span><span class="o">=</span><span class="mi">60</span><span class="p">)</span>
|
|||
|
|
<span class="n">g</span><span class="o">.</span><span class="n">flatten</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>
|
|||
|
|
<span class="n">text</span> <span class="o">=</span> <span class="n">fp</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>If the message object contains binary data that is not encoded according
|
|||
|
|
to RFC standards, the non-compliant data will be replaced by unicode
|
|||
|
|
“unknown character” code points. (See also <a class="reference internal" href="#email.message.Message.as_bytes" title="email.message.Message.as_bytes"><code class="xref py py-meth docutils literal notranslate"><span class="pre">as_bytes()</span></code></a> and
|
|||
|
|
<a class="reference internal" href="email.generator.html#email.generator.BytesGenerator" title="email.generator.BytesGenerator"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesGenerator</span></code></a>.)</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.4: </span>the <em>policy</em> keyword argument was added.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.__str__">
|
|||
|
|
<code class="descname">__str__</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.__str__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Equivalent to <a class="reference internal" href="#email.message.Message.as_string" title="email.message.Message.as_string"><code class="xref py py-meth docutils literal notranslate"><span class="pre">as_string()</span></code></a>. Allows <code class="docutils literal notranslate"><span class="pre">str(msg)</span></code> to produce a
|
|||
|
|
string containing the formatted message.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.as_bytes">
|
|||
|
|
<code class="descname">as_bytes</code><span class="sig-paren">(</span><em>unixfrom=False</em>, <em>policy=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.as_bytes" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the entire message flattened as a bytes object. When optional
|
|||
|
|
<em>unixfrom</em> is true, the envelope header is included in the returned
|
|||
|
|
string. <em>unixfrom</em> defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>. The <em>policy</em> argument may be
|
|||
|
|
used to override the default policy obtained from the message instance.
|
|||
|
|
This can be used to control some of the formatting produced by the
|
|||
|
|
method, since the specified <em>policy</em> will be passed to the
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">BytesGenerator</span></code>.</p>
|
|||
|
|
<p>Flattening the message may trigger changes to the <a class="reference internal" href="#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> if
|
|||
|
|
defaults need to be filled in to complete the transformation to a string
|
|||
|
|
(for example, MIME boundaries may be generated or modified).</p>
|
|||
|
|
<p>Note that this method is provided as a convenience and may not always
|
|||
|
|
format the message the way you want. For example, by default it does
|
|||
|
|
not do the mangling of lines that begin with <code class="docutils literal notranslate"><span class="pre">From</span></code> that is
|
|||
|
|
required by the unix mbox format. For more flexibility, instantiate a
|
|||
|
|
<a class="reference internal" href="email.generator.html#email.generator.BytesGenerator" title="email.generator.BytesGenerator"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesGenerator</span></code></a> instance and use its
|
|||
|
|
<a class="reference internal" href="email.generator.html#email.generator.BytesGenerator.flatten" title="email.generator.BytesGenerator.flatten"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flatten()</span></code></a> method directly.
|
|||
|
|
For example:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">io</span> <span class="k">import</span> <span class="n">BytesIO</span>
|
|||
|
|
<span class="kn">from</span> <span class="nn">email.generator</span> <span class="k">import</span> <span class="n">BytesGenerator</span>
|
|||
|
|
<span class="n">fp</span> <span class="o">=</span> <span class="n">BytesIO</span><span class="p">()</span>
|
|||
|
|
<span class="n">g</span> <span class="o">=</span> <span class="n">BytesGenerator</span><span class="p">(</span><span class="n">fp</span><span class="p">,</span> <span class="n">mangle_from_</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">maxheaderlen</span><span class="o">=</span><span class="mi">60</span><span class="p">)</span>
|
|||
|
|
<span class="n">g</span><span class="o">.</span><span class="n">flatten</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>
|
|||
|
|
<span class="n">text</span> <span class="o">=</span> <span class="n">fp</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.4.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.__bytes__">
|
|||
|
|
<code class="descname">__bytes__</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.__bytes__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Equivalent to <a class="reference internal" href="#email.message.Message.as_bytes" title="email.message.Message.as_bytes"><code class="xref py py-meth docutils literal notranslate"><span class="pre">as_bytes()</span></code></a>. Allows <code class="docutils literal notranslate"><span class="pre">bytes(msg)</span></code> to produce a
|
|||
|
|
bytes object containing the formatted message.</p>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.4.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.is_multipart">
|
|||
|
|
<code class="descname">is_multipart</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.is_multipart" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the message’s payload is a list of
|
|||
|
|
sub-<a class="reference internal" href="#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> objects, otherwise return <code class="docutils literal notranslate"><span class="pre">False</span></code>. When
|
|||
|
|
<a class="reference internal" href="#email.message.Message.is_multipart" title="email.message.Message.is_multipart"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code></a> returns <code class="docutils literal notranslate"><span class="pre">False</span></code>, the payload should be a string
|
|||
|
|
object (which might be a CTE encoded binary payload). (Note that
|
|||
|
|
<a class="reference internal" href="#email.message.Message.is_multipart" title="email.message.Message.is_multipart"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code></a> returning <code class="docutils literal notranslate"><span class="pre">True</span></code> does not necessarily mean that
|
|||
|
|
“msg.get_content_maintype() == ‘multipart’” will return the <code class="docutils literal notranslate"><span class="pre">True</span></code>.
|
|||
|
|
For example, <code class="docutils literal notranslate"><span class="pre">is_multipart</span></code> will return <code class="docutils literal notranslate"><span class="pre">True</span></code> when the
|
|||
|
|
<a class="reference internal" href="#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> is of type <code class="docutils literal notranslate"><span class="pre">message/rfc822</span></code>.)</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.set_unixfrom">
|
|||
|
|
<code class="descname">set_unixfrom</code><span class="sig-paren">(</span><em>unixfrom</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.set_unixfrom" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the message’s envelope header to <em>unixfrom</em>, which should be a string.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.get_unixfrom">
|
|||
|
|
<code class="descname">get_unixfrom</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.get_unixfrom" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the message’s envelope header. Defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code> if the
|
|||
|
|
envelope header was never set.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.attach">
|
|||
|
|
<code class="descname">attach</code><span class="sig-paren">(</span><em>payload</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.attach" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Add the given <em>payload</em> to the current payload, which must be <code class="docutils literal notranslate"><span class="pre">None</span></code> or
|
|||
|
|
a list of <a class="reference internal" href="#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> objects before the call. After the call, the
|
|||
|
|
payload will always be a list of <a class="reference internal" href="#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> objects. If you want to
|
|||
|
|
set the payload to a scalar object (e.g. a string), use
|
|||
|
|
<a class="reference internal" href="#email.message.Message.set_payload" title="email.message.Message.set_payload"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_payload()</span></code></a> instead.</p>
|
|||
|
|
<p>This is a legacy method. On the
|
|||
|
|
<code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code> class its functionality is
|
|||
|
|
replaced by <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 the
|
|||
|
|
related <code class="docutils literal notranslate"><span class="pre">make</span></code> and <code class="docutils literal notranslate"><span class="pre">add</span></code> methods.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.get_payload">
|
|||
|
|
<code class="descname">get_payload</code><span class="sig-paren">(</span><em>i=None</em>, <em>decode=False</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.get_payload" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the current payload, which will be a list of
|
|||
|
|
<a class="reference internal" href="#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> objects when <a class="reference internal" href="#email.message.Message.is_multipart" title="email.message.Message.is_multipart"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code></a> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, or a
|
|||
|
|
string when <a class="reference internal" href="#email.message.Message.is_multipart" title="email.message.Message.is_multipart"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code></a> is <code class="docutils literal notranslate"><span class="pre">False</span></code>. If the payload is a list
|
|||
|
|
and you mutate the list object, you modify the message’s payload in place.</p>
|
|||
|
|
<p>With optional argument <em>i</em>, <a class="reference internal" href="#email.message.Message.get_payload" title="email.message.Message.get_payload"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_payload()</span></code></a> will return the <em>i</em>-th
|
|||
|
|
element of the payload, counting from zero, if <a class="reference internal" href="#email.message.Message.is_multipart" title="email.message.Message.is_multipart"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code></a> is
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">True</span></code>. An <a class="reference internal" href="exceptions.html#IndexError" title="IndexError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IndexError</span></code></a> will be raised if <em>i</em> is less than 0 or
|
|||
|
|
greater than or equal to the number of items in the payload. If the
|
|||
|
|
payload is a string (i.e. <a class="reference internal" href="#email.message.Message.is_multipart" title="email.message.Message.is_multipart"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code></a> is <code class="docutils literal notranslate"><span class="pre">False</span></code>) and <em>i</em> is
|
|||
|
|
given, a <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised.</p>
|
|||
|
|
<p>Optional <em>decode</em> is a flag indicating whether the payload should be
|
|||
|
|
decoded or not, according to the <em class="mailheader">Content-Transfer-Encoding</em>
|
|||
|
|
header. When <code class="docutils literal notranslate"><span class="pre">True</span></code> and the message is not a multipart, the payload will
|
|||
|
|
be decoded if this header’s value is <code class="docutils literal notranslate"><span class="pre">quoted-printable</span></code> or <code class="docutils literal notranslate"><span class="pre">base64</span></code>.
|
|||
|
|
If some other encoding is used, or <em class="mailheader">Content-Transfer-Encoding</em>
|
|||
|
|
header is missing, the payload is
|
|||
|
|
returned as-is (undecoded). In all cases the returned value is binary
|
|||
|
|
data. If the message is a multipart and the <em>decode</em> flag is <code class="docutils literal notranslate"><span class="pre">True</span></code>,
|
|||
|
|
then <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned. If the payload is base64 and it was not
|
|||
|
|
perfectly formed (missing padding, characters outside the base64
|
|||
|
|
alphabet), then an appropriate defect will be added to the message’s
|
|||
|
|
defect property (<code class="xref py py-class docutils literal notranslate"><span class="pre">InvalidBase64PaddingDefect</span></code> or
|
|||
|
|
<code class="xref py py-class docutils literal notranslate"><span class="pre">InvalidBase64CharactersDefect</span></code>, respectively).</p>
|
|||
|
|
<p>When <em>decode</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code> (the default) the body is returned as a string
|
|||
|
|
without decoding the <em class="mailheader">Content-Transfer-Encoding</em>. However,
|
|||
|
|
for a <em class="mailheader">Content-Transfer-Encoding</em> of 8bit, an attempt is made
|
|||
|
|
to decode the original bytes using the <code class="docutils literal notranslate"><span class="pre">charset</span></code> specified by the
|
|||
|
|
<em class="mailheader">Content-Type</em> header, using the <code class="docutils literal notranslate"><span class="pre">replace</span></code> error handler.
|
|||
|
|
If no <code class="docutils literal notranslate"><span class="pre">charset</span></code> is specified, or if the <code class="docutils literal notranslate"><span class="pre">charset</span></code> given is not
|
|||
|
|
recognized by the email package, the body is decoded using the default
|
|||
|
|
ASCII charset.</p>
|
|||
|
|
<p>This is a legacy method. On the
|
|||
|
|
<code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code> class its functionality is
|
|||
|
|
replaced by <a class="reference internal" href="email.message.html#email.message.EmailMessage.get_content" title="email.message.EmailMessage.get_content"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_content()</span></code></a> and
|
|||
|
|
<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>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.set_payload">
|
|||
|
|
<code class="descname">set_payload</code><span class="sig-paren">(</span><em>payload</em>, <em>charset=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.set_payload" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the entire message object’s payload to <em>payload</em>. It is the client’s
|
|||
|
|
responsibility to ensure the payload invariants. Optional <em>charset</em> sets
|
|||
|
|
the message’s default character set; see <a class="reference internal" href="#email.message.Message.set_charset" title="email.message.Message.set_charset"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_charset()</span></code></a> for details.</p>
|
|||
|
|
<p>This is a legacy method. On the
|
|||
|
|
<code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code> class its functionality is
|
|||
|
|
replaced by <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>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.set_charset">
|
|||
|
|
<code class="descname">set_charset</code><span class="sig-paren">(</span><em>charset</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.set_charset" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the character set of the payload to <em>charset</em>, which can either be a
|
|||
|
|
<a class="reference internal" href="email.charset.html#email.charset.Charset" title="email.charset.Charset"><code class="xref py py-class docutils literal notranslate"><span class="pre">Charset</span></code></a> instance (see <a class="reference internal" href="email.charset.html#module-email.charset" title="email.charset: Character Sets"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.charset</span></code></a>), a
|
|||
|
|
string naming a character set, or <code class="docutils literal notranslate"><span class="pre">None</span></code>. If it is a string, it will
|
|||
|
|
be converted to a <a class="reference internal" href="email.charset.html#email.charset.Charset" title="email.charset.Charset"><code class="xref py py-class docutils literal notranslate"><span class="pre">Charset</span></code></a> instance. If <em>charset</em>
|
|||
|
|
is <code class="docutils literal notranslate"><span class="pre">None</span></code>, the <code class="docutils literal notranslate"><span class="pre">charset</span></code> parameter will be removed from the
|
|||
|
|
<em class="mailheader">Content-Type</em> header (the message will not be otherwise
|
|||
|
|
modified). Anything else will generate a <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>
|
|||
|
|
<p>If there is no existing <em class="mailheader">MIME-Version</em> header one will be
|
|||
|
|
added. If there is no existing <em class="mailheader">Content-Type</em> header, one
|
|||
|
|
will be added with a value of <em class="mimetype">text/plain</em>. Whether the
|
|||
|
|
<em class="mailheader">Content-Type</em> header already exists or not, its <code class="docutils literal notranslate"><span class="pre">charset</span></code>
|
|||
|
|
parameter will be set to <em>charset.output_charset</em>. If
|
|||
|
|
<em>charset.input_charset</em> and <em>charset.output_charset</em> differ, the payload
|
|||
|
|
will be re-encoded to the <em>output_charset</em>. If there is no existing
|
|||
|
|
<em class="mailheader">Content-Transfer-Encoding</em> header, then the payload will be
|
|||
|
|
transfer-encoded, if needed, using the specified
|
|||
|
|
<a class="reference internal" href="email.charset.html#email.charset.Charset" title="email.charset.Charset"><code class="xref py py-class docutils literal notranslate"><span class="pre">Charset</span></code></a>, and a header with the appropriate value
|
|||
|
|
will be added. If a <em class="mailheader">Content-Transfer-Encoding</em> header
|
|||
|
|
already exists, the payload is assumed to already be correctly encoded
|
|||
|
|
using that <em class="mailheader">Content-Transfer-Encoding</em> and is not modified.</p>
|
|||
|
|
<p>This is a legacy method. On the
|
|||
|
|
<code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code> class its functionality is
|
|||
|
|
replaced by the <em>charset</em> parameter of the
|
|||
|
|
<code class="xref py py-meth docutils literal notranslate"><span class="pre">email.emailmessage.EmailMessage.set_content()</span></code> method.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.get_charset">
|
|||
|
|
<code class="descname">get_charset</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.get_charset" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the <a class="reference internal" href="email.charset.html#email.charset.Charset" title="email.charset.Charset"><code class="xref py py-class docutils literal notranslate"><span class="pre">Charset</span></code></a> instance associated with the
|
|||
|
|
message’s payload.</p>
|
|||
|
|
<p>This is a legacy method. On the
|
|||
|
|
<code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code> class it always returns
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p>The following methods implement a mapping-like interface for accessing the
|
|||
|
|
message’s <span class="target" id="index-1"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2822.html"><strong>RFC 2822</strong></a> headers. Note that there are some semantic differences
|
|||
|
|
between these methods and a normal mapping (i.e. dictionary) interface. For
|
|||
|
|
example, in a dictionary there are no duplicate keys, but here there may be
|
|||
|
|
duplicate message headers. Also, in dictionaries there is no guaranteed
|
|||
|
|
order to the keys returned by <a class="reference internal" href="#email.message.Message.keys" title="email.message.Message.keys"><code class="xref py py-meth docutils literal notranslate"><span class="pre">keys()</span></code></a>, but in a <a class="reference internal" href="#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> object,
|
|||
|
|
headers are always returned in the order they appeared in the original
|
|||
|
|
message, or were added to the message later. Any header deleted and then
|
|||
|
|
re-added are always appended to the end of the header list.</p>
|
|||
|
|
<p>These semantic differences are intentional and are biased toward maximal
|
|||
|
|
convenience.</p>
|
|||
|
|
<p>Note that in all cases, any envelope header present in the message is not
|
|||
|
|
included in the mapping interface.</p>
|
|||
|
|
<p>In a model generated from bytes, any header values that (in contravention of
|
|||
|
|
the RFCs) contain non-ASCII bytes will, when retrieved through this
|
|||
|
|
interface, be represented as <a class="reference internal" href="email.header.html#email.header.Header" title="email.header.Header"><code class="xref py py-class docutils literal notranslate"><span class="pre">Header</span></code></a> objects with
|
|||
|
|
a charset of <cite>unknown-8bit</cite>.</p>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.__len__">
|
|||
|
|
<code class="descname">__len__</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.__len__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the total number of headers, including duplicates.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.__contains__">
|
|||
|
|
<code class="descname">__contains__</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.__contains__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return true if the message object has a field named <em>name</em>. Matching is
|
|||
|
|
done case-insensitively and <em>name</em> should not include the trailing colon.
|
|||
|
|
Used for the <code class="docutils literal notranslate"><span class="pre">in</span></code> operator, e.g.:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="s1">'message-id'</span> <span class="ow">in</span> <span class="n">myMessage</span><span class="p">:</span>
|
|||
|
|
<span class="nb">print</span><span class="p">(</span><span class="s1">'Message-ID:'</span><span class="p">,</span> <span class="n">myMessage</span><span class="p">[</span><span class="s1">'message-id'</span><span class="p">])</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.__getitem__">
|
|||
|
|
<code class="descname">__getitem__</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.__getitem__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the value of the named header field. <em>name</em> should not include the
|
|||
|
|
colon field separator. If the header is missing, <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned; 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> is never raised.</p>
|
|||
|
|
<p>Note that if the named field appears more than once in the message’s
|
|||
|
|
headers, exactly which of those field values will be returned is
|
|||
|
|
undefined. Use the <a class="reference internal" href="#email.message.Message.get_all" title="email.message.Message.get_all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_all()</span></code></a> method to get the values of all the
|
|||
|
|
extant named headers.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.__setitem__">
|
|||
|
|
<code class="descname">__setitem__</code><span class="sig-paren">(</span><em>name</em>, <em>val</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.__setitem__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Add a header to the message with field name <em>name</em> and value <em>val</em>. The
|
|||
|
|
field is appended to the end of the message’s existing fields.</p>
|
|||
|
|
<p>Note that this does <em>not</em> overwrite or delete any existing header with the same
|
|||
|
|
name. If you want to ensure that the new header is the only one present in the
|
|||
|
|
message with field name <em>name</em>, delete the field first, e.g.:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">del</span> <span class="n">msg</span><span class="p">[</span><span class="s1">'subject'</span><span class="p">]</span>
|
|||
|
|
<span class="n">msg</span><span class="p">[</span><span class="s1">'subject'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'Python roolz!'</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.__delitem__">
|
|||
|
|
<code class="descname">__delitem__</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.__delitem__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Delete all occurrences of the field with name <em>name</em> from the message’s
|
|||
|
|
headers. No exception is raised if the named field isn’t present in the
|
|||
|
|
headers.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.keys">
|
|||
|
|
<code class="descname">keys</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.keys" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return a list of all the message’s header field names.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.values">
|
|||
|
|
<code class="descname">values</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.values" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return a list of all the message’s field values.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.items">
|
|||
|
|
<code class="descname">items</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.items" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return a list of 2-tuples containing all the message’s field headers and
|
|||
|
|
values.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.get">
|
|||
|
|
<code class="descname">get</code><span class="sig-paren">(</span><em>name</em>, <em>failobj=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.get" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the value of the named header field. This is identical to
|
|||
|
|
<a class="reference internal" href="#email.message.Message.__getitem__" title="email.message.Message.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> except that optional <em>failobj</em> is returned if the
|
|||
|
|
named header is missing (defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p>Here are some additional useful methods:</p>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.get_all">
|
|||
|
|
<code class="descname">get_all</code><span class="sig-paren">(</span><em>name</em>, <em>failobj=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.get_all" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return a list of all the values for the field named <em>name</em>. If there are
|
|||
|
|
no such named headers in the message, <em>failobj</em> is returned (defaults to
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">None</span></code>).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.add_header">
|
|||
|
|
<code class="descname">add_header</code><span class="sig-paren">(</span><em>_name</em>, <em>_value</em>, <em>**_params</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.add_header" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Extended header setting. This method is similar to <a class="reference internal" href="#email.message.Message.__setitem__" title="email.message.Message.__setitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setitem__()</span></code></a>
|
|||
|
|
except that additional header parameters can be provided as keyword
|
|||
|
|
arguments. <em>_name</em> is the header field to add and <em>_value</em> is the
|
|||
|
|
<em>primary</em> value for the header.</p>
|
|||
|
|
<p>For each item in the keyword argument dictionary <em>_params</em>, the key is
|
|||
|
|
taken as the parameter name, with underscores converted to dashes (since
|
|||
|
|
dashes are illegal in Python identifiers). Normally, the parameter will
|
|||
|
|
be added as <code class="docutils literal notranslate"><span class="pre">key="value"</span></code> unless the value is <code class="docutils literal notranslate"><span class="pre">None</span></code>, in which case
|
|||
|
|
only the key will be added. If the value contains non-ASCII characters,
|
|||
|
|
it can be specified as a three tuple in the format
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">(CHARSET,</span> <span class="pre">LANGUAGE,</span> <span class="pre">VALUE)</span></code>, where <code class="docutils literal notranslate"><span class="pre">CHARSET</span></code> is a string naming the
|
|||
|
|
charset to be used to encode the value, <code class="docutils literal notranslate"><span class="pre">LANGUAGE</span></code> can usually be set
|
|||
|
|
to <code class="docutils literal notranslate"><span class="pre">None</span></code> or the empty string (see <span class="target" id="index-2"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2231.html"><strong>RFC 2231</strong></a> for other possibilities),
|
|||
|
|
and <code class="docutils literal notranslate"><span class="pre">VALUE</span></code> is the string value containing non-ASCII code points. If
|
|||
|
|
a three tuple is not passed and the value contains non-ASCII characters,
|
|||
|
|
it is automatically encoded in <span class="target" id="index-3"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2231.html"><strong>RFC 2231</strong></a> format using a <code class="docutils literal notranslate"><span class="pre">CHARSET</span></code>
|
|||
|
|
of <code class="docutils literal notranslate"><span class="pre">utf-8</span></code> and a <code class="docutils literal notranslate"><span class="pre">LANGUAGE</span></code> of <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
|||
|
|
<p>Here’s an example:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">msg</span><span class="o">.</span><span class="n">add_header</span><span class="p">(</span><span class="s1">'Content-Disposition'</span><span class="p">,</span> <span class="s1">'attachment'</span><span class="p">,</span> <span class="n">filename</span><span class="o">=</span><span class="s1">'bud.gif'</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>This will add a header that looks like</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Content</span><span class="o">-</span><span class="n">Disposition</span><span class="p">:</span> <span class="n">attachment</span><span class="p">;</span> <span class="n">filename</span><span class="o">=</span><span class="s2">"bud.gif"</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>An example with non-ASCII characters:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">msg</span><span class="o">.</span><span class="n">add_header</span><span class="p">(</span><span class="s1">'Content-Disposition'</span><span class="p">,</span> <span class="s1">'attachment'</span><span class="p">,</span>
|
|||
|
|
<span class="n">filename</span><span class="o">=</span><span class="p">(</span><span class="s1">'iso-8859-1'</span><span class="p">,</span> <span class="s1">''</span><span class="p">,</span> <span class="s1">'Fußballer.ppt'</span><span class="p">))</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>Which produces</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Content</span><span class="o">-</span><span class="n">Disposition</span><span class="p">:</span> <span class="n">attachment</span><span class="p">;</span> <span class="n">filename</span><span class="o">*=</span><span class="s2">"iso-8859-1''Fu%DFballer.ppt"</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.replace_header">
|
|||
|
|
<code class="descname">replace_header</code><span class="sig-paren">(</span><em>_name</em>, <em>_value</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.replace_header" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Replace a header. Replace the first header found in the message that
|
|||
|
|
matches <em>_name</em>, retaining header order and field name case. If no
|
|||
|
|
matching header was found, 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> is raised.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.get_content_type">
|
|||
|
|
<code class="descname">get_content_type</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.get_content_type" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the message’s content type. The returned string is coerced to
|
|||
|
|
lower case of the form <em class="mimetype">maintype/subtype</em>. If there was no
|
|||
|
|
<em class="mailheader">Content-Type</em> header in the message the default type as given
|
|||
|
|
by <a class="reference internal" href="#email.message.Message.get_default_type" title="email.message.Message.get_default_type"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_default_type()</span></code></a> will be returned. Since according to
|
|||
|
|
<span class="target" id="index-4"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2045.html"><strong>RFC 2045</strong></a>, messages always have a default type, <a class="reference internal" href="#email.message.Message.get_content_type" title="email.message.Message.get_content_type"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_content_type()</span></code></a>
|
|||
|
|
will always return a value.</p>
|
|||
|
|
<p><span class="target" id="index-5"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2045.html"><strong>RFC 2045</strong></a> defines a message’s default type to be <em class="mimetype">text/plain</em>
|
|||
|
|
unless it appears inside a <em class="mimetype">multipart/digest</em> container, in
|
|||
|
|
which case it would be <em class="mimetype">message/rfc822</em>. If the
|
|||
|
|
<em class="mailheader">Content-Type</em> header has an invalid type specification,
|
|||
|
|
<span class="target" id="index-6"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2045.html"><strong>RFC 2045</strong></a> mandates that the default type be <em class="mimetype">text/plain</em>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.get_content_maintype">
|
|||
|
|
<code class="descname">get_content_maintype</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.get_content_maintype" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the message’s main content type. This is the <em class="mimetype">maintype</em>
|
|||
|
|
part of the string returned by <a class="reference internal" href="#email.message.Message.get_content_type" title="email.message.Message.get_content_type"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_content_type()</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.get_content_subtype">
|
|||
|
|
<code class="descname">get_content_subtype</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.get_content_subtype" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the message’s sub-content type. This is the <em class="mimetype">subtype</em>
|
|||
|
|
part of the string returned by <a class="reference internal" href="#email.message.Message.get_content_type" title="email.message.Message.get_content_type"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_content_type()</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.get_default_type">
|
|||
|
|
<code class="descname">get_default_type</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.get_default_type" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the default content type. Most messages have a default content
|
|||
|
|
type of <em class="mimetype">text/plain</em>, except for messages that are subparts of
|
|||
|
|
<em class="mimetype">multipart/digest</em> containers. Such subparts have a default
|
|||
|
|
content type of <em class="mimetype">message/rfc822</em>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.set_default_type">
|
|||
|
|
<code class="descname">set_default_type</code><span class="sig-paren">(</span><em>ctype</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.set_default_type" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the default content type. <em>ctype</em> should either be
|
|||
|
|
<em class="mimetype">text/plain</em> or <em class="mimetype">message/rfc822</em>, although this is not
|
|||
|
|
enforced. The default content type is not stored in the
|
|||
|
|
<em class="mailheader">Content-Type</em> header.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.get_params">
|
|||
|
|
<code class="descname">get_params</code><span class="sig-paren">(</span><em>failobj=None</em>, <em>header='content-type'</em>, <em>unquote=True</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.get_params" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the message’s <em class="mailheader">Content-Type</em> parameters, as a list.
|
|||
|
|
The elements of the returned list are 2-tuples of key/value pairs, as
|
|||
|
|
split on the <code class="docutils literal notranslate"><span class="pre">'='</span></code> sign. The left hand side of the <code class="docutils literal notranslate"><span class="pre">'='</span></code> is the key,
|
|||
|
|
while the right hand side is the value. If there is no <code class="docutils literal notranslate"><span class="pre">'='</span></code> sign in
|
|||
|
|
the parameter the value is the empty string, otherwise the value is as
|
|||
|
|
described in <a class="reference internal" href="#email.message.Message.get_param" title="email.message.Message.get_param"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_param()</span></code></a> and is unquoted if optional <em>unquote</em> is
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">True</span></code> (the default).</p>
|
|||
|
|
<p>Optional <em>failobj</em> is the object to return if there is no
|
|||
|
|
<em class="mailheader">Content-Type</em> header. Optional <em>header</em> is the header to
|
|||
|
|
search instead of <em class="mailheader">Content-Type</em>.</p>
|
|||
|
|
<p>This is a legacy method. On the
|
|||
|
|
<code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code> class its functionality is
|
|||
|
|
replaced by the <em>params</em> property of the individual header objects
|
|||
|
|
returned by the header access methods.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.get_param">
|
|||
|
|
<code class="descname">get_param</code><span class="sig-paren">(</span><em>param</em>, <em>failobj=None</em>, <em>header='content-type'</em>, <em>unquote=True</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.get_param" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the value of the <em class="mailheader">Content-Type</em> header’s parameter
|
|||
|
|
<em>param</em> as a string. If the message has no <em class="mailheader">Content-Type</em>
|
|||
|
|
header or if there is no such parameter, then <em>failobj</em> is returned
|
|||
|
|
(defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>).</p>
|
|||
|
|
<p>Optional <em>header</em> if given, specifies the message header to use instead of
|
|||
|
|
<em class="mailheader">Content-Type</em>.</p>
|
|||
|
|
<p>Parameter keys are always compared case insensitively. The return value
|
|||
|
|
can either be a string, or a 3-tuple if the parameter was <span class="target" id="index-7"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2231.html"><strong>RFC 2231</strong></a>
|
|||
|
|
encoded. When it’s a 3-tuple, the elements of the value are of the form
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">(CHARSET,</span> <span class="pre">LANGUAGE,</span> <span class="pre">VALUE)</span></code>. Note that both <code class="docutils literal notranslate"><span class="pre">CHARSET</span></code> and
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">LANGUAGE</span></code> can be <code class="docutils literal notranslate"><span class="pre">None</span></code>, in which case you should consider <code class="docutils literal notranslate"><span class="pre">VALUE</span></code>
|
|||
|
|
to be encoded in the <code class="docutils literal notranslate"><span class="pre">us-ascii</span></code> charset. You can usually ignore
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">LANGUAGE</span></code>.</p>
|
|||
|
|
<p>If your application doesn’t care whether the parameter was encoded as in
|
|||
|
|
<span class="target" id="index-8"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2231.html"><strong>RFC 2231</strong></a>, you can collapse the parameter value by calling
|
|||
|
|
<a class="reference internal" href="email.utils.html#email.utils.collapse_rfc2231_value" title="email.utils.collapse_rfc2231_value"><code class="xref py py-func docutils literal notranslate"><span class="pre">email.utils.collapse_rfc2231_value()</span></code></a>, passing in the return value
|
|||
|
|
from <a class="reference internal" href="#email.message.Message.get_param" title="email.message.Message.get_param"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_param()</span></code></a>. This will return a suitably decoded Unicode
|
|||
|
|
string when the value is a tuple, or the original string unquoted if it
|
|||
|
|
isn’t. For example:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">rawparam</span> <span class="o">=</span> <span class="n">msg</span><span class="o">.</span><span class="n">get_param</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">)</span>
|
|||
|
|
<span class="n">param</span> <span class="o">=</span> <span class="n">email</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">collapse_rfc2231_value</span><span class="p">(</span><span class="n">rawparam</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>In any case, the parameter value (either the returned string, or the
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">VALUE</span></code> item in the 3-tuple) is always unquoted, unless <em>unquote</em> is set
|
|||
|
|
to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
|||
|
|
<p>This is a legacy method. On the
|
|||
|
|
<code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code> class its functionality is
|
|||
|
|
replaced by the <em>params</em> property of the individual header objects
|
|||
|
|
returned by the header access methods.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.set_param">
|
|||
|
|
<code class="descname">set_param</code><span class="sig-paren">(</span><em>param</em>, <em>value</em>, <em>header='Content-Type'</em>, <em>requote=True</em>, <em>charset=None</em>, <em>language=''</em>, <em>replace=False</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.set_param" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set a parameter in the <em class="mailheader">Content-Type</em> header. If the
|
|||
|
|
parameter already exists in the header, its value will be replaced with
|
|||
|
|
<em>value</em>. If the <em class="mailheader">Content-Type</em> header as not yet been defined
|
|||
|
|
for this message, it will be set to <em class="mimetype">text/plain</em> and the new
|
|||
|
|
parameter value will be appended as per <span class="target" id="index-9"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2045.html"><strong>RFC 2045</strong></a>.</p>
|
|||
|
|
<p>Optional <em>header</em> specifies an alternative header to
|
|||
|
|
<em class="mailheader">Content-Type</em>, and all parameters will be quoted as necessary
|
|||
|
|
unless optional <em>requote</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code> (the default is <code class="docutils literal notranslate"><span class="pre">True</span></code>).</p>
|
|||
|
|
<p>If optional <em>charset</em> is specified, the parameter will be encoded
|
|||
|
|
according to <span class="target" id="index-10"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2231.html"><strong>RFC 2231</strong></a>. Optional <em>language</em> specifies the RFC 2231
|
|||
|
|
language, defaulting to the empty string. Both <em>charset</em> and <em>language</em>
|
|||
|
|
should be strings.</p>
|
|||
|
|
<p>If <em>replace</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code> (the default) the header is moved to the
|
|||
|
|
end of the list of headers. If <em>replace</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the header
|
|||
|
|
will be updated in place.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.4: </span><code class="docutils literal notranslate"><span class="pre">replace</span></code> keyword was added.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.del_param">
|
|||
|
|
<code class="descname">del_param</code><span class="sig-paren">(</span><em>param</em>, <em>header='content-type'</em>, <em>requote=True</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.del_param" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Remove the given parameter completely from the <em class="mailheader">Content-Type</em>
|
|||
|
|
header. The header will be re-written in place without the parameter or
|
|||
|
|
its value. All values will be quoted as necessary unless <em>requote</em> is
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">False</span></code> (the default is <code class="docutils literal notranslate"><span class="pre">True</span></code>). Optional <em>header</em> specifies an
|
|||
|
|
alternative to <em class="mailheader">Content-Type</em>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.set_type">
|
|||
|
|
<code class="descname">set_type</code><span class="sig-paren">(</span><em>type</em>, <em>header='Content-Type'</em>, <em>requote=True</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.set_type" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the main type and subtype for the <em class="mailheader">Content-Type</em>
|
|||
|
|
header. <em>type</em> must be a string in the form <em class="mimetype">maintype/subtype</em>,
|
|||
|
|
otherwise a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised.</p>
|
|||
|
|
<p>This method replaces the <em class="mailheader">Content-Type</em> header, keeping all
|
|||
|
|
the parameters in place. If <em>requote</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, this leaves the
|
|||
|
|
existing header’s quoting as is, otherwise the parameters will be quoted
|
|||
|
|
(the default).</p>
|
|||
|
|
<p>An alternative header can be specified in the <em>header</em> argument. When the
|
|||
|
|
<em class="mailheader">Content-Type</em> header is set a <em class="mailheader">MIME-Version</em>
|
|||
|
|
header is also added.</p>
|
|||
|
|
<p>This is a legacy method. On the
|
|||
|
|
<code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code> class its functionality is
|
|||
|
|
replaced by the <code class="docutils literal notranslate"><span class="pre">make_</span></code> and <code class="docutils literal notranslate"><span class="pre">add_</span></code> methods.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.get_filename">
|
|||
|
|
<code class="descname">get_filename</code><span class="sig-paren">(</span><em>failobj=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.get_filename" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the value of the <code class="docutils literal notranslate"><span class="pre">filename</span></code> parameter of the
|
|||
|
|
<em class="mailheader">Content-Disposition</em> header of the message. If the header
|
|||
|
|
does not have a <code class="docutils literal notranslate"><span class="pre">filename</span></code> parameter, this method falls back to looking
|
|||
|
|
for the <code class="docutils literal notranslate"><span class="pre">name</span></code> parameter on the <em class="mailheader">Content-Type</em> header. If
|
|||
|
|
neither is found, or the header is missing, then <em>failobj</em> is returned.
|
|||
|
|
The returned string will always be unquoted as per
|
|||
|
|
<a class="reference internal" href="email.utils.html#email.utils.unquote" title="email.utils.unquote"><code class="xref py py-func docutils literal notranslate"><span class="pre">email.utils.unquote()</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.get_boundary">
|
|||
|
|
<code class="descname">get_boundary</code><span class="sig-paren">(</span><em>failobj=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.get_boundary" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the value of the <code class="docutils literal notranslate"><span class="pre">boundary</span></code> parameter of the
|
|||
|
|
<em class="mailheader">Content-Type</em> header of the message, or <em>failobj</em> if either
|
|||
|
|
the header is missing, or has no <code class="docutils literal notranslate"><span class="pre">boundary</span></code> parameter. The returned
|
|||
|
|
string will always be unquoted as per <a class="reference internal" href="email.utils.html#email.utils.unquote" title="email.utils.unquote"><code class="xref py py-func docutils literal notranslate"><span class="pre">email.utils.unquote()</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.set_boundary">
|
|||
|
|
<code class="descname">set_boundary</code><span class="sig-paren">(</span><em>boundary</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.set_boundary" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the <code class="docutils literal notranslate"><span class="pre">boundary</span></code> parameter of the <em class="mailheader">Content-Type</em> header to
|
|||
|
|
<em>boundary</em>. <a class="reference internal" href="#email.message.Message.set_boundary" title="email.message.Message.set_boundary"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_boundary()</span></code></a> will always quote <em>boundary</em> if
|
|||
|
|
necessary. A <a class="reference internal" href="email.errors.html#email.errors.HeaderParseError" title="email.errors.HeaderParseError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">HeaderParseError</span></code></a> is raised if the
|
|||
|
|
message object has no <em class="mailheader">Content-Type</em> header.</p>
|
|||
|
|
<p>Note that using this method is subtly different than deleting the old
|
|||
|
|
<em class="mailheader">Content-Type</em> header and adding a new one with the new
|
|||
|
|
boundary via <a class="reference internal" href="#email.message.Message.add_header" title="email.message.Message.add_header"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_header()</span></code></a>, because <a class="reference internal" href="#email.message.Message.set_boundary" title="email.message.Message.set_boundary"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_boundary()</span></code></a> preserves
|
|||
|
|
the order of the <em class="mailheader">Content-Type</em> header in the list of
|
|||
|
|
headers. However, it does <em>not</em> preserve any continuation lines which may
|
|||
|
|
have been present in the original <em class="mailheader">Content-Type</em> header.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.get_content_charset">
|
|||
|
|
<code class="descname">get_content_charset</code><span class="sig-paren">(</span><em>failobj=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.get_content_charset" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the <code class="docutils literal notranslate"><span class="pre">charset</span></code> parameter of the <em class="mailheader">Content-Type</em> header,
|
|||
|
|
coerced to lower case. If there is no <em class="mailheader">Content-Type</em> header, or if
|
|||
|
|
that header has no <code class="docutils literal notranslate"><span class="pre">charset</span></code> parameter, <em>failobj</em> is returned.</p>
|
|||
|
|
<p>Note that this method differs from <a class="reference internal" href="#email.message.Message.get_charset" title="email.message.Message.get_charset"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_charset()</span></code></a> which returns the
|
|||
|
|
<a class="reference internal" href="email.charset.html#email.charset.Charset" title="email.charset.Charset"><code class="xref py py-class docutils literal notranslate"><span class="pre">Charset</span></code></a> instance for the default encoding of the message body.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.get_charsets">
|
|||
|
|
<code class="descname">get_charsets</code><span class="sig-paren">(</span><em>failobj=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.get_charsets" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return a list containing the character set names in the message. If the
|
|||
|
|
message is a <em class="mimetype">multipart</em>, then the list will contain one element
|
|||
|
|
for each subpart in the payload, otherwise, it will be a list of length 1.</p>
|
|||
|
|
<p>Each item in the list will be a string which is the value of the
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">charset</span></code> parameter in the <em class="mailheader">Content-Type</em> header for the
|
|||
|
|
represented subpart. However, if the subpart has no
|
|||
|
|
<em class="mailheader">Content-Type</em> header, no <code class="docutils literal notranslate"><span class="pre">charset</span></code> parameter, or is not of
|
|||
|
|
the <em class="mimetype">text</em> main MIME type, then that item in the returned list
|
|||
|
|
will be <em>failobj</em>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.get_content_disposition">
|
|||
|
|
<code class="descname">get_content_disposition</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.get_content_disposition" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the lowercased value (without parameters) of the message’s
|
|||
|
|
<em class="mailheader">Content-Disposition</em> header if it has one, or <code class="docutils literal notranslate"><span class="pre">None</span></code>. The
|
|||
|
|
possible values for this method are <em>inline</em>, <em>attachment</em> or <code class="docutils literal notranslate"><span class="pre">None</span></code>
|
|||
|
|
if the message follows <span class="target" id="index-11"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2183.html"><strong>RFC 2183</strong></a>.</p>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.5.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.Message.walk">
|
|||
|
|
<code class="descname">walk</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.Message.walk" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The <a class="reference internal" href="#email.message.Message.walk" title="email.message.Message.walk"><code class="xref py py-meth docutils literal notranslate"><span class="pre">walk()</span></code></a> method is an all-purpose generator which can be used to
|
|||
|
|
iterate over all the parts and subparts of a message object tree, in
|
|||
|
|
depth-first traversal order. You will typically use <a class="reference internal" href="#email.message.Message.walk" title="email.message.Message.walk"><code class="xref py py-meth docutils literal notranslate"><span class="pre">walk()</span></code></a> as the
|
|||
|
|
iterator in a <code class="docutils literal notranslate"><span class="pre">for</span></code> loop; each iteration returns the next subpart.</p>
|
|||
|
|
<p>Here’s an example that prints the MIME type of every part of a multipart
|
|||
|
|
message structure:</p>
|
|||
|
|
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">for</span> <span class="n">part</span> <span class="ow">in</span> <span class="n">msg</span><span class="o">.</span><span class="n">walk</span><span class="p">():</span>
|
|||
|
|
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">part</span><span class="o">.</span><span class="n">get_content_type</span><span class="p">())</span>
|
|||
|
|
<span class="go">multipart/report</span>
|
|||
|
|
<span class="go">text/plain</span>
|
|||
|
|
<span class="go">message/delivery-status</span>
|
|||
|
|
<span class="go">text/plain</span>
|
|||
|
|
<span class="go">text/plain</span>
|
|||
|
|
<span class="go">message/rfc822</span>
|
|||
|
|
<span class="go">text/plain</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p><code class="docutils literal notranslate"><span class="pre">walk</span></code> iterates over the subparts of any part where
|
|||
|
|
<a class="reference internal" href="#email.message.Message.is_multipart" title="email.message.Message.is_multipart"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code></a> returns <code class="docutils literal notranslate"><span class="pre">True</span></code>, even though
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">msg.get_content_maintype()</span> <span class="pre">==</span> <span class="pre">'multipart'</span></code> may return <code class="docutils literal notranslate"><span class="pre">False</span></code>. We
|
|||
|
|
can see this in our example by making use of the <code class="docutils literal notranslate"><span class="pre">_structure</span></code> debug
|
|||
|
|
helper function:</p>
|
|||
|
|
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">for</span> <span class="n">part</span> <span class="ow">in</span> <span class="n">msg</span><span class="o">.</span><span class="n">walk</span><span class="p">():</span>
|
|||
|
|
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">part</span><span class="o">.</span><span class="n">get_content_maintype</span><span class="p">()</span> <span class="o">==</span> <span class="s1">'multipart'</span><span class="p">,</span>
|
|||
|
|
<span class="gp">... </span> <span class="n">part</span><span class="o">.</span><span class="n">is_multipart</span><span class="p">())</span>
|
|||
|
|
<span class="go">True True</span>
|
|||
|
|
<span class="go">False False</span>
|
|||
|
|
<span class="go">False True</span>
|
|||
|
|
<span class="go">False False</span>
|
|||
|
|
<span class="go">False False</span>
|
|||
|
|
<span class="go">False True</span>
|
|||
|
|
<span class="go">False False</span>
|
|||
|
|
<span class="gp">>>> </span><span class="n">_structure</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>
|
|||
|
|
<span class="go">multipart/report</span>
|
|||
|
|
<span class="go"> text/plain</span>
|
|||
|
|
<span class="go"> message/delivery-status</span>
|
|||
|
|
<span class="go"> text/plain</span>
|
|||
|
|
<span class="go"> text/plain</span>
|
|||
|
|
<span class="go"> message/rfc822</span>
|
|||
|
|
<span class="go"> text/plain</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>Here the <code class="docutils literal notranslate"><span class="pre">message</span></code> parts are not <code class="docutils literal notranslate"><span class="pre">multiparts</span></code>, but they do contain
|
|||
|
|
subparts. <code class="docutils literal notranslate"><span class="pre">is_multipart()</span></code> returns <code class="docutils literal notranslate"><span class="pre">True</span></code> and <code class="docutils literal notranslate"><span class="pre">walk</span></code> descends
|
|||
|
|
into the subparts.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p><a class="reference internal" href="#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> objects can also optionally contain two instance attributes,
|
|||
|
|
which can be used when generating the plain text of a MIME message.</p>
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="email.message.Message.preamble">
|
|||
|
|
<code class="descname">preamble</code><a class="headerlink" href="#email.message.Message.preamble" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The format of a MIME document allows for some text between the blank line
|
|||
|
|
following the headers, and the first multipart boundary string. Normally,
|
|||
|
|
this text is never visible in a MIME-aware mail reader because it falls
|
|||
|
|
outside the standard MIME armor. However, when viewing the raw text of
|
|||
|
|
the message, or when viewing the message in a non-MIME aware reader, this
|
|||
|
|
text can become visible.</p>
|
|||
|
|
<p>The <em>preamble</em> attribute contains this leading extra-armor text for MIME
|
|||
|
|
documents. When the <a class="reference internal" href="email.parser.html#email.parser.Parser" title="email.parser.Parser"><code class="xref py py-class docutils literal notranslate"><span class="pre">Parser</span></code></a> discovers some text
|
|||
|
|
after the headers but before the first boundary string, it assigns this
|
|||
|
|
text to the message’s <em>preamble</em> attribute. When the
|
|||
|
|
<a class="reference internal" href="email.generator.html#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a> is writing out the plain text
|
|||
|
|
representation of a MIME message, and it finds the
|
|||
|
|
message has a <em>preamble</em> attribute, it will write this text in the area
|
|||
|
|
between the headers and the first boundary. See <a class="reference internal" href="email.parser.html#module-email.parser" title="email.parser: Parse flat text email messages to produce a message object structure."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.parser</span></code></a> and
|
|||
|
|
<a class="reference internal" href="email.generator.html#module-email.generator" title="email.generator: Generate flat text email messages from a message structure."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.generator</span></code></a> for details.</p>
|
|||
|
|
<p>Note that if the message object has no preamble, the <em>preamble</em> attribute
|
|||
|
|
will be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="email.message.Message.epilogue">
|
|||
|
|
<code class="descname">epilogue</code><a class="headerlink" href="#email.message.Message.epilogue" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The <em>epilogue</em> attribute acts the same way as the <em>preamble</em> attribute,
|
|||
|
|
except that it contains text that appears between the last boundary and
|
|||
|
|
the end of the message.</p>
|
|||
|
|
<p>You do not need to set the epilogue to the empty string in order for the
|
|||
|
|
<a class="reference internal" href="email.generator.html#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a> to print a newline at the end of the
|
|||
|
|
file.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="email.message.Message.defects">
|
|||
|
|
<code class="descname">defects</code><a class="headerlink" href="#email.message.Message.defects" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The <em>defects</em> attribute contains a list of all the problems found when
|
|||
|
|
parsing this message. 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 a detailed description
|
|||
|
|
of the possible parsing defects.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
|||
|
|
<div class="sphinxsidebarwrapper">
|
|||
|
|
<h4>Previous topic</h4>
|
|||
|
|
<p class="topless"><a href="email.examples.html"
|
|||
|
|
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email</span></code>: Examples</a></p>
|
|||
|
|
<h4>Next topic</h4>
|
|||
|
|
<p class="topless"><a href="email.mime.html"
|
|||
|
|
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.mime</span></code>: Creating email and MIME objects from scratch</a></p>
|
|||
|
|
<div role="note" aria-label="source link">
|
|||
|
|
<h3>This Page</h3>
|
|||
|
|
<ul class="this-page-menu">
|
|||
|
|
<li><a href="../bugs.html">Report a Bug</a></li>
|
|||
|
|
<li>
|
|||
|
|
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/email.compat32-message.rst"
|
|||
|
|
rel="nofollow">Show Source
|
|||
|
|
</a>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="clearer"></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
>index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="email.mime.html" title="email.mime: Creating email and MIME objects from scratch"
|
|||
|
|
>next</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="email.examples.html" title="email: Examples"
|
|||
|
|
>previous</a> |</li>
|
|||
|
|
<li><img src="../_static/py.png" alt=""
|
|||
|
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
|
<li>
|
|||
|
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
|
<a href="../index.html">Documentation </a> »
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-2"><a href="netdata.html" >Internet Data Handling</a> »</li>
|
|||
|
|
<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> »</li>
|
|||
|
|
<li class="right">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
|
<input type="hidden" name="area" value="default" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<div class="footer">
|
|||
|
|
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
|||
|
|
<br />
|
|||
|
|
The Python Software Foundation is a non-profit corporation.
|
|||
|
|
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
|||
|
|
<br />
|
|||
|
|
Last updated on Jul 13, 2019.
|
|||
|
|
<a href="../bugs.html">Found a bug</a>?
|
|||
|
|
<br />
|
|||
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
</body>
|
|||
|
|
</html>
|