12.2.11 Differences from email v1 (up to Python 2.2.1)
Keywords: lib

## 12.2.11 Differences from `email` v1 (up to Python 2.2.1)

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. `email` version 2 is almost entirely backward compatible with version 1, with the following differences:

- 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.