Doc/library/email.generator.rst

   1 :mod:`email`: Generating MIME documents
   2 ---------------------------------------
   3
   4 .. module:: email.generator
   5    :synopsis: Generate flat text email messages from a message structure.
   6
   7
   8 One of the most common tasks is to generate the flat text of the email message
   9 represented by a message object structure.  You will need to do this if you want
  10 to send your message via the :mod:`smtplib` module or the :mod:`nntplib` module,
  11 or print the message on the console.  Taking a message object structure and
  12 producing a flat text document is the job of the :class:`Generator` class.
  13
  14 Again, as with the :mod:`email.parser` module, you aren't limited to the
  15 functionality of the bundled generator; you could write one from scratch
  16 yourself.  However the bundled generator knows how to generate most email in a
  17 standards-compliant way, should handle MIME and non-MIME email messages just
  18 fine, and is designed so that the transformation from flat text, to a message
  19 structure via the :class:`~email.parser.Parser` class, and back to flat text,
  20 is idempotent (the input is identical to the output).
  21
  22 Here are the public methods of the :class:`Generator` class, imported from the
  23 :mod:`email.generator` module:
  24
  25
  26 .. class:: Generator(outfp[, mangle_from_[, maxheaderlen]])
  27
  28    The constructor for the :class:`Generator` class takes a file-like object called
  29    *outfp* for an argument.  *outfp* must support the :meth:`write` method and be
  30    usable as the output file in a Python extended print statement.
  31
  32    Optional *mangle_from_* is a flag that, when ``True``, puts a ``>`` character in
  33    front of any line in the body that starts exactly as ``From``, i.e. ``From``
  34    followed by a space at the beginning of the line.  This is the only guaranteed
  35    portable way to avoid having such lines be mistaken for a Unix mailbox format
  36    envelope header separator (see `WHY THE CONTENT-LENGTH FORMAT IS BAD
  37    <http://www.jwz.org/doc/content-length.html>`_ for details).  *mangle_from_*
  38    defaults to ``True``, but you might want to set this to ``False`` if you are not
  39    writing Unix mailbox format files.
  40
  41    Optional *maxheaderlen* specifies the longest length for a non-continued header.
  42    When a header line is longer than *maxheaderlen* (in characters, with tabs
  43    expanded to 8 spaces), the header will be split as defined in the
  44    :class:`~email.header.Header` class.  Set to zero to disable header wrapping.
  45    The default is 78, as recommended (but not required) by :rfc:`2822`.
  46
  47    The other public :class:`Generator` methods are:
  48
  49
  50    .. method:: flatten(msg[, unixfrom])
  51
  52       Print the textual representation of the message object structure rooted at
  53       *msg* to the output file specified when the :class:`Generator` instance
  54       was created.  Subparts are visited depth-first and the resulting text will
  55       be properly MIME encoded.
  56
  57       Optional *unixfrom* is a flag that forces the printing of the envelope
  58       header delimiter before the first :rfc:`2822` header of the root message
  59       object.  If the root object has no envelope header, a standard one is
  60       crafted.  By default, this is set to ``False`` to inhibit the printing of
  61       the envelope delimiter.
  62
  63       Note that for subparts, no envelope header is ever printed.
  64
  65       .. versionadded:: 2.2.2
  66
  67
  68    .. method:: clone(fp)
  69
  70       Return an independent clone of this :class:`Generator` instance with the
  71       exact same options.
  72
  73       .. versionadded:: 2.2.2
  74
  75
  76    .. method:: write(s)
  77
  78       Write the string *s* to the underlying file object, i.e. *outfp* passed to
  79       :class:`Generator`'s constructor.  This provides just enough file-like API
  80       for :class:`Generator` instances to be used in extended print statements.
  81
  82 As a convenience, see the methods :meth:`Message.as_string` and
  83 ``str(aMessage)``, a.k.a. :meth:`Message.__str__`, which simplify the generation
  84 of a formatted string representation of a message object.  For more detail, see
  85 :mod:`email.message`.
  86
  87 The :mod:`email.generator` module also provides a derived class, called
  88 :class:`DecodedGenerator` which is like the :class:`Generator` base class,
  89 except that non-\ :mimetype:`text` parts are substituted with a format string
  90 representing the part.
  91
  92
  93 .. class:: DecodedGenerator(outfp[, mangle_from_[, maxheaderlen[, fmt]]])
  94
  95    This class, derived from :class:`Generator` walks through all the subparts of a
  96    message.  If the subpart is of main type :mimetype:`text`, then it prints the
  97    decoded payload of the subpart. Optional *_mangle_from_* and *maxheaderlen* are
  98    as with the :class:`Generator` base class.
  99
 100    If the subpart is not of main type :mimetype:`text`, optional *fmt* is a format
 101    string that is used instead of the message payload. *fmt* is expanded with the
 102    following keywords, ``%(keyword)s`` format:
 103
 104    * ``type`` -- Full MIME type of the non-\ :mimetype:`text` part
 105
 106    * ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part
 107
 108    * ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part
 109
 110    * ``filename`` -- Filename of the non-\ :mimetype:`text` part
 111
 112    * ``description`` -- Description associated with the non-\ :mimetype:`text` part
 113
 114    * ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part
 115
 116    The default value for *fmt* is ``None``, meaning ::
 117
 118       [Non-text (%(type)s) part of message omitted, filename %(filename)s]
 119
 120    .. versionadded:: 2.2.2
 121
 122 .. versionchanged:: 2.5
 123    The previously deprecated method :meth:`__call__` was removed.
 124