Fetching contributors…
Cannot retrieve contributors at this time
280 lines (206 sloc) 13.3 KB

:mod:`email.generator`: Generating MIME documents

.. module:: email.generator
   :synopsis: Generate flat text email messages from a message structure.

Source code: :source:`Lib/email/`

One of the most common tasks is to generate the flat (serialized) version of the email message represented by a message object structure. You will need to do this if you want to send your message via :meth:`smtplib.SMTP.sendmail` or the :mod:`nntplib` module, or print the message on the console. Taking a message object structure and producing a serialized representation is the job of the generator classes.

As with the :mod:`email.parser` module, you aren't limited to the functionality of the bundled generator; you could write one from scratch yourself. However the bundled generator knows how to generate most email in a standards-compliant way, should handle MIME and non-MIME email messages just fine, and is designed so that the bytes-oriented parsing and generation operations are inverses, assuming the same non-transforming :mod:`~email.policy` is used for both. That is, parsing the serialized byte stream via the :class:`~email.parser.BytesParser` class and then regenerating the serialized byte stream using :class:`BytesGenerator` should produce output identical to the input [1]. (On the other hand, using the generator on an :class:`~email.message.EmailMessage` constructed by program may result in changes to the :class:`~email.message.EmailMessage` object as defaults are filled in.)

The :class:`Generator` class can be used to flatten a message into a text (as opposed to binary) serialized representation, but since Unicode cannot represent binary data directly, the message is of necessity transformed into something that contains only ASCII characters, using the standard email RFC Content Transfer Encoding techniques for encoding email messages for transport over channels that are not "8 bit clean".

As a convenience, :class:`~email.message.EmailMessage` provides the methods :meth:`~email.message.EmailMessage.as_bytes` and bytes(aMessage) (a.k.a. :meth:`~email.message.EmailMessage.__bytes__`), which simplify the generation of a serialized binary representation of a message object. For more detail, see :mod:`email.message`.

Because strings cannot represent binary data, the :class:`Generator` class must convert any binary data in any message it flattens to an ASCII compatible format, by converting them to an ASCII compatible :mailheader:`Content-Transfer_Encoding`. Using the terminology of the email RFCs, you can think of this as :class:`Generator` serializing to an I/O stream that is not "8 bit clean". In other words, most applications will want to be using :class:`BytesGenerator`, and not :class:`Generator`.

As a convenience, :class:`~email.message.EmailMessage` provides the methods :meth:`~email.message.EmailMessage.as_string` and str(aMessage) (a.k.a. :meth:`~email.message.EmailMessage.__str__`), which simplify the generation of a formatted string representation of a message object. For more detail, see :mod:`email.message`.

The :mod:`email.generator` module also provides a derived class, :class:`DecodedGenerator`, which is like the :class:`Generator` base class, except that non-:mimetype:`text` parts are not serialized, but are instead represented in the output stream by a string derived from a template filled in with information about the part.


[1]This statement assumes that you use the appropriate setting for unixfrom, and that there are no :mod:`policy` settings calling for automatic adjustments (for example, :attr:`~email.policy.Policy.refold_source` must be none, which is not the default). It is also not 100% true, since if the message does not conform to the RFC standards occasionally information about the exact original text is lost during parsing error recovery. It is a goal to fix these latter edge cases when possible.