cpython/Doc/library/email.generator.rst

:mod:`email`: Generating MIME documents
---------------------------------------

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


One of the most common tasks is to generate the flat text of the email message
represented by a message object structure.  You will need to do this if you want
to send your message via the :mod:`smtplib` module or the :mod:`nntplib` module,
or print the message on the console.  Taking a message object structure and
producing a flat text document is the job of the :class:`Generator` class.

Again, 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 transformation from flat text, to a message
structure via the :class:`~email.parser.Parser` class, and back to flat text,
is idempotent (the input is identical to the output).  On the other hand, using
the Generator on a :class:`~email.message.Message` constructed by program may
result in changes to the :class:`~email.message.Message` object as defaults are
filled in.

:class:`bytes` output can be generated using the :class:`BytesGenerator` class.
If the message object structure contains non-ASCII bytes, this generator's
:meth:`~BytesGenerator.flatten` method will emit the original bytes.  Parsing a
binary message and then flattening it with :class:`BytesGenerator` should be
idempotent for standards compliant messages.

Here are the public methods of the :class:`Generator` class, imported from the
:mod:`email.generator` module:


.. class:: Generator(outfp, mangle_from_=True, maxheaderlen=78, *, \
                     policy=policy.default)

   The constructor for the :class:`Generator` class takes a :term:`file-like object`
   called *outfp* for an argument.  *outfp* must support the :meth:`write` method
   and be usable as the output file for the :func:`print` function.

   Optional *mangle_from_* is a flag that, when ``True``, puts a ``>`` character in
   front of any line in the body that starts exactly as ``From``, i.e. ``From``
   followed by a space at the beginning of the line.  This is the only guaranteed
   portable way to avoid having such lines be mistaken for a Unix mailbox format
   envelope header separator (see `WHY THE CONTENT-LENGTH FORMAT IS BAD
   <http://www.jwz.org/doc/content-length.html>`_ for details).  *mangle_from_*
   defaults to ``True``, but you might want to set this to ``False`` if you are not
   writing Unix mailbox format files.

   Optional *maxheaderlen* specifies the longest length for a non-continued header.
   When a header line is longer than *maxheaderlen* (in characters, with tabs
   expanded to 8 spaces), the header will be split as defined in the
   :class:`~email.header.Header` class.  Set to zero to disable header wrapping.
   The default is 78, as recommended (but not required) by :rfc:`2822`.

   The *policy* keyword specifies a :mod:`~email.policy` object that controls a
   number of aspects of the generator's operation.  The default policy
   maintains backward compatibility.

   .. versionchanged:: 3.3 Added the *policy* keyword.

   The other public :class:`Generator` methods are:


   .. method:: flatten(msg, unixfrom=False, linesep=None)

      Print the textual representation of the message object structure rooted at
      *msg* to the output file specified when the :class:`Generator` instance
      was created.  Subparts are visited depth-first and the resulting text will
      be properly MIME encoded.

      Optional *unixfrom* is a flag that forces the printing of the envelope
      header delimiter before the first :rfc:`2822` header of the root message
      object.  If the root object has no envelope header, a standard one is
      crafted.  By default, this is set to ``False`` to inhibit the printing of
      the envelope delimiter.

      Note that for subparts, no envelope header is ever printed.

      Optional *linesep* specifies the line separator character used to
      terminate lines in the output.  If specified it overrides the value
      specified by the ``Generator``\'s ``policy``.

      Because strings cannot represent non-ASCII bytes, ``Generator`` ignores
      the value of the :attr:`~email.policy.Policy.must_be_7bit`
      :mod:`~email.policy` setting and operates as if it were set ``True``.
      This means that messages parsed with a Bytes parser that have a
      :mailheader:`Content-Transfer-Encoding` of 8bit will be converted to a
      use a 7bit Content-Transfer-Encoding.  Non-ASCII bytes in the headers
      will be :rfc:`2047` encoded with a charset of `unknown-8bit`.

      .. versionchanged:: 3.2
         Added support for re-encoding 8bit message bodies, and the *linesep*
         argument.

   .. method:: clone(fp)

      Return an independent clone of this :class:`Generator` instance with the
      exact same options.

   .. method:: write(s)

      Write the string *s* to the underlying file object, i.e. *outfp* passed to
      :class:`Generator`'s constructor.  This provides just enough file-like API
      for :class:`Generator` instances to be used in the :func:`print` function.

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

.. class:: BytesGenerator(outfp, mangle_from_=True, maxheaderlen=78, *, \
                          policy=policy.default)

   The constructor for the :class:`BytesGenerator` class takes a binary
   :term:`file-like object` called *outfp* for an argument.  *outfp* must
   support a :meth:`write` method that accepts binary data.

   Optional *mangle_from_* is a flag that, when ``True``, puts a ``>``
   character in front of any line in the body that starts exactly as ``From``,
   i.e. ``From`` followed by a space at the beginning of the line.  This is the
   only guaranteed portable way to avoid having such lines be mistaken for a
   Unix mailbox format envelope header separator (see `WHY THE CONTENT-LENGTH
   FORMAT IS BAD <http://www.jwz.org/doc/content-length.html>`_ for details).
   *mangle_from_* defaults to ``True``, but you might want to set this to
   ``False`` if you are not writing Unix mailbox format files.

   Optional *maxheaderlen* specifies the longest length for a non-continued
   header.  When a header line is longer than *maxheaderlen* (in characters,
   with tabs expanded to 8 spaces), the header will be split as defined in the
   :class:`~email.header.Header` class.  Set to zero to disable header
   wrapping.  The default is 78, as recommended (but not required) by
   :rfc:`2822`.

   The *policy* keyword specifies a :mod:`~email.policy` object that controls a
   number of aspects of the generator's operation.  The default policy
   maintains backward compatibility.

   .. versionchanged:: 3.3 Added the *policy* keyword.

   The other public :class:`BytesGenerator` methods are:


   .. method:: flatten(msg, unixfrom=False, linesep=None)

      Print the textual representation of the message object structure rooted
      at *msg* to the output file specified when the :class:`BytesGenerator`
      instance was created.  Subparts are visited depth-first and the resulting
      text will be properly MIME encoded.  If the :mod:`~email.policy` option
      :attr:`~email.policy.Policy.must_be_7bit` is ``False`` (the default),
      then any bytes with the high bit set in the original parsed message that
      have not been modified will be copied faithfully to the output.  If
      ``must_be_7bit`` is true, the bytes will be converted as needed using an
      ASCII content-transfer-encoding.  In particular, RFC-invalid non-ASCII
      bytes in headers will be encoded using the MIME ``unknown-8bit``
      character set, thus rendering them RFC-compliant.

      .. XXX: There should be a complementary option that just does the RFC
         compliance transformation but leaves CTE 8bit parts alone.

      Messages parsed with a Bytes parser that have a
      :mailheader:`Content-Transfer-Encoding` of 8bit will be reconstructed
      as 8bit if they have not been modified.

      Optional *unixfrom* is a flag that forces the printing of the envelope
      header delimiter before the first :rfc:`2822` header of the root message
      object.  If the root object has no envelope header, a standard one is
      crafted.  By default, this is set to ``False`` to inhibit the printing of
      the envelope delimiter.

      Note that for subparts, no envelope header is ever printed.

      Optional *linesep* specifies the line separator character used to
      terminate lines in the output.  If specified it overrides the value
      specified by the ``Generator``\ 's ``policy``.

   .. method:: clone(fp)

      Return an independent clone of this :class:`BytesGenerator` instance with
      the exact same options.

   .. method:: write(s)

      Write the string *s* to the underlying file object.  *s* is encoded using
      the ``ASCII`` codec and written to the *write* method of the  *outfp*
      *outfp* passed to the :class:`BytesGenerator`'s constructor.  This
      provides just enough file-like API for :class:`BytesGenerator` instances
      to be used in the :func:`print` function.

   .. versionadded:: 3.2

The :mod:`email.generator` module also provides a derived class, called
:class:`DecodedGenerator` which is like the :class:`Generator` base class,
except that non-\ :mimetype:`text` parts are substituted with a format string
representing the part.


.. class:: DecodedGenerator(outfp[, mangle_from_=True, maxheaderlen=78, fmt=None)

   This class, derived from :class:`Generator` walks through all the subparts of a
   message.  If the subpart is of main type :mimetype:`text`, then it prints the
   decoded payload of the subpart. Optional *_mangle_from_* and *maxheaderlen* are
   as with the :class:`Generator` base class.

   If the subpart is not of main type :mimetype:`text`, optional *fmt* is a format
   string that is used instead of the message payload. *fmt* is expanded with the
   following keywords, ``%(keyword)s`` format:

   * ``type`` -- Full MIME type of the non-\ :mimetype:`text` part

   * ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part

   * ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part

   * ``filename`` -- Filename of the non-\ :mimetype:`text` part

   * ``description`` -- Description associated with the non-\ :mimetype:`text` part

   * ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part

   The default value for *fmt* is ``None``, meaning ::

      [Non-text (%(type)s) part of message omitted, filename %(filename)s]