mirror of
https://github.com/python/cpython.git
synced 2025-07-24 11:44:31 +00:00
29d1bc0842
This is a wholesale reorganization and editing of the email documentation to make the new API the standard one, and the old API the 'legacy' one. The default is still the compat32 policy, for backward compatibility. We will change that eventually.
259 lines
11 KiB
ReStructuredText
259 lines
11 KiB
ReStructuredText
:mod:`email.mime`: Creating email and MIME objects from scratch
|
|
---------------------------------------------------------------
|
|
|
|
.. module:: email.mime
|
|
:synopsis: Build MIME messages.
|
|
|
|
**Source code:** :source:`Lib/email/mime/`
|
|
|
|
--------------
|
|
|
|
This module is part of the legacy (``Compat32``) email API. Its functionality
|
|
is partially replaced by the :mod:`~email.contentmanager` in the new API, but
|
|
in certain applications these classes may still be useful, even in non-legacy
|
|
code.
|
|
|
|
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
|
|
:class:`~email.message.Message` objects by hand. In fact, you can also take an
|
|
existing structure and add new :class:`~email.message.Message` objects, move them
|
|
around, etc. This makes a very convenient interface for slicing-and-dicing MIME
|
|
messages.
|
|
|
|
You can create a new object structure by creating :class:`~email.message.Message`
|
|
instances, adding attachments and all the appropriate headers manually. For MIME
|
|
messages though, the :mod:`email` package provides some convenient subclasses to
|
|
make things easier.
|
|
|
|
Here are the classes:
|
|
|
|
.. currentmodule:: email.mime.base
|
|
|
|
.. class:: MIMEBase(_maintype, _subtype, *, policy=compat32, **_params)
|
|
|
|
Module: :mod:`email.mime.base`
|
|
|
|
This is the base class for all the MIME-specific subclasses of
|
|
:class:`~email.message.Message`. Ordinarily you won't create instances
|
|
specifically of :class:`MIMEBase`, although you could. :class:`MIMEBase`
|
|
is provided primarily as a convenient base class for more specific
|
|
MIME-aware subclasses.
|
|
|
|
*_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`
|
|
or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor
|
|
type (e.g. :mimetype:`plain` or :mimetype:`gif`). *_params* is a parameter
|
|
key/value dictionary and is passed directly to :meth:`Message.add_header
|
|
<email.message.Message.add_header>`.
|
|
|
|
If *policy* is specified, (defaults to the
|
|
:class:`compat32 <email.policy.Compat32>` policy) it will be passed to
|
|
:class:`~email.message.Message`.
|
|
|
|
The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header
|
|
(based on *_maintype*, *_subtype*, and *_params*), and a
|
|
:mailheader:`MIME-Version` header (always set to ``1.0``).
|
|
|
|
.. versionchanged:: 3.6
|
|
Added *policy* keyword-only parameter.
|
|
|
|
|
|
.. currentmodule:: email.mime.nonmultipart
|
|
|
|
.. class:: MIMENonMultipart()
|
|
|
|
Module: :mod:`email.mime.nonmultipart`
|
|
|
|
A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base
|
|
class for MIME messages that are not :mimetype:`multipart`. The primary
|
|
purpose of this class is to prevent the use of the
|
|
:meth:`~email.message.Message.attach` method, which only makes sense for
|
|
:mimetype:`multipart` messages. If :meth:`~email.message.Message.attach`
|
|
is called, a :exc:`~email.errors.MultipartConversionError` exception is raised.
|
|
|
|
|
|
.. currentmodule:: email.mime.multipart
|
|
|
|
.. class:: MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, \
|
|
*, policy=compat32, **_params)
|
|
|
|
Module: :mod:`email.mime.multipart`
|
|
|
|
A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base
|
|
class for MIME messages that are :mimetype:`multipart`. Optional *_subtype*
|
|
defaults to :mimetype:`mixed`, but can be used to specify the subtype of the
|
|
message. A :mailheader:`Content-Type` header of :mimetype:`multipart/_subtype`
|
|
will be added to the message object. A :mailheader:`MIME-Version` header will
|
|
also be added.
|
|
|
|
Optional *boundary* is the multipart boundary string. When ``None`` (the
|
|
default), the boundary is calculated when needed (for example, when the
|
|
message is serialized).
|
|
|
|
*_subparts* 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 :meth:`Message.attach
|
|
<email.message.Message.attach>` method.
|
|
|
|
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
|
|
|
|
Additional parameters for the :mailheader:`Content-Type` header are taken from
|
|
the keyword arguments, or passed into the *_params* argument, which is a keyword
|
|
dictionary.
|
|
|
|
.. versionchanged:: 3.6
|
|
Added *policy* keyword-only parameter.
|
|
|
|
.. currentmodule:: email.mime.application
|
|
|
|
.. class:: MIMEApplication(_data, _subtype='octet-stream', \
|
|
_encoder=email.encoders.encode_base64, \
|
|
*, policy=compat32, **_params)
|
|
|
|
Module: :mod:`email.mime.application`
|
|
|
|
A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
|
|
:class:`MIMEApplication` class is used to represent MIME message objects of
|
|
major type :mimetype:`application`. *_data* is a string containing the raw
|
|
byte data. Optional *_subtype* specifies the MIME subtype and defaults to
|
|
:mimetype:`octet-stream`.
|
|
|
|
Optional *_encoder* 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 :class:`MIMEApplication` instance. It should use
|
|
:meth:`~email.message.Message.get_payload` and
|
|
:meth:`~email.message.Message.set_payload` to change the payload to encoded
|
|
form. It should also add
|
|
any :mailheader:`Content-Transfer-Encoding` or other headers to the message
|
|
object as necessary. The default encoding is base64. See the
|
|
:mod:`email.encoders` module for a list of the built-in encoders.
|
|
|
|
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
|
|
|
|
*_params* are passed straight through to the base class constructor.
|
|
|
|
.. versionchanged:: 3.6
|
|
Added *policy* keyword-only parameter.
|
|
|
|
.. currentmodule:: email.mime.audio
|
|
|
|
.. class:: MIMEAudio(_audiodata, _subtype=None, \
|
|
_encoder=email.encoders.encode_base64, \
|
|
*, policy=compat32, **_params)
|
|
|
|
Module: :mod:`email.mime.audio`
|
|
|
|
A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
|
|
:class:`MIMEAudio` class is used to create MIME message objects of major type
|
|
:mimetype:`audio`. *_audiodata* is a string containing the raw audio data. If
|
|
this data can be decoded by the standard Python module :mod:`sndhdr`, then the
|
|
subtype will be automatically included in the :mailheader:`Content-Type` header.
|
|
Otherwise you can explicitly specify the audio subtype via the *_subtype*
|
|
argument. If the minor type could not be guessed and *_subtype* was not given,
|
|
then :exc:`TypeError` is raised.
|
|
|
|
Optional *_encoder* 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 :class:`MIMEAudio` instance. It should use
|
|
:meth:`~email.message.Message.get_payload` and
|
|
:meth:`~email.message.Message.set_payload` to change the payload to encoded
|
|
form. It should also add
|
|
any :mailheader:`Content-Transfer-Encoding` or other headers to the message
|
|
object as necessary. The default encoding is base64. See the
|
|
:mod:`email.encoders` module for a list of the built-in encoders.
|
|
|
|
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
|
|
|
|
*_params* are passed straight through to the base class constructor.
|
|
|
|
.. versionchanged:: 3.6
|
|
Added *policy* keyword-only parameter.
|
|
|
|
.. currentmodule:: email.mime.image
|
|
|
|
.. class:: MIMEImage(_imagedata, _subtype=None, \
|
|
_encoder=email.encoders.encode_base64, \
|
|
*, policy=compat32, **_params)
|
|
|
|
Module: :mod:`email.mime.image`
|
|
|
|
A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
|
|
:class:`MIMEImage` class is used to create MIME message objects of major type
|
|
:mimetype:`image`. *_imagedata* is a string containing the raw image data. If
|
|
this data can be decoded by the standard Python module :mod:`imghdr`, then the
|
|
subtype will be automatically included in the :mailheader:`Content-Type` header.
|
|
Otherwise you can explicitly specify the image subtype via the *_subtype*
|
|
argument. If the minor type could not be guessed and *_subtype* was not given,
|
|
then :exc:`TypeError` is raised.
|
|
|
|
Optional *_encoder* 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 :class:`MIMEImage` instance. It should use
|
|
:meth:`~email.message.Message.get_payload` and
|
|
:meth:`~email.message.Message.set_payload` to change the payload to encoded
|
|
form. It should also add
|
|
any :mailheader:`Content-Transfer-Encoding` or other headers to the message
|
|
object as necessary. The default encoding is base64. See the
|
|
:mod:`email.encoders` module for a list of the built-in encoders.
|
|
|
|
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
|
|
|
|
*_params* are passed straight through to the :class:`~email.mime.base.MIMEBase`
|
|
constructor.
|
|
|
|
.. versionchanged:: 3.6
|
|
Added *policy* keyword-only parameter.
|
|
|
|
.. currentmodule:: email.mime.message
|
|
|
|
.. class:: MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32)
|
|
|
|
Module: :mod:`email.mime.message`
|
|
|
|
A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
|
|
:class:`MIMEMessage` class is used to create MIME objects of main type
|
|
:mimetype:`message`. *_msg* is used as the payload, and must be an instance
|
|
of class :class:`~email.message.Message` (or a subclass thereof), otherwise
|
|
a :exc:`TypeError` is raised.
|
|
|
|
Optional *_subtype* sets the subtype of the message; it defaults to
|
|
:mimetype:`rfc822`.
|
|
|
|
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
|
|
|
|
.. versionchanged:: 3.6
|
|
Added *policy* keyword-only parameter.
|
|
|
|
.. currentmodule:: email.mime.text
|
|
|
|
.. class:: MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32)
|
|
|
|
Module: :mod:`email.mime.text`
|
|
|
|
A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
|
|
:class:`MIMEText` class is used to create MIME objects of major type
|
|
:mimetype:`text`. *_text* is the string for the payload. *_subtype* is the
|
|
minor type and defaults to :mimetype:`plain`. *_charset* is the character
|
|
set of the text and is passed as an argument to the
|
|
:class:`~email.mime.nonmultipart.MIMENonMultipart` constructor; it defaults
|
|
to ``us-ascii`` if the string contains only ``ascii`` code points, and
|
|
``utf-8`` otherwise. The *_charset* parameter accepts either a string or a
|
|
:class:`~email.charset.Charset` instance.
|
|
|
|
Unless the *_charset* argument is explicitly set to ``None``, the
|
|
MIMEText object created will have both a :mailheader:`Content-Type` header
|
|
with a ``charset`` parameter, and a :mailheader:`Content-Transfer-Endcoding`
|
|
header. This means that a subsequent ``set_payload`` call will not result
|
|
in an encoded payload, even if a charset is passed in the ``set_payload``
|
|
command. You can "reset" this behavior by deleting the
|
|
``Content-Transfer-Encoding`` header, after which a ``set_payload`` call
|
|
will automatically encode the new payload (and add a new
|
|
:mailheader:`Content-Transfer-Encoding` header).
|
|
|
|
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
|
|
|
|
.. versionchanged:: 3.5
|
|
*_charset* also accepts :class:`~email.charset.Charset` instances.
|
|
|
|
.. versionchanged:: 3.6
|
|
Added *policy* keyword-only parameter.
|