path: root/devdocs/python~3.12/library%2Femail.contentmanager.html

 <span id="email-contentmanager-managing-mime-content"></span><h1>email.contentmanager: Managing MIME Content</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/email/contentmanager.py">Lib/email/contentmanager.py</a></p>  <div class="versionadded"> <p><span class="versionmodified added">New in version 3.6: </span><a class="footnote-reference brackets" href="#id2" id="id1">1</a></p> </div> <dl class="py class"> <dt class="sig sig-object py" id="email.contentmanager.ContentManager">
<code>class email.contentmanager.ContentManager</code> </dt> <dd>
<p>Base class for content managers. Provides the standard registry mechanisms to register converters between MIME content and other representations, as well as the <code>get_content</code> and <code>set_content</code> dispatch methods.</p> <dl class="py method"> <dt class="sig sig-object py" id="email.contentmanager.ContentManager.get_content">
<code>get_content(msg, *args, **kw)</code> </dt> <dd>
<p>Look up a handler function based on the <code>mimetype</code> of <em>msg</em> (see next paragraph), call it, passing through all arguments, and return the result of the call. The expectation is that the handler will extract the payload from <em>msg</em> and return an object that encodes information about the extracted data.</p> <p>To find the handler, look for the following keys in the registry, stopping with the first one found:</p> <ul class="simple"> <li>the string representing the full MIME type (<code>maintype/subtype</code>)</li> <li>the string representing the <code>maintype</code>
</li> <li>the empty string</li> </ul> <p>If none of these keys produce a handler, raise a <a class="reference internal" href="exceptions#KeyError" title="KeyError"><code>KeyError</code></a> for the full MIME type.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="email.contentmanager.ContentManager.set_content">
<code>set_content(msg, obj, *args, **kw)</code> </dt> <dd>
<p>If the <code>maintype</code> is <code>multipart</code>, raise a <a class="reference internal" href="exceptions#TypeError" title="TypeError"><code>TypeError</code></a>; otherwise look up a handler function based on the type of <em>obj</em> (see next paragraph), call <a class="reference internal" href="email.message#email.message.EmailMessage.clear_content" title="email.message.EmailMessage.clear_content"><code>clear_content()</code></a> on the <em>msg</em>, and call the handler function, passing through all arguments. The expectation is that the handler will transform and store <em>obj</em> into <em>msg</em>, possibly making other changes to <em>msg</em> as well, such as adding various MIME headers to encode information needed to interpret the stored data.</p> <p>To find the handler, obtain the type of <em>obj</em> (<code>typ = type(obj)</code>), and look for the following keys in the registry, stopping with the first one found:</p> <ul class="simple"> <li>the type itself (<code>typ</code>)</li> <li>the type’s fully qualified name (<code>typ.__module__ + '.' +
typ.__qualname__</code>).</li> <li>the type’s qualname (<code>typ.__qualname__</code>)</li> <li>the type’s name (<code>typ.__name__</code>).</li> </ul> <p>If none of the above match, repeat all of the checks above for each of the types in the <a class="reference internal" href="../glossary#term-MRO"><span class="xref std std-term">MRO</span></a> (<code>typ.__mro__</code>). Finally, if no other key yields a handler, check for a handler for the key <code>None</code>. If there is no handler for <code>None</code>, raise a <a class="reference internal" href="exceptions#KeyError" title="KeyError"><code>KeyError</code></a> for the fully qualified name of the type.</p> <p>Also add a <em class="mailheader">MIME-Version</em> header if one is not present (see also <a class="reference internal" href="email.message#email.message.MIMEPart" title="email.message.MIMEPart"><code>MIMEPart</code></a>).</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="email.contentmanager.ContentManager.add_get_handler">
<code>add_get_handler(key, handler)</code> </dt> <dd>
<p>Record the function <em>handler</em> as the handler for <em>key</em>. For the possible values of <em>key</em>, see <a class="reference internal" href="#email.contentmanager.get_content" title="email.contentmanager.get_content"><code>get_content()</code></a>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="email.contentmanager.ContentManager.add_set_handler">
<code>add_set_handler(typekey, handler)</code> </dt> <dd>
<p>Record <em>handler</em> as the function to call when an object of a type matching <em>typekey</em> is passed to <a class="reference internal" href="#email.contentmanager.set_content" title="email.contentmanager.set_content"><code>set_content()</code></a>. For the possible values of <em>typekey</em>, see <a class="reference internal" href="#email.contentmanager.set_content" title="email.contentmanager.set_content"><code>set_content()</code></a>.</p> </dd>
</dl> </dd>
</dl> <section id="content-manager-instances"> <h2>Content Manager Instances</h2> <p>Currently the email package provides only one concrete content manager, <a class="reference internal" href="#email.contentmanager.raw_data_manager" title="email.contentmanager.raw_data_manager"><code>raw_data_manager</code></a>, although more may be added in the future. <a class="reference internal" href="#email.contentmanager.raw_data_manager" title="email.contentmanager.raw_data_manager"><code>raw_data_manager</code></a> is the <a class="reference internal" href="email.policy#email.policy.EmailPolicy.content_manager" title="email.policy.EmailPolicy.content_manager"><code>content_manager</code></a> provided by <a class="reference internal" href="email.policy#email.policy.EmailPolicy" title="email.policy.EmailPolicy"><code>EmailPolicy</code></a> and its derivatives.</p> <dl class="py data"> <dt class="sig sig-object py" id="email.contentmanager.raw_data_manager">
<code>email.contentmanager.raw_data_manager</code> </dt> <dd>
<p>This content manager provides only a minimum interface beyond that provided by <a class="reference internal" href="email.compat32-message#email.message.Message" title="email.message.Message"><code>Message</code></a> itself: it deals only with text, raw byte strings, and <a class="reference internal" href="email.compat32-message#email.message.Message" title="email.message.Message"><code>Message</code></a> objects. Nevertheless, it provides significant advantages compared to the base API: <code>get_content</code> on a text part will return a unicode string without the application needing to manually decode it, <code>set_content</code> provides a rich set of options for controlling the headers added to a part and controlling the content transfer encoding, and it enables the use of the various <code>add_</code> methods, thereby simplifying the creation of multipart messages.</p> <dl class="py method"> <dt class="sig sig-object py" id="email.contentmanager.get_content">
<code>email.contentmanager.get_content(msg, errors='replace')</code> </dt> <dd>
<p>Return the payload of the part as either a string (for <code>text</code> parts), an <a class="reference internal" href="email.message#email.message.EmailMessage" title="email.message.EmailMessage"><code>EmailMessage</code></a> object (for <code>message/rfc822</code> parts), or a <code>bytes</code> object (for all other non-multipart types). Raise a <a class="reference internal" href="exceptions#KeyError" title="KeyError"><code>KeyError</code></a> if called on a <code>multipart</code>. If the part is a <code>text</code> part and <em>errors</em> is specified, use it as the error handler when decoding the payload to unicode. The default error handler is <code>replace</code>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="email.contentmanager.set_content">
<code>email.contentmanager.set_content(msg, &lt;'str'&gt;, subtype="plain", charset='utf-8', cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)</code> </dt> <dt class="sig sig-object py"> <span class="sig-prename descclassname">email.contentmanager.</span><span class="sig-name descname">set_content</span><span class="sig-paren">(</span><em class="sig-param"><span class="n">msg</span></em>, <em class="sig-param"><span class="n">&lt;'bytes'&gt;</span></em>, <em class="sig-param"><span class="n">maintype</span></em>, <em class="sig-param"><span class="n">subtype</span></em>, <em class="sig-param"><span class="n">cte="base64"</span></em>, <em class="sig-param"><span class="n">disposition=None</span></em>, <em class="sig-param"><span class="n">filename=None</span></em>, <em class="sig-param"><span class="n">cid=None</span></em>, <em class="sig-param"><span class="n">params=None</span></em>, <em class="sig-param"><span class="n">headers=None</span></em><span class="sig-paren">)</span>
</dt> <dt class="sig sig-object py"> <span class="sig-prename descclassname">email.contentmanager.</span><span class="sig-name descname">set_content</span><span class="sig-paren">(</span><em class="sig-param"><span class="n">msg</span></em>, <em class="sig-param"><span class="n">&lt;'EmailMessage'&gt;</span></em>, <em class="sig-param"><span class="n">cte=None</span></em>, <em class="sig-param"><span class="n">disposition=None</span></em>, <em class="sig-param"><span class="n">filename=None</span></em>, <em class="sig-param"><span class="n">cid=None</span></em>, <em class="sig-param"><span class="n">params=None</span></em>, <em class="sig-param"><span class="n">headers=None</span></em><span class="sig-paren">)</span>
</dt> <dd>
<p>Add headers and payload to <em>msg</em>:</p> <p>Add a <em class="mailheader">Content-Type</em> header with a <code>maintype/subtype</code> value.</p> <ul class="simple"> <li>For <code>str</code>, set the MIME <code>maintype</code> to <code>text</code>, and set the subtype to <em>subtype</em> if it is specified, or <code>plain</code> if it is not.</li> <li>For <code>bytes</code>, use the specified <em>maintype</em> and <em>subtype</em>, or raise a <a class="reference internal" href="exceptions#TypeError" title="TypeError"><code>TypeError</code></a> if they are not specified.</li> <li>For <a class="reference internal" href="email.message#email.message.EmailMessage" title="email.message.EmailMessage"><code>EmailMessage</code></a> objects, set the maintype to <code>message</code>, and set the subtype to <em>subtype</em> if it is specified or <code>rfc822</code> if it is not. If <em>subtype</em> is <code>partial</code>, raise an error (<code>bytes</code> objects must be used to construct <code>message/partial</code> parts).</li> </ul> <p>If <em>charset</em> is provided (which is valid only for <code>str</code>), encode the string to bytes using the specified character set. The default is <code>utf-8</code>. If the specified <em>charset</em> is a known alias for a standard MIME charset name, use the standard charset instead.</p> <p>If <em>cte</em> is set, encode the payload using the specified content transfer encoding, and set the <em class="mailheader">Content-Transfer-Encoding</em> header to that value. Possible values for <em>cte</em> are <code>quoted-printable</code>, <code>base64</code>, <code>7bit</code>, <code>8bit</code>, and <code>binary</code>. If the input cannot be encoded in the specified encoding (for example, specifying a <em>cte</em> of <code>7bit</code> for an input that contains non-ASCII values), raise a <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a>.</p> <ul class="simple"> <li>For <code>str</code> objects, if <em>cte</em> is not set use heuristics to determine the most compact encoding.</li> <li>For <a class="reference internal" href="email.message#email.message.EmailMessage" title="email.message.EmailMessage"><code>EmailMessage</code></a>, per <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2046.html"><strong>RFC 2046</strong></a>, raise an error if a <em>cte</em> of <code>quoted-printable</code> or <code>base64</code> is requested for <em>subtype</em> <code>rfc822</code>, and for any <em>cte</em> other than <code>7bit</code> for <em>subtype</em> <code>external-body</code>. For <code>message/rfc822</code>, use <code>8bit</code> if <em>cte</em> is not specified. For all other values of <em>subtype</em>, use <code>7bit</code>.</li> </ul> <div class="admonition note"> <p class="admonition-title">Note</p> <p>A <em>cte</em> of <code>binary</code> does not actually work correctly yet. The <code>EmailMessage</code> object as modified by <code>set_content</code> is correct, but <a class="reference internal" href="email.generator#email.generator.BytesGenerator" title="email.generator.BytesGenerator"><code>BytesGenerator</code></a> does not serialize it correctly.</p> </div> <p>If <em>disposition</em> is set, use it as the value of the <em class="mailheader">Content-Disposition</em> header. If not specified, and <em>filename</em> is specified, add the header with the value <code>attachment</code>. If <em>disposition</em> is not specified and <em>filename</em> is also not specified, do not add the header. The only valid values for <em>disposition</em> are <code>attachment</code> and <code>inline</code>.</p> <p>If <em>filename</em> is specified, use it as the value of the <code>filename</code> parameter of the <em class="mailheader">Content-Disposition</em> header.</p> <p>If <em>cid</em> is specified, add a <em class="mailheader">Content-ID</em> header with <em>cid</em> as its value.</p> <p>If <em>params</em> is specified, iterate its <code>items</code> method and use the resulting <code>(key, value)</code> pairs to set additional parameters on the <em class="mailheader">Content-Type</em> header.</p> <p>If <em>headers</em> is specified and is a list of strings of the form <code>headername: headervalue</code> or a list of <code>header</code> objects (distinguished from strings by having a <code>name</code> attribute), add the headers to <em>msg</em>.</p> </dd>
</dl> </dd>
</dl> <h4 class="rubric">Footnotes</h4> <dl class="footnote brackets"> <dt class="label" id="id2">
<code>1</code> </dt> <dd>
<p>Originally added in 3.4 as a <a class="reference internal" href="../glossary#term-provisional-package"><span class="xref std std-term">provisional module</span></a></p> </dd> </dl> </section> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/library/email.contentmanager.html" class="_attribution-link">https://docs.python.org/3.12/library/email.contentmanager.html</a>
  </p>
</div>