1 :mod:`email.generator`: 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) [#]_. On the other hand, 21 using the Generator on a :class:`~email.message.Message` constructed by program 22 may result in changes to the :class:`~email.message.Message` object as defaults 23 are filled in. 24 25 Here are the public methods of the :class:`Generator` class, imported from the 26 :mod:`email.generator` module: 27 28 29 .. class:: Generator(outfp[, mangle_from_[, maxheaderlen]]) 30 31 The constructor for the :class:`Generator` class takes a file-like object called 32 *outfp* for an argument. *outfp* must support the :meth:`write` method and be 33 usable as the output file in a Python extended print statement. 34 35 Optional *mangle_from_* is a flag that, when ``True``, puts a ``>`` character in 36 front of any line in the body that starts exactly as ``From``, i.e. ``From`` 37 followed by a space at the beginning of the line. This is the only guaranteed 38 portable way to avoid having such lines be mistaken for a Unix mailbox format 39 envelope header separator (see `WHY THE CONTENT-LENGTH FORMAT IS BAD 40 <https://www.jwz.org/doc/content-length.html>`_ for details). *mangle_from_* 41 defaults to ``True``, but you might want to set this to ``False`` if you are not 42 writing Unix mailbox format files. 43 44 Optional *maxheaderlen* specifies the longest length for a non-continued header. 45 When a header line is longer than *maxheaderlen* (in characters, with tabs 46 expanded to 8 spaces), the header will be split as defined in the 47 :class:`~email.header.Header` class. Set to zero to disable header wrapping. 48 The default is 78, as recommended (but not required) by :rfc:`2822`. 49 50 The other public :class:`Generator` methods are: 51 52 53 .. method:: flatten(msg[, unixfrom]) 54 55 Print the textual representation of the message object structure rooted at 56 *msg* to the output file specified when the :class:`Generator` instance 57 was created. Subparts are visited depth-first and the resulting text will 58 be properly MIME encoded. 59 60 Optional *unixfrom* is a flag that forces the printing of the envelope 61 header delimiter before the first :rfc:`2822` header of the root message 62 object. If the root object has no envelope header, a standard one is 63 crafted. By default, this is set to ``False`` to inhibit the printing of 64 the envelope delimiter. 65 66 Note that for subparts, no envelope header is ever printed. 67 68 .. versionadded:: 2.2.2 69 70 71 .. method:: clone(fp) 72 73 Return an independent clone of this :class:`Generator` instance with the 74 exact same options. 75 76 .. versionadded:: 2.2.2 77 78 79 .. method:: write(s) 80 81 Write the string *s* to the underlying file object, i.e. *outfp* passed to 82 :class:`Generator`'s constructor. This provides just enough file-like API 83 for :class:`Generator` instances to be used in extended print statements. 84 85 As a convenience, see the methods :meth:`Message.as_string` and 86 ``str(aMessage)``, a.k.a. :meth:`Message.__str__`, which simplify the generation 87 of a formatted string representation of a message object. For more detail, see 88 :mod:`email.message`. 89 90 The :mod:`email.generator` module also provides a derived class, called 91 :class:`DecodedGenerator` which is like the :class:`Generator` base class, 92 except that non-\ :mimetype:`text` parts are substituted with a format string 93 representing the part. 94 95 96 .. class:: DecodedGenerator(outfp[, mangle_from_[, maxheaderlen[, fmt]]]) 97 98 This class, derived from :class:`Generator` walks through all the subparts of a 99 message. If the subpart is of main type :mimetype:`text`, then it prints the 100 decoded payload of the subpart. Optional *_mangle_from_* and *maxheaderlen* are 101 as with the :class:`Generator` base class. 102 103 If the subpart is not of main type :mimetype:`text`, optional *fmt* is a format 104 string that is used instead of the message payload. *fmt* is expanded with the 105 following keywords, ``%(keyword)s`` format: 106 107 * ``type`` -- Full MIME type of the non-\ :mimetype:`text` part 108 109 * ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part 110 111 * ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part 112 113 * ``filename`` -- Filename of the non-\ :mimetype:`text` part 114 115 * ``description`` -- Description associated with the non-\ :mimetype:`text` part 116 117 * ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part 118 119 The default value for *fmt* is ``None``, meaning :: 120 121 [Non-text (%(type)s) part of message omitted, filename %(filename)s] 122 123 .. versionadded:: 2.2.2 124 125 .. versionchanged:: 2.5 126 The previously deprecated method :meth:`__call__` was removed. 127 128 129 .. rubric:: Footnotes 130 131 .. [#] This statement assumes that you use the appropriate setting for the 132 ``unixfrom`` argument, and that you set maxheaderlen=0 (which will 133 preserve whatever the input line lengths were). It is also not strictly 134 true, since in many cases runs of whitespace in headers are collapsed 135 into single blanks. The latter is a bug that will eventually be fixed. 136
