cpython/Doc/library/email.mime.rst

190 lines
8.6 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
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, **_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.
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`.
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``).
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:`attach` method,
which only makes sense for :mimetype:`multipart` messages. If :meth:`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, **_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` method.
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.
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, **_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* is a string containing the raw
byte 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:`get_payload` and
:meth:`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.
*_params* are passed straight through to the base class constructor.
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, **_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* 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*
parameter. 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:`get_payload` and
:meth:`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.
*_params* are passed straight through to the base class constructor.
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, **_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* 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*
parameter. 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:`get_payload` and
:meth:`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.
*_params* are passed straight through to the :class:`~email.mime.base.MIMEBase`
constructor.
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')
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`.
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='us-ascii')
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 a parameter to the
:class:`~email.mime.nonmultipart.MIMENonMultipart` constructor; it defaults
to ``us-ascii``. No guessing or encoding is performed on the text data.
2007-08-15 11:28:22 -03:00