1
:mod:`email` --- An email and MIME handling package
2
===================================================
5
:synopsis: Package supporting the parsing, manipulating, and generating
6
email messages, including MIME documents.
7
.. moduleauthor:: Barry A. Warsaw <barry@python.org>
8
.. sectionauthor:: Barry A. Warsaw <barry@python.org>
9
.. Copyright (C) 2001-2010 Python Software Foundation
12
The :mod:`email` package is a library for managing email messages, including
13
MIME and other :rfc:`2822`\ -based message documents. It is specifically *not*
14
designed to do any sending of email messages to SMTP (:rfc:`2821`), NNTP, or
15
other servers; those are functions of modules such as :mod:`smtplib` and
16
:mod:`nntplib`. The :mod:`email` package attempts to be as RFC-compliant as
17
possible, supporting in addition to :rfc:`2822`, such MIME-related RFCs as
18
:rfc:`2045`, :rfc:`2046`, :rfc:`2047`, and :rfc:`2231`.
20
The primary distinguishing feature of the :mod:`email` package is that it splits
21
the parsing and generating of email messages from the internal *object model*
22
representation of email. Applications using the :mod:`email` package deal
23
primarily with objects; you can add sub-objects to messages, remove sub-objects
24
from messages, completely re-arrange the contents, etc. There is a separate
25
parser and a separate generator which handles the transformation from flat text
26
to the object model, and then back to flat text again. There are also handy
27
subclasses for some common MIME object types, and a few miscellaneous utilities
28
that help with such common tasks as extracting and parsing message field values,
29
creating RFC-compliant dates, etc.
31
The following sections describe the functionality of the :mod:`email` package.
32
The ordering follows a progression that should be common in applications: an
33
email message is read as flat text from a file or other source, the text is
34
parsed to produce the object structure of the email message, this structure is
35
manipulated, and finally, the object tree is rendered back into flat text.
37
It is perfectly feasible to create the object structure out of whole cloth ---
38
i.e. completely from scratch. From there, a similar progression can be taken as
41
Also included are detailed specifications of all the classes and modules that
42
the :mod:`email` package provides, the exception classes you might encounter
43
while using the :mod:`email` package, some auxiliary utilities, and a few
44
examples. For users of the older :mod:`mimelib` package, or previous versions
45
of the :mod:`email` package, a section on differences and porting is provided.
47
Contents of the :mod:`email` package documentation:
55
email.headerregistry.rst
56
email.contentmanager.rst
76
.. _email-pkg-history:
81
This table describes the release history of the email package, corresponding to
82
the version of Python that the package was released with. For purposes of this
83
document, when you see a note about change or added versions, these refer to the
84
Python version the change was made in, *not* the email package version. This
85
table also describes the Python compatibility of each version of the package.
87
+---------------+------------------------------+-----------------------+
88
| email version | distributed with | compatible with |
89
+===============+==============================+=======================+
90
| :const:`1.x` | Python 2.2.0 to Python 2.2.1 | *no longer supported* |
91
+---------------+------------------------------+-----------------------+
92
| :const:`2.5` | Python 2.2.2+ and Python 2.3 | Python 2.1 to 2.5 |
93
+---------------+------------------------------+-----------------------+
94
| :const:`3.0` | Python 2.4 and Python 2.5 | Python 2.3 to 2.6 |
95
+---------------+------------------------------+-----------------------+
96
| :const:`4.0` | Python 2.5 to Python 2.7 | Python 2.3 to 2.7 |
97
+---------------+------------------------------+-----------------------+
98
| :const:`5.0` | Python 3.0 and Python 3.1 | Python 3.0 to 3.2 |
99
+---------------+------------------------------+-----------------------+
100
| :const:`5.1` | Python 3.2 | Python 3.2 |
101
+---------------+------------------------------+-----------------------+
103
After Version 5.1 (Python 3.2), the email package no longer has a version that
104
is separate from the Python version. (See the :ref:`whatsnew-index` documents
105
for the respective Python versions for details on changes.)
107
Here are the major differences between :mod:`email` version 5.1 and
110
* It is once again possible to parse messages containing non-ASCII bytes,
111
and to reproduce such messages if the data containing the non-ASCII
112
bytes is not modified.
114
* New functions :func:`message_from_bytes` and :func:`message_from_binary_file`,
115
and new classes :class:`~email.parser.BytesFeedParser` and
116
:class:`~email.parser.BytesParser` allow binary message data to be parsed
119
* Given bytes input to the model, :meth:`~email.message.Message.get_payload`
120
will by default decode a message body that has a
121
:mailheader:`Content-Transfer-Encoding` of ``8bit`` using the charset
122
specified in the MIME headers and return the resulting string.
124
* Given bytes input to the model, :class:`~email.generator.Generator` will
125
convert message bodies that have a :mailheader:`Content-Transfer-Encoding` of
126
8bit to instead have a 7bit Content-Transfer-Encoding.
128
* New class :class:`~email.generator.BytesGenerator` produces bytes
129
as output, preserving any unchanged non-ASCII data that was
130
present in the input used to build the model, including message bodies
131
with a :mailheader:`Content-Transfer-Encoding` of 8bit.
133
Here are the major differences between :mod:`email` version 5.0 and version 4:
135
* All operations are on unicode strings. Text inputs must be strings,
136
text outputs are strings. Outputs are limited to the ASCII character
137
set and so can be encoded to ASCII for transmission. Inputs are also
138
limited to ASCII; this is an acknowledged limitation of email 5.0 and
139
means it can only be used to parse email that is 7bit clean.
141
Here are the major differences between :mod:`email` version 4 and version 3:
143
* All modules have been renamed according to :pep:`8` standards. For example,
144
the version 3 module :mod:`email.Message` was renamed to :mod:`email.message` in
147
* A new subpackage :mod:`email.mime` was added and all the version 3
148
:mod:`email.MIME\*` modules were renamed and situated into the :mod:`email.mime`
149
subpackage. For example, the version 3 module :mod:`email.MIMEText` was renamed
150
to :mod:`email.mime.text`.
152
*Note that the version 3 names will continue to work until Python 2.6*.
154
* The :mod:`email.mime.application` module was added, which contains the
155
:class:`~email.mime.application.MIMEApplication` class.
157
* Methods that were deprecated in version 3 have been removed. These include
158
:meth:`Generator.__call__`, :meth:`Message.get_type`,
159
:meth:`Message.get_main_type`, :meth:`Message.get_subtype`.
161
* Fixes have been added for :rfc:`2231` support which can change some of the
162
return types for :func:`Message.get_param <email.message.Message.get_param>`
163
and friends. Under some
164
circumstances, values which used to return a 3-tuple now return simple strings
165
(specifically, if all extended parameter segments were unencoded, there is no
166
language and charset designation expected, so the return type is now a simple
167
string). Also, %-decoding used to be done for both encoded and unencoded
168
segments; this decoding is now done only for encoded segments.
170
Here are the major differences between :mod:`email` version 3 and version 2:
172
* The :class:`~email.parser.FeedParser` class was introduced, and the
173
:class:`~email.parser.Parser` class was implemented in terms of the
174
:class:`~email.parser.FeedParser`. All parsing therefore is
175
non-strict, and parsing will make a best effort never to raise an exception.
176
Problems found while parsing messages are stored in the message's *defect*
179
* All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2
180
have been removed. These include the *_encoder* argument to the
181
:class:`~email.mime.text.MIMEText` constructor, the
182
:meth:`Message.add_payload` method, the :func:`Utils.dump_address_pair`
183
function, and the functions :func:`Utils.decode` and :func:`Utils.encode`.
185
* New :exc:`DeprecationWarning`\ s have been added to:
186
:meth:`Generator.__call__`, :meth:`Message.get_type`,
187
:meth:`Message.get_main_type`, :meth:`Message.get_subtype`, and the *strict*
188
argument to the :class:`~email.parser.Parser` class. These are expected to
189
be removed in future versions.
191
* Support for Pythons earlier than 2.3 has been removed.
193
Here are the differences between :mod:`email` version 2 and version 1:
195
* The :mod:`email.Header` and :mod:`email.Charset` modules have been added.
197
* The pickle format for :class:`~email.message.Message` instances has changed.
198
Since this was never (and still isn't) formally defined, this isn't
199
considered a backward incompatibility. However if your application pickles
200
and unpickles :class:`~email.message.Message` instances, be aware that in
201
:mod:`email` version 2, :class:`~email.message.Message` instances now have
202
private variables *_charset* and *_default_type*.
204
* Several methods in the :class:`~email.message.Message` class have been
205
deprecated, or their signatures changed. Also, many new methods have been
206
added. See the documentation for the :class:`~email.message.Message` class
207
for details. The changes should be completely backward compatible.
209
* The object structure has changed in the face of :mimetype:`message/rfc822`
210
content types. In :mod:`email` version 1, such a type would be represented
211
by a scalar payload, i.e. the container message's
212
:meth:`~email.message.Message.is_multipart` returned false,
213
:meth:`~email.message.Message.get_payload` was not a list object, but a
214
single :class:`~email.message.Message` instance.
216
This structure was inconsistent with the rest of the package, so the object
217
representation for :mimetype:`message/rfc822` content types was changed. In
218
:mod:`email` version 2, the container *does* return ``True`` from
219
:meth:`~email.message.Message.is_multipart`, and
220
:meth:`~email.message.Message.get_payload` returns a list containing a single
221
:class:`~email.message.Message` item.
223
Note that this is one place that backward compatibility could not be
224
completely maintained. However, if you're already testing the return type of
225
:meth:`~email.message.Message.get_payload`, you should be fine. You just need
226
to make sure your code doesn't do a :meth:`~email.message.Message.set_payload`
227
with a :class:`~email.message.Message` instance on a container with a content
228
type of :mimetype:`message/rfc822`.
230
* The :class:`~email.parser.Parser` constructor's *strict* argument was added,
231
and its :meth:`~email.parser.Parser.parse` and
232
:meth:`~email.parser.Parser.parsestr` methods grew a *headersonly* argument.
233
The *strict* flag was also added to functions :func:`email.message_from_file`
234
and :func:`email.message_from_string`.
236
* :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten
237
<email.generator.Generator.flatten>` instead. The
238
:class:`~email.generator.Generator` class has also grown the
239
:meth:`~email.generator.Generator.clone` method.
241
* The :class:`~email.generator.DecodedGenerator` class in the
242
:mod:`email.generator` module was added.
244
* The intermediate base classes
245
:class:`~email.mime.nonmultipart.MIMENonMultipart` and
246
:class:`~email.mime.multipart.MIMEMultipart` have been added, and interposed
247
in the class hierarchy for most of the other MIME-related derived classes.
249
* The *_encoder* argument to the :class:`~email.mime.text.MIMEText` constructor
250
has been deprecated. Encoding now happens implicitly based on the
253
* The following functions in the :mod:`email.Utils` module have been deprecated:
254
:func:`dump_address_pairs`, :func:`decode`, and :func:`encode`. The following
255
functions have been added to the module: :func:`make_msgid`,
256
:func:`decode_rfc2231`, :func:`encode_rfc2231`, and :func:`decode_params`.
258
* The non-public function :func:`email.Iterators._structure` was added.
261
Differences from :mod:`mimelib`
262
-------------------------------
264
The :mod:`email` package was originally prototyped as a separate library called
265
`mimelib <http://mimelib.sourceforge.net/>`_. Changes have been made so that method names
266
are more consistent, and some methods or modules have either been added or
267
removed. The semantics of some of the methods have also changed. For the most
268
part, any functionality available in :mod:`mimelib` is still available in the
269
:mod:`email` package, albeit often in a different way. Backward compatibility
270
between the :mod:`mimelib` package and the :mod:`email` package was not a
273
Here is a brief description of the differences between the :mod:`mimelib` and
274
the :mod:`email` packages, along with hints on how to port your applications.
276
Of course, the most visible difference between the two packages is that the
277
package name has been changed to :mod:`email`. In addition, the top-level
278
package has the following differences:
280
* :func:`messageFromString` has been renamed to :func:`message_from_string`.
282
* :func:`messageFromFile` has been renamed to :func:`message_from_file`.
284
The :class:`~email.message.Message` class has the following differences:
286
* The method :meth:`asString` was renamed to
287
:meth:`~email.message.Message.as_string`.
289
* The method :meth:`ismultipart` was renamed to
290
:meth:`~email.message.Message.is_multipart`.
292
* The :meth:`~email.message.Message.get_payload` method has grown a *decode*
295
* The method :meth:`getall` was renamed to
296
:meth:`~email.message.Message.get_all`.
298
* The method :meth:`addheader` was renamed to
299
:meth:`~email.message.Message.add_header`.
301
* The method :meth:`gettype` was renamed to :meth:`get_type`.
303
* The method :meth:`getmaintype` was renamed to :meth:`get_main_type`.
305
* The method :meth:`getsubtype` was renamed to :meth:`get_subtype`.
307
* The method :meth:`getparams` was renamed to
308
:meth:`~email.message.Message.get_params`. Also, whereas :meth:`getparams`
309
returned a list of strings, :meth:`~email.message.Message.get_params` returns
310
a list of 2-tuples, effectively the key/value pairs of the parameters, split
313
* The method :meth:`getparam` was renamed to
314
:meth:`~email.message.Message.get_param`.
316
* The method :meth:`getcharsets` was renamed to
317
:meth:`~email.message.Message.get_charsets`.
319
* The method :meth:`getfilename` was renamed to
320
:meth:`~email.message.Message.get_filename`.
322
* The method :meth:`getboundary` was renamed to
323
:meth:`~email.message.Message.get_boundary`.
325
* The method :meth:`setboundary` was renamed to
326
:meth:`~email.message.Message.set_boundary`.
328
* The method :meth:`getdecodedpayload` was removed. To get similar
329
functionality, pass the value 1 to the *decode* flag of the
330
:meth:`~email.message.Message.get_payload` method.
332
* The method :meth:`getpayloadastext` was removed. Similar functionality is
333
supported by the :class:`~email.generator.DecodedGenerator` class in the
334
:mod:`email.generator` module.
336
* The method :meth:`getbodyastext` was removed. You can get similar
337
functionality by creating an iterator with
338
:func:`~email.iterators.typed_subpart_iterator` in the :mod:`email.iterators`
341
The :class:`~email.parser.Parser` class has no differences in its public
342
interface. It does have some additional smarts to recognize
343
:mimetype:`message/delivery-status` type messages, which it represents as a
344
:class:`~email.message.Message` instance containing separate
345
:class:`~email.message.Message` subparts for each header block in the delivery
346
status notification [#]_.
348
The :class:`~email.generator.Generator` class has no differences in its public
349
interface. There is a new class in the :mod:`email.generator` module though,
350
called :class:`~email.generator.DecodedGenerator` which provides most of the
351
functionality previously available in the :meth:`Message.getpayloadastext`
354
The following modules and classes have been changed:
356
* The :class:`~email.mime.base.MIMEBase` class constructor arguments *_major*
357
and *_minor* have changed to *_maintype* and *_subtype* respectively.
359
* The ``Image`` class/module has been renamed to ``MIMEImage``. The *_minor*
360
argument has been renamed to *_subtype*.
362
* The ``Text`` class/module has been renamed to ``MIMEText``. The *_minor*
363
argument has been renamed to *_subtype*.
365
* The ``MessageRFC822`` class/module has been renamed to ``MIMEMessage``. Note
366
that an earlier version of :mod:`mimelib` called this class/module ``RFC822``,
367
but that clashed with the Python standard library module :mod:`rfc822` on some
368
case-insensitive file systems.
370
Also, the :class:`~email.mime.message.MIMEMessage` class now represents any
372
with main type :mimetype:`message`. It takes an optional argument *_subtype*
373
which is used to set the MIME subtype. *_subtype* defaults to
376
:mod:`mimelib` provided some utility functions in its :mod:`address` and
377
:mod:`date` modules. All of these functions have been moved to the
378
:mod:`email.utils` module.
380
The ``MsgReader`` class/module has been removed. Its functionality is most
381
closely supported in the :func:`~email.iterators.body_line_iterator` function
382
in the :mod:`email.iterators` module.
384
.. rubric:: Footnotes
386
.. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`.
added
removed
python-3.5.1-docs-html/_sources/library/email.txt
