## 12.2.11 Package History

Version 1 of the `email` package was bundled with Python releases up to Python 2.2.1. Version 2 was developed for the Python 2.3 release, and backported to Python 2.2.2. It was also available as a separate distutils-based package, and is compatible back to Python 2.1.

`email` version 3.0 was released with Python 2.4 and as a separate distutils-based package. It is compatible back to Python 2.3.

Here are the differences between `email` version 3 and version 2:

- The `FeedParser` class was introduced, and the `Parser` class was implemented in terms of the `FeedParser`. All parsing there for 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.

- All aspects of the API which raised `DeprecationWarning`s in version 2 have been removed. These include the _encoder argument to the `MIMEText` constructor, the `Message.add_payload()` method, the `Utils.dump_address_pair()` function, and the functions `Utils.decode()` and `Utils.encode()`.

- New `DeprecationWarning`s have been added to: `Generator.__call__()`, `Message.get_type()`, `Message.get_main_type()`, `Message.get_subtype()`, and the strict argument to the `Parser` class. These are expected to be removed in email 3.1.

- Support for Pythons earlier than 2.3 has been removed.

Here are the differences between `email` version 2 and version 1:

- The `email.Header` and `email.Charset` modules have been added.

- The pickle format for `Message` instances 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 `Message` instances, be aware that in `email` version 2, `Message` instances now have private variables _charset and _default_type.

- Several methods in the `Message` class have been deprecated, or their signatures changed. Also, many new methods have been added. See the documentation for the `Message` class for details. The changes should be completely backward compatible.

- The object structure has changed in the face of message/rfc822 content types. In `email` version 1, such a type would be represented by a scalar payload, i.e. the container message's `is_multipart()` returned false, `get_payload()` was not a list object, but a single `Message` instance.

  This structure was inconsistent with the rest of the package, so the object representation for message/rfc822 content types was changed. In `email` version 2, the container does return `True` from `is_multipart()`, and `get_payload()` returns a list containing a single `Message` item.

  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.

- The `Parser` constructor's strict argument was added, and its `parse()` and `parsestr()` methods grew a headersonly argument. The strict flag was also added to functions `email.message_from_file()` and `email.message_from_string()`.

- `Generator.__call__()` is deprecated; use `Generator.flatten()` instead. The `Generator` class has also grown the `clone()` method.

- The `DecodedGenerator` class in the `email.Generator` module was added.

- The intermediate base classes `MIMENonMultipart` and `MIMEMultipart` have been added, and interposed in the class hierarchy for most of the other MIME-related derived classes.

- The _encoder argument to the `MIMEText` constructor has been deprecated. Encoding now happens implicitly based on the _charset argument.

- The following functions in the `email.Utils` module have been deprecated: `dump_address_pairs()`, `decode()`, and `encode()`. The following functions have been added to the module: `make_msgid()`, `decode_rfc2231()`, `encode_rfc2231()`, and `decode_params()`.

- The non-public function `email.Iterators._structure()` was added.