New in version 2.2.
multifile, and other non-standard packages such as
mimecntl. It is specifically not designed to do any sending of email messages to SMTP (RFC 2821), NNTP, or other servers; those are functions of modules such as
The primary distinguishing feature of the
The following sections describe the functionality of the
It is perfectly feasible to create the object structure out of whole cloth — i.e. completely from scratch. From there, a similar progression can be taken as above.
Also included are detailed specifications of all the classes and modules that the
mimelib package, or previous versions of the
Contents of the
email.message: Representing an email message
email.parser: Parsing email messages
email.generator: Generating MIME documents
email.mime: Creating email and MIME objects from scratch
email.header: Internationalized headers
email.charset: Representing character sets
email.errors: Exception and Defect classes
email.utils: Miscellaneous utilities
This table describes the release history of the email package, corresponding to the version of Python that the package was released with. For purposes of this document, when you see a note about change or added versions, these refer to the Python version the change was made in, not the email package version. This table also describes the Python compatibility of each version of the package.
|email version||distributed with||compatible with|
| ||Python 2.2.0 to Python 2.2.1||no longer supported|
| ||Python 2.2.2+ and Python 2.3||Python 2.1 to 2.5|
| ||Python 2.4||Python 2.3 to 2.5|
| ||Python 2.5||Python 2.3 to 2.5|
Here are the major differences between
email.Messagewas renamed to
email.messagein version 4.
A new subpackage
email.mime was added and all the version 3
email.MIME* modules were renamed and situated into the
email.mime subpackage. For example, the version 3 module
email.MIMEText was renamed to
Note that the version 3 names will continue to work until Python 2.6.
email.mime.applicationmodule was added, which contains the
Message.get_paramand friends. Under some circumstances, values which used to return a 3-tuple now return simple strings (specifically, if all extended parameter segments were unencoded, there is no language and charset designation expected, so the return type is now a simple string). Also, %-decoding used to be done for both encoded and unencoded segments; this decoding is now done only for encoded segments.
Here are the major differences between
FeedParserclass was introduced, and the
Parserclass was implemented in terms of the
FeedParser. All parsing therefore is non-strict, and parsing will make a best effort never to raise an exception. Problems found while parsing messages are stored in the message’s defect attribute.
DeprecationWarnings in version 2 have been removed. These include the _encoder argument to the
Utils.dump_address_pair()function, and the functions
DeprecationWarnings have been added to:
Message.get_subtype(), and the strict argument to the
Parserclass. These are expected to be removed in future versions.
Here are the differences between
email.Charsetmodules have been added.
Messageinstances has changed. Since this was never (and still isn’t) formally defined, this isn’t considered a backward incompatibility. However if your application pickles and unpickles
Messageinstances, be aware that in
Messageinstances now have private variables _charset and _default_type.
Messageclass have been deprecated, or their signatures changed. Also, many new methods have been added. See the documentation for the
Messageclass for details. The changes should be completely backward compatible.
The object structure has changed in the face of message/rfc822 content types. In
is_multipart() returned false,
get_payload() was not a list object, but a single
This structure was inconsistent with the rest of the package, so the object representation for message/rfc822 content types was changed. In
get_payload() returns a list containing a single
Note that this is one place that backward compatibility could not be completely maintained. However, if you’re already testing the return type of
get_payload(), you should be fine. You just need to make sure your code doesn’t do a
set_payload() with a
Message instance on a container with a content type of message/rfc822.
Parserconstructor’s strict argument was added, and its
parsestr()methods grew a headersonly argument. The strict flag was also added to functions
Generator.__call__()is deprecated; use
Generatorclass has also grown the
DecodedGeneratorclass in the
email.generatormodule was added.
MIMEMultiparthave been added, and interposed in the class hierarchy for most of the other MIME-related derived classes.
MIMETextconstructor has been deprecated. Encoding now happens implicitly based on the _charset argument.
email.Utilsmodule have been deprecated:
encode(). The following functions have been added to the module:
mimelib is still available in the
mimelib package and the
Here is a brief description of the differences between the
mimelib and the
Of course, the most visible difference between the two packages is that the package name has been changed to
messageFromString()has been renamed to
messageFromFile()has been renamed to
Message class has the following differences:
asString()was renamed to
ismultipart()was renamed to
get_payload()method has grown a decode optional argument.
getall()was renamed to
addheader()was renamed to
gettype()was renamed to
getmaintype()was renamed to
getsubtype()was renamed to
getparams()was renamed to
get_params(). Also, whereas
getparams()returned a list of strings,
get_params()returns a list of 2-tuples, effectively the key/value pairs of the parameters, split on the
getparam()was renamed to
getcharsets()was renamed to
getfilename()was renamed to
getboundary()was renamed to
setboundary()was renamed to
getdecodedpayload()was removed. To get similar functionality, pass the value 1 to the decode flag of the
getpayloadastext()was removed. Similar functionality is supported by the
DecodedGeneratorclass in the
getbodyastext()was removed. You can get similar functionality by creating an iterator with
Parser class has no differences in its public interface. It does have some additional smarts to recognize message/delivery-status type messages, which it represents as a
Message instance containing separate
Message subparts for each header block in the delivery status notification .
Generator class has no differences in its public interface. There is a new class in the
email.generator module though, called
DecodedGenerator which provides most of the functionality previously available in the
The following modules and classes have been changed:
MIMEBaseclass constructor arguments _major and _minor have changed to _maintype and _subtype respectively.
Imageclass/module has been renamed to
MIMEImage. The _minor argument has been renamed to _subtype.
Textclass/module has been renamed to
MIMEText. The _minor argument has been renamed to _subtype.
MessageRFC822 class/module has been renamed to
MIMEMessage. Note that an earlier version of
mimelib called this class/module
RFC822, but that clashed with the Python standard library module
rfc822 on some case-insensitive file systems.
MIMEMessage class now represents any kind of MIME message with main type message. It takes an optional argument _subtype which is used to set the MIME subtype. _subtype defaults to rfc822.
mimelib provided some utility functions in its
date modules. All of these functions have been moved to the
|||Delivery Status Notifications (DSN) are defined in RFC 1894.|
© 2001–2017 Python Software Foundation
Licensed under the PSF License.