cpython/Doc/library/email.mime.rst

261 lines
12 KiB
ReStructuredText
Raw Normal View History

:mod:`email.mime`: Creating email and MIME objects from scratch
---------------------------------------------------------------
2007-08-15 11:28:22 -03:00
.. module:: email.mime
2009-01-03 17:18:54 -04:00
:synopsis: Build MIME messages.
2007-08-15 11:28:22 -03:00
**Source code:** :source:`Lib/email/mime/`
--------------
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
Here are the classes:
Merged revisions 68116-68119,68121,68123-68127 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r68116 | georg.brandl | 2009-01-01 05:46:51 -0600 (Thu, 01 Jan 2009) | 2 lines #4100: note that element children are not necessarily present on "start" events. ........ r68117 | georg.brandl | 2009-01-01 05:53:55 -0600 (Thu, 01 Jan 2009) | 2 lines #4156: make clear that "protocol" is to be replaced with the protocol name. ........ r68118 | georg.brandl | 2009-01-01 06:00:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4185: clarify escape behavior of replacement strings. ........ r68119 | georg.brandl | 2009-01-01 06:09:40 -0600 (Thu, 01 Jan 2009) | 3 lines #4222: document dis.findlabels() and dis.findlinestarts() and put them into dis.__all__. ........ r68121 | georg.brandl | 2009-01-01 06:43:33 -0600 (Thu, 01 Jan 2009) | 2 lines Point to types module in new module deprecation notice. ........ r68123 | georg.brandl | 2009-01-01 06:52:29 -0600 (Thu, 01 Jan 2009) | 2 lines #4784: ... on three counts ... ........ r68124 | georg.brandl | 2009-01-01 06:53:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4782: Fix markup error that hid load() and loads(). ........ r68125 | georg.brandl | 2009-01-01 07:02:09 -0600 (Thu, 01 Jan 2009) | 2 lines #4776: add data_files and package_dir arguments. ........ r68126 | georg.brandl | 2009-01-01 07:05:13 -0600 (Thu, 01 Jan 2009) | 2 lines Handlers are in the `logging.handlers` module. ........ r68127 | georg.brandl | 2009-01-01 07:14:49 -0600 (Thu, 01 Jan 2009) | 2 lines #4767: Use correct submodules for all MIME classes. ........
2009-01-01 11:05:06 -04:00
.. currentmodule:: email.mime.base
2007-08-15 11:28:22 -03:00
.. class:: MIMEBase(_maintype, _subtype, *, policy=compat32, **_params)
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
*_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>`.
2007-08-15 11:28:22 -03:00
If *policy* is specified, (defaults to the
:class:`compat32 <email.policy.Compat32>` policy) it will be passed to
:class:`~email.message.Message`.
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
Merged revisions 68116-68119,68121,68123-68127 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r68116 | georg.brandl | 2009-01-01 05:46:51 -0600 (Thu, 01 Jan 2009) | 2 lines #4100: note that element children are not necessarily present on "start" events. ........ r68117 | georg.brandl | 2009-01-01 05:53:55 -0600 (Thu, 01 Jan 2009) | 2 lines #4156: make clear that "protocol" is to be replaced with the protocol name. ........ r68118 | georg.brandl | 2009-01-01 06:00:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4185: clarify escape behavior of replacement strings. ........ r68119 | georg.brandl | 2009-01-01 06:09:40 -0600 (Thu, 01 Jan 2009) | 3 lines #4222: document dis.findlabels() and dis.findlinestarts() and put them into dis.__all__. ........ r68121 | georg.brandl | 2009-01-01 06:43:33 -0600 (Thu, 01 Jan 2009) | 2 lines Point to types module in new module deprecation notice. ........ r68123 | georg.brandl | 2009-01-01 06:52:29 -0600 (Thu, 01 Jan 2009) | 2 lines #4784: ... on three counts ... ........ r68124 | georg.brandl | 2009-01-01 06:53:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4782: Fix markup error that hid load() and loads(). ........ r68125 | georg.brandl | 2009-01-01 07:02:09 -0600 (Thu, 01 Jan 2009) | 2 lines #4776: add data_files and package_dir arguments. ........ r68126 | georg.brandl | 2009-01-01 07:05:13 -0600 (Thu, 01 Jan 2009) | 2 lines Handlers are in the `logging.handlers` module. ........ r68127 | georg.brandl | 2009-01-01 07:14:49 -0600 (Thu, 01 Jan 2009) | 2 lines #4767: Use correct submodules for all MIME classes. ........
2009-01-01 11:05:06 -04:00
.. currentmodule:: email.mime.nonmultipart
2007-08-15 11:28:22 -03:00
.. 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.
2007-08-15 11:28:22 -03:00
Merged revisions 68116-68119,68121,68123-68127 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r68116 | georg.brandl | 2009-01-01 05:46:51 -0600 (Thu, 01 Jan 2009) | 2 lines #4100: note that element children are not necessarily present on "start" events. ........ r68117 | georg.brandl | 2009-01-01 05:53:55 -0600 (Thu, 01 Jan 2009) | 2 lines #4156: make clear that "protocol" is to be replaced with the protocol name. ........ r68118 | georg.brandl | 2009-01-01 06:00:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4185: clarify escape behavior of replacement strings. ........ r68119 | georg.brandl | 2009-01-01 06:09:40 -0600 (Thu, 01 Jan 2009) | 3 lines #4222: document dis.findlabels() and dis.findlinestarts() and put them into dis.__all__. ........ r68121 | georg.brandl | 2009-01-01 06:43:33 -0600 (Thu, 01 Jan 2009) | 2 lines Point to types module in new module deprecation notice. ........ r68123 | georg.brandl | 2009-01-01 06:52:29 -0600 (Thu, 01 Jan 2009) | 2 lines #4784: ... on three counts ... ........ r68124 | georg.brandl | 2009-01-01 06:53:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4782: Fix markup error that hid load() and loads(). ........ r68125 | georg.brandl | 2009-01-01 07:02:09 -0600 (Thu, 01 Jan 2009) | 2 lines #4776: add data_files and package_dir arguments. ........ r68126 | georg.brandl | 2009-01-01 07:05:13 -0600 (Thu, 01 Jan 2009) | 2 lines Handlers are in the `logging.handlers` module. ........ r68127 | georg.brandl | 2009-01-01 07:14:49 -0600 (Thu, 01 Jan 2009) | 2 lines #4767: Use correct submodules for all MIME classes. ........
2009-01-01 11:05:06 -04:00
.. currentmodule:: email.mime.multipart
.. class:: MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, \
*, policy=compat32, **_params)
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
Optional *boundary* is the multipart boundary string. When ``None`` (the
default), the boundary is calculated when needed (for example, when the
message is serialized).
2007-08-15 11:28:22 -03:00
*_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.
2007-08-15 11:28:22 -03:00
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
Merged revisions 68116-68119,68121,68123-68127 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r68116 | georg.brandl | 2009-01-01 05:46:51 -0600 (Thu, 01 Jan 2009) | 2 lines #4100: note that element children are not necessarily present on "start" events. ........ r68117 | georg.brandl | 2009-01-01 05:53:55 -0600 (Thu, 01 Jan 2009) | 2 lines #4156: make clear that "protocol" is to be replaced with the protocol name. ........ r68118 | georg.brandl | 2009-01-01 06:00:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4185: clarify escape behavior of replacement strings. ........ r68119 | georg.brandl | 2009-01-01 06:09:40 -0600 (Thu, 01 Jan 2009) | 3 lines #4222: document dis.findlabels() and dis.findlinestarts() and put them into dis.__all__. ........ r68121 | georg.brandl | 2009-01-01 06:43:33 -0600 (Thu, 01 Jan 2009) | 2 lines Point to types module in new module deprecation notice. ........ r68123 | georg.brandl | 2009-01-01 06:52:29 -0600 (Thu, 01 Jan 2009) | 2 lines #4784: ... on three counts ... ........ r68124 | georg.brandl | 2009-01-01 06:53:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4782: Fix markup error that hid load() and loads(). ........ r68125 | georg.brandl | 2009-01-01 07:02:09 -0600 (Thu, 01 Jan 2009) | 2 lines #4776: add data_files and package_dir arguments. ........ r68126 | georg.brandl | 2009-01-01 07:05:13 -0600 (Thu, 01 Jan 2009) | 2 lines Handlers are in the `logging.handlers` module. ........ r68127 | georg.brandl | 2009-01-01 07:14:49 -0600 (Thu, 01 Jan 2009) | 2 lines #4767: Use correct submodules for all MIME classes. ........
2009-01-01 11:05:06 -04:00
.. currentmodule:: email.mime.application
.. class:: MIMEApplication(_data, _subtype='octet-stream', \
_encoder=email.encoders.encode_base64, \
*, policy=compat32, **_params)
2007-08-15 11:28:22 -03:00
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* contains the bytes for the raw
application data. Optional *_subtype* specifies the MIME subtype and defaults
to :mimetype:`octet-stream`.
2007-08-15 11:28:22 -03:00
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
2007-08-15 11:28:22 -03:00
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>`.
2007-08-15 11:28:22 -03:00
*_params* are passed straight through to the base class constructor.
.. versionchanged:: 3.6
Added *policy* keyword-only parameter.
2007-08-15 11:28:22 -03:00
Merged revisions 68116-68119,68121,68123-68127 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r68116 | georg.brandl | 2009-01-01 05:46:51 -0600 (Thu, 01 Jan 2009) | 2 lines #4100: note that element children are not necessarily present on "start" events. ........ r68117 | georg.brandl | 2009-01-01 05:53:55 -0600 (Thu, 01 Jan 2009) | 2 lines #4156: make clear that "protocol" is to be replaced with the protocol name. ........ r68118 | georg.brandl | 2009-01-01 06:00:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4185: clarify escape behavior of replacement strings. ........ r68119 | georg.brandl | 2009-01-01 06:09:40 -0600 (Thu, 01 Jan 2009) | 3 lines #4222: document dis.findlabels() and dis.findlinestarts() and put them into dis.__all__. ........ r68121 | georg.brandl | 2009-01-01 06:43:33 -0600 (Thu, 01 Jan 2009) | 2 lines Point to types module in new module deprecation notice. ........ r68123 | georg.brandl | 2009-01-01 06:52:29 -0600 (Thu, 01 Jan 2009) | 2 lines #4784: ... on three counts ... ........ r68124 | georg.brandl | 2009-01-01 06:53:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4782: Fix markup error that hid load() and loads(). ........ r68125 | georg.brandl | 2009-01-01 07:02:09 -0600 (Thu, 01 Jan 2009) | 2 lines #4776: add data_files and package_dir arguments. ........ r68126 | georg.brandl | 2009-01-01 07:05:13 -0600 (Thu, 01 Jan 2009) | 2 lines Handlers are in the `logging.handlers` module. ........ r68127 | georg.brandl | 2009-01-01 07:14:49 -0600 (Thu, 01 Jan 2009) | 2 lines #4767: Use correct submodules for all MIME classes. ........
2009-01-01 11:05:06 -04:00
.. currentmodule:: email.mime.audio
.. class:: MIMEAudio(_audiodata, _subtype=None, \
_encoder=email.encoders.encode_base64, \
*, policy=compat32, **_params)
2007-08-15 11:28:22 -03:00
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* 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 :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.
2007-08-15 11:28:22 -03:00
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
2007-08-15 11:28:22 -03:00
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>`.
2007-08-15 11:28:22 -03:00
*_params* are passed straight through to the base class constructor.
.. versionchanged:: 3.6
Added *policy* keyword-only parameter.
2007-08-15 11:28:22 -03:00
Merged revisions 68116-68119,68121,68123-68127 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r68116 | georg.brandl | 2009-01-01 05:46:51 -0600 (Thu, 01 Jan 2009) | 2 lines #4100: note that element children are not necessarily present on "start" events. ........ r68117 | georg.brandl | 2009-01-01 05:53:55 -0600 (Thu, 01 Jan 2009) | 2 lines #4156: make clear that "protocol" is to be replaced with the protocol name. ........ r68118 | georg.brandl | 2009-01-01 06:00:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4185: clarify escape behavior of replacement strings. ........ r68119 | georg.brandl | 2009-01-01 06:09:40 -0600 (Thu, 01 Jan 2009) | 3 lines #4222: document dis.findlabels() and dis.findlinestarts() and put them into dis.__all__. ........ r68121 | georg.brandl | 2009-01-01 06:43:33 -0600 (Thu, 01 Jan 2009) | 2 lines Point to types module in new module deprecation notice. ........ r68123 | georg.brandl | 2009-01-01 06:52:29 -0600 (Thu, 01 Jan 2009) | 2 lines #4784: ... on three counts ... ........ r68124 | georg.brandl | 2009-01-01 06:53:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4782: Fix markup error that hid load() and loads(). ........ r68125 | georg.brandl | 2009-01-01 07:02:09 -0600 (Thu, 01 Jan 2009) | 2 lines #4776: add data_files and package_dir arguments. ........ r68126 | georg.brandl | 2009-01-01 07:05:13 -0600 (Thu, 01 Jan 2009) | 2 lines Handlers are in the `logging.handlers` module. ........ r68127 | georg.brandl | 2009-01-01 07:14:49 -0600 (Thu, 01 Jan 2009) | 2 lines #4767: Use correct submodules for all MIME classes. ........
2009-01-01 11:05:06 -04:00
.. currentmodule:: email.mime.image
.. class:: MIMEImage(_imagedata, _subtype=None, \
_encoder=email.encoders.encode_base64, \
*, policy=compat32, **_params)
2007-08-15 11:28:22 -03:00
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* 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 :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.
2007-08-15 11:28:22 -03:00
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
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
.. versionchanged:: 3.6
Added *policy* keyword-only parameter.
2007-08-15 11:28:22 -03:00
Merged revisions 68116-68119,68121,68123-68127 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r68116 | georg.brandl | 2009-01-01 05:46:51 -0600 (Thu, 01 Jan 2009) | 2 lines #4100: note that element children are not necessarily present on "start" events. ........ r68117 | georg.brandl | 2009-01-01 05:53:55 -0600 (Thu, 01 Jan 2009) | 2 lines #4156: make clear that "protocol" is to be replaced with the protocol name. ........ r68118 | georg.brandl | 2009-01-01 06:00:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4185: clarify escape behavior of replacement strings. ........ r68119 | georg.brandl | 2009-01-01 06:09:40 -0600 (Thu, 01 Jan 2009) | 3 lines #4222: document dis.findlabels() and dis.findlinestarts() and put them into dis.__all__. ........ r68121 | georg.brandl | 2009-01-01 06:43:33 -0600 (Thu, 01 Jan 2009) | 2 lines Point to types module in new module deprecation notice. ........ r68123 | georg.brandl | 2009-01-01 06:52:29 -0600 (Thu, 01 Jan 2009) | 2 lines #4784: ... on three counts ... ........ r68124 | georg.brandl | 2009-01-01 06:53:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4782: Fix markup error that hid load() and loads(). ........ r68125 | georg.brandl | 2009-01-01 07:02:09 -0600 (Thu, 01 Jan 2009) | 2 lines #4776: add data_files and package_dir arguments. ........ r68126 | georg.brandl | 2009-01-01 07:05:13 -0600 (Thu, 01 Jan 2009) | 2 lines Handlers are in the `logging.handlers` module. ........ r68127 | georg.brandl | 2009-01-01 07:14:49 -0600 (Thu, 01 Jan 2009) | 2 lines #4767: Use correct submodules for all MIME classes. ........
2009-01-01 11:05:06 -04:00
.. currentmodule:: email.mime.message
.. class:: MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32)
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
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.
2007-08-15 11:28:22 -03:00
Merged revisions 68116-68119,68121,68123-68127 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r68116 | georg.brandl | 2009-01-01 05:46:51 -0600 (Thu, 01 Jan 2009) | 2 lines #4100: note that element children are not necessarily present on "start" events. ........ r68117 | georg.brandl | 2009-01-01 05:53:55 -0600 (Thu, 01 Jan 2009) | 2 lines #4156: make clear that "protocol" is to be replaced with the protocol name. ........ r68118 | georg.brandl | 2009-01-01 06:00:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4185: clarify escape behavior of replacement strings. ........ r68119 | georg.brandl | 2009-01-01 06:09:40 -0600 (Thu, 01 Jan 2009) | 3 lines #4222: document dis.findlabels() and dis.findlinestarts() and put them into dis.__all__. ........ r68121 | georg.brandl | 2009-01-01 06:43:33 -0600 (Thu, 01 Jan 2009) | 2 lines Point to types module in new module deprecation notice. ........ r68123 | georg.brandl | 2009-01-01 06:52:29 -0600 (Thu, 01 Jan 2009) | 2 lines #4784: ... on three counts ... ........ r68124 | georg.brandl | 2009-01-01 06:53:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4782: Fix markup error that hid load() and loads(). ........ r68125 | georg.brandl | 2009-01-01 07:02:09 -0600 (Thu, 01 Jan 2009) | 2 lines #4776: add data_files and package_dir arguments. ........ r68126 | georg.brandl | 2009-01-01 07:05:13 -0600 (Thu, 01 Jan 2009) | 2 lines Handlers are in the `logging.handlers` module. ........ r68127 | georg.brandl | 2009-01-01 07:14:49 -0600 (Thu, 01 Jan 2009) | 2 lines #4767: Use correct submodules for all MIME classes. ........
2009-01-01 11:05:06 -04:00
.. currentmodule:: email.mime.text
.. class:: MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32)
2007-08-15 11:28:22 -03:00
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
2015-01-14 03:26:30 -04:00
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-Encoding`
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.