diff options
Diffstat (limited to 'devdocs/python~3.12/library%2Femail.mime.html')
| -rw-r--r-- | devdocs/python~3.12/library%2Femail.mime.html | 30 |
1 files changed, 30 insertions, 0 deletions
diff --git a/devdocs/python~3.12/library%2Femail.mime.html b/devdocs/python~3.12/library%2Femail.mime.html new file mode 100644 index 00000000..404f9607 --- /dev/null +++ b/devdocs/python~3.12/library%2Femail.mime.html @@ -0,0 +1,30 @@ + <span id="email-mime-creating-email-and-mime-objects-from-scratch"></span><h1>email.mime: Creating email and MIME objects from scratch</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/email/mime/">Lib/email/mime/</a></p> <p>This module is part of the legacy (<code>Compat32</code>) email API. Its functionality is partially replaced by the <a class="reference internal" href="email.contentmanager#module-email.contentmanager" title="email.contentmanager: Storing and Retrieving Content from MIME Parts"><code>contentmanager</code></a> in the new API, but in certain applications these classes may still be useful, even in non-legacy code.</p> <p>Ordinarily, you get a message object structure by passing a file or some text to a parser, which parses the text and returns the root message object. However you can also build a complete message structure from scratch, or even individual <a class="reference internal" href="email.compat32-message#email.message.Message" title="email.message.Message"><code>Message</code></a> objects by hand. In fact, you can also take an existing structure and add new <a class="reference internal" href="email.compat32-message#email.message.Message" title="email.message.Message"><code>Message</code></a> objects, move them around, etc. This makes a very convenient interface for slicing-and-dicing MIME messages.</p> <p>You can create a new object structure by creating <a class="reference internal" href="email.compat32-message#email.message.Message" title="email.message.Message"><code>Message</code></a> instances, adding attachments and all the appropriate headers manually. For MIME messages though, the <a class="reference internal" href="email#module-email" title="email: Package supporting the parsing, manipulating, and generating email messages."><code>email</code></a> package provides some convenient subclasses to make things easier.</p> <p>Here are the classes:</p> <dl class="py class"> <dt class="sig sig-object py" id="email.mime.base.MIMEBase"> +<code>class email.mime.base.MIMEBase(_maintype, _subtype, *, policy=compat32, **_params)</code> </dt> <dd> +<p>Module: <code>email.mime.base</code></p> <p>This is the base class for all the MIME-specific subclasses of <a class="reference internal" href="email.compat32-message#email.message.Message" title="email.message.Message"><code>Message</code></a>. Ordinarily you won’t create instances specifically of <a class="reference internal" href="#email.mime.base.MIMEBase" title="email.mime.base.MIMEBase"><code>MIMEBase</code></a>, although you could. <a class="reference internal" href="#email.mime.base.MIMEBase" title="email.mime.base.MIMEBase"><code>MIMEBase</code></a> is provided primarily as a convenient base class for more specific MIME-aware subclasses.</p> <p><em>_maintype</em> is the <em class="mailheader">Content-Type</em> major type (e.g. <em class="mimetype">text</em> or <em class="mimetype">image</em>), and <em>_subtype</em> is the <em class="mailheader">Content-Type</em> minor type (e.g. <em class="mimetype">plain</em> or <em class="mimetype">gif</em>). <em>_params</em> is a parameter key/value dictionary and is passed directly to <a class="reference internal" href="email.compat32-message#email.message.Message.add_header" title="email.message.Message.add_header"><code>Message.add_header</code></a>.</p> <p>If <em>policy</em> is specified, (defaults to the <a class="reference internal" href="email.policy#email.policy.Compat32" title="email.policy.Compat32"><code>compat32</code></a> policy) it will be passed to <a class="reference internal" href="email.compat32-message#email.message.Message" title="email.message.Message"><code>Message</code></a>.</p> <p>The <a class="reference internal" href="#email.mime.base.MIMEBase" title="email.mime.base.MIMEBase"><code>MIMEBase</code></a> class always adds a <em class="mailheader">Content-Type</em> header (based on <em>_maintype</em>, <em>_subtype</em>, and <em>_params</em>), and a <em class="mailheader">MIME-Version</em> header (always set to <code>1.0</code>).</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.6: </span>Added <em>policy</em> keyword-only parameter.</p> </div> </dd> +</dl> <dl class="py class"> <dt class="sig sig-object py" id="email.mime.nonmultipart.MIMENonMultipart"> +<code>class email.mime.nonmultipart.MIMENonMultipart</code> </dt> <dd> +<p>Module: <code>email.mime.nonmultipart</code></p> <p>A subclass of <a class="reference internal" href="#email.mime.base.MIMEBase" title="email.mime.base.MIMEBase"><code>MIMEBase</code></a>, this is an intermediate base class for MIME messages that are not <em class="mimetype">multipart</em>. The primary purpose of this class is to prevent the use of the <a class="reference internal" href="email.compat32-message#email.message.Message.attach" title="email.message.Message.attach"><code>attach()</code></a> method, which only makes sense for <em class="mimetype">multipart</em> messages. If <a class="reference internal" href="email.compat32-message#email.message.Message.attach" title="email.message.Message.attach"><code>attach()</code></a> is called, a <a class="reference internal" href="email.errors#email.errors.MultipartConversionError" title="email.errors.MultipartConversionError"><code>MultipartConversionError</code></a> exception is raised.</p> </dd> +</dl> <dl class="py class"> <dt class="sig sig-object py" id="email.mime.multipart.MIMEMultipart"> +<code>class email.mime.multipart.MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, *, policy=compat32, **_params)</code> </dt> <dd> +<p>Module: <code>email.mime.multipart</code></p> <p>A subclass of <a class="reference internal" href="#email.mime.base.MIMEBase" title="email.mime.base.MIMEBase"><code>MIMEBase</code></a>, this is an intermediate base class for MIME messages that are <em class="mimetype">multipart</em>. Optional <em>_subtype</em> defaults to <em class="mimetype">mixed</em>, but can be used to specify the subtype of the message. A <em class="mailheader">Content-Type</em> header of <em class="mimetype">multipart/_subtype</em> will be added to the message object. A <em class="mailheader">MIME-Version</em> header will also be added.</p> <p>Optional <em>boundary</em> is the multipart boundary string. When <code>None</code> (the default), the boundary is calculated when needed (for example, when the message is serialized).</p> <p><em>_subparts</em> is a sequence of initial subparts for the payload. It must be possible to convert this sequence to a list. You can always attach new subparts to the message by using the <a class="reference internal" href="email.compat32-message#email.message.Message.attach" title="email.message.Message.attach"><code>Message.attach</code></a> method.</p> <p>Optional <em>policy</em> argument defaults to <a class="reference internal" href="email.policy#email.policy.Compat32" title="email.policy.Compat32"><code>compat32</code></a>.</p> <p>Additional parameters for the <em class="mailheader">Content-Type</em> header are taken from the keyword arguments, or passed into the <em>_params</em> argument, which is a keyword dictionary.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.6: </span>Added <em>policy</em> keyword-only parameter.</p> </div> </dd> +</dl> <dl class="py class"> <dt class="sig sig-object py" id="email.mime.application.MIMEApplication"> +<code>class email.mime.application.MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)</code> </dt> <dd> +<p>Module: <code>email.mime.application</code></p> <p>A subclass of <a class="reference internal" href="#email.mime.nonmultipart.MIMENonMultipart" title="email.mime.nonmultipart.MIMENonMultipart"><code>MIMENonMultipart</code></a>, the <a class="reference internal" href="#email.mime.application.MIMEApplication" title="email.mime.application.MIMEApplication"><code>MIMEApplication</code></a> class is used to represent MIME message objects of major type <em class="mimetype">application</em>. <em>_data</em> contains the bytes for the raw application data. Optional <em>_subtype</em> specifies the MIME subtype and defaults to <em class="mimetype">octet-stream</em>.</p> <p>Optional <em>_encoder</em> is a callable (i.e. function) which will perform the actual encoding of the data for transport. This callable takes one argument, which is the <a class="reference internal" href="#email.mime.application.MIMEApplication" title="email.mime.application.MIMEApplication"><code>MIMEApplication</code></a> instance. It should use <a class="reference internal" href="email.compat32-message#email.message.Message.get_payload" title="email.message.Message.get_payload"><code>get_payload()</code></a> and <a class="reference internal" href="email.compat32-message#email.message.Message.set_payload" title="email.message.Message.set_payload"><code>set_payload()</code></a> to change the payload to encoded form. It should also add any <em class="mailheader">Content-Transfer-Encoding</em> or other headers to the message object as necessary. The default encoding is base64. See the <a class="reference internal" href="email.encoders#module-email.encoders" title="email.encoders: Encoders for email message payloads."><code>email.encoders</code></a> module for a list of the built-in encoders.</p> <p>Optional <em>policy</em> argument defaults to <a class="reference internal" href="email.policy#email.policy.Compat32" title="email.policy.Compat32"><code>compat32</code></a>.</p> <p><em>_params</em> are passed straight through to the base class constructor.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.6: </span>Added <em>policy</em> keyword-only parameter.</p> </div> </dd> +</dl> <dl class="py class"> <dt class="sig sig-object py" id="email.mime.audio.MIMEAudio"> +<code>class email.mime.audio.MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)</code> </dt> <dd> +<p>Module: <code>email.mime.audio</code></p> <p>A subclass of <a class="reference internal" href="#email.mime.nonmultipart.MIMENonMultipart" title="email.mime.nonmultipart.MIMENonMultipart"><code>MIMENonMultipart</code></a>, the <a class="reference internal" href="#email.mime.audio.MIMEAudio" title="email.mime.audio.MIMEAudio"><code>MIMEAudio</code></a> class is used to create MIME message objects of major type <em class="mimetype">audio</em>. <em>_audiodata</em> contains the bytes for the raw audio data. If this data can be decoded as au, wav, aiff, or aifc, then the subtype will be automatically included in the <em class="mailheader">Content-Type</em> header. Otherwise you can explicitly specify the audio subtype via the <em>_subtype</em> argument. If the minor type could not be guessed and <em>_subtype</em> was not given, then <a class="reference internal" href="exceptions#TypeError" title="TypeError"><code>TypeError</code></a> is raised.</p> <p>Optional <em>_encoder</em> is a callable (i.e. function) which will perform the actual encoding of the audio data for transport. This callable takes one argument, which is the <a class="reference internal" href="#email.mime.audio.MIMEAudio" title="email.mime.audio.MIMEAudio"><code>MIMEAudio</code></a> instance. It should use <a class="reference internal" href="email.compat32-message#email.message.Message.get_payload" title="email.message.Message.get_payload"><code>get_payload()</code></a> and <a class="reference internal" href="email.compat32-message#email.message.Message.set_payload" title="email.message.Message.set_payload"><code>set_payload()</code></a> to change the payload to encoded form. It should also add any <em class="mailheader">Content-Transfer-Encoding</em> or other headers to the message object as necessary. The default encoding is base64. See the <a class="reference internal" href="email.encoders#module-email.encoders" title="email.encoders: Encoders for email message payloads."><code>email.encoders</code></a> module for a list of the built-in encoders.</p> <p>Optional <em>policy</em> argument defaults to <a class="reference internal" href="email.policy#email.policy.Compat32" title="email.policy.Compat32"><code>compat32</code></a>.</p> <p><em>_params</em> are passed straight through to the base class constructor.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.6: </span>Added <em>policy</em> keyword-only parameter.</p> </div> </dd> +</dl> <dl class="py class"> <dt class="sig sig-object py" id="email.mime.image.MIMEImage"> +<code>class email.mime.image.MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)</code> </dt> <dd> +<p>Module: <code>email.mime.image</code></p> <p>A subclass of <a class="reference internal" href="#email.mime.nonmultipart.MIMENonMultipart" title="email.mime.nonmultipart.MIMENonMultipart"><code>MIMENonMultipart</code></a>, the <a class="reference internal" href="#email.mime.image.MIMEImage" title="email.mime.image.MIMEImage"><code>MIMEImage</code></a> class is used to create MIME message objects of major type <em class="mimetype">image</em>. <em>_imagedata</em> contains the bytes for the raw image data. If this data type can be detected (jpeg, png, gif, tiff, rgb, pbm, pgm, ppm, rast, xbm, bmp, webp, and exr attempted), then the subtype will be automatically included in the <em class="mailheader">Content-Type</em> header. Otherwise you can explicitly specify the image subtype via the <em>_subtype</em> argument. If the minor type could not be guessed and <em>_subtype</em> was not given, then <a class="reference internal" href="exceptions#TypeError" title="TypeError"><code>TypeError</code></a> is raised.</p> <p>Optional <em>_encoder</em> is a callable (i.e. function) which will perform the actual encoding of the image data for transport. This callable takes one argument, which is the <a class="reference internal" href="#email.mime.image.MIMEImage" title="email.mime.image.MIMEImage"><code>MIMEImage</code></a> instance. It should use <a class="reference internal" href="email.compat32-message#email.message.Message.get_payload" title="email.message.Message.get_payload"><code>get_payload()</code></a> and <a class="reference internal" href="email.compat32-message#email.message.Message.set_payload" title="email.message.Message.set_payload"><code>set_payload()</code></a> to change the payload to encoded form. It should also add any <em class="mailheader">Content-Transfer-Encoding</em> or other headers to the message object as necessary. The default encoding is base64. See the <a class="reference internal" href="email.encoders#module-email.encoders" title="email.encoders: Encoders for email message payloads."><code>email.encoders</code></a> module for a list of the built-in encoders.</p> <p>Optional <em>policy</em> argument defaults to <a class="reference internal" href="email.policy#email.policy.Compat32" title="email.policy.Compat32"><code>compat32</code></a>.</p> <p><em>_params</em> are passed straight through to the <a class="reference internal" href="#email.mime.base.MIMEBase" title="email.mime.base.MIMEBase"><code>MIMEBase</code></a> constructor.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.6: </span>Added <em>policy</em> keyword-only parameter.</p> </div> </dd> +</dl> <dl class="py class"> <dt class="sig sig-object py" id="email.mime.message.MIMEMessage"> +<code>class email.mime.message.MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32)</code> </dt> <dd> +<p>Module: <code>email.mime.message</code></p> <p>A subclass of <a class="reference internal" href="#email.mime.nonmultipart.MIMENonMultipart" title="email.mime.nonmultipart.MIMENonMultipart"><code>MIMENonMultipart</code></a>, the <a class="reference internal" href="#email.mime.message.MIMEMessage" title="email.mime.message.MIMEMessage"><code>MIMEMessage</code></a> class is used to create MIME objects of main type <em class="mimetype">message</em>. <em>_msg</em> is used as the payload, and must be an instance of class <a class="reference internal" href="email.compat32-message#email.message.Message" title="email.message.Message"><code>Message</code></a> (or a subclass thereof), otherwise a <a class="reference internal" href="exceptions#TypeError" title="TypeError"><code>TypeError</code></a> is raised.</p> <p>Optional <em>_subtype</em> sets the subtype of the message; it defaults to <em class="mimetype">rfc822</em>.</p> <p>Optional <em>policy</em> argument defaults to <a class="reference internal" href="email.policy#email.policy.Compat32" title="email.policy.Compat32"><code>compat32</code></a>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.6: </span>Added <em>policy</em> keyword-only parameter.</p> </div> </dd> +</dl> <dl class="py class"> <dt class="sig sig-object py" id="email.mime.text.MIMEText"> +<code>class email.mime.text.MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32)</code> </dt> <dd> +<p>Module: <code>email.mime.text</code></p> <p>A subclass of <a class="reference internal" href="#email.mime.nonmultipart.MIMENonMultipart" title="email.mime.nonmultipart.MIMENonMultipart"><code>MIMENonMultipart</code></a>, the <a class="reference internal" href="#email.mime.text.MIMEText" title="email.mime.text.MIMEText"><code>MIMEText</code></a> class is used to create MIME objects of major type <em class="mimetype">text</em>. <em>_text</em> is the string for the payload. <em>_subtype</em> is the minor type and defaults to <em class="mimetype">plain</em>. <em>_charset</em> is the character set of the text and is passed as an argument to the <a class="reference internal" href="#email.mime.nonmultipart.MIMENonMultipart" title="email.mime.nonmultipart.MIMENonMultipart"><code>MIMENonMultipart</code></a> constructor; it defaults to <code>us-ascii</code> if the string contains only <code>ascii</code> code points, and <code>utf-8</code> otherwise. The <em>_charset</em> parameter accepts either a string or a <a class="reference internal" href="email.charset#email.charset.Charset" title="email.charset.Charset"><code>Charset</code></a> instance.</p> <p>Unless the <em>_charset</em> argument is explicitly set to <code>None</code>, the MIMEText object created will have both a <em class="mailheader">Content-Type</em> header with a <code>charset</code> parameter, and a <em class="mailheader">Content-Transfer-Encoding</em> header. This means that a subsequent <code>set_payload</code> call will not result in an encoded payload, even if a charset is passed in the <code>set_payload</code> command. You can “reset” this behavior by deleting the <code>Content-Transfer-Encoding</code> header, after which a <code>set_payload</code> call will automatically encode the new payload (and add a new <em class="mailheader">Content-Transfer-Encoding</em> header).</p> <p>Optional <em>policy</em> argument defaults to <a class="reference internal" href="email.policy#email.policy.Compat32" title="email.policy.Compat32"><code>compat32</code></a>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span><em>_charset</em> also accepts <a class="reference internal" href="email.charset#email.charset.Charset" title="email.charset.Charset"><code>Charset</code></a> instances.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.6: </span>Added <em>policy</em> keyword-only parameter.</p> </div> </dd> +</dl> <div class="_attribution"> + <p class="_attribution-p"> + © 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br> + <a href="https://docs.python.org/3.12/library/email.mime.html" class="_attribution-link">https://docs.python.org/3.12/library/email.mime.html</a> + </p> +</div> |