blob: 6fc8ebe3e04a54d640c475727738571d358c7b7b [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`email`: Generating MIME documents
2---------------------------------------
3
4.. module:: email.generator
5 :synopsis: Generate flat text email messages from a message structure.
6
7
8One of the most common tasks is to generate the flat text of the email message
9represented by a message object structure. You will need to do this if you want
10to send your message via the :mod:`smtplib` module or the :mod:`nntplib` module,
11or print the message on the console. Taking a message object structure and
12producing a flat text document is the job of the :class:`Generator` class.
13
14Again, as with the :mod:`email.parser` module, you aren't limited to the
15functionality of the bundled generator; you could write one from scratch
16yourself. However the bundled generator knows how to generate most email in a
17standards-compliant way, should handle MIME and non-MIME email messages just
18fine, and is designed so that the transformation from flat text, to a message
19structure via the :class:`Parser` class, and back to flat text, is idempotent
20(the input is identical to the output).
21
22Here 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
Georg Brandl6911e3c2007-09-04 07:15:32 +000030 usable as the output file for the :func:`print` function.
Georg Brandl116aa622007-08-15 14:28:22 +000031
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 :mod:`email.header.Header` class. Set to zero to disable header wrapping. The
45 default is 78, as recommended (but not required) by :rfc:`2822`.
46
47The other public :class:`Generator` methods are:
48
49
50.. method:: Generator.flatten(msg[, unixfrom])
51
52 Print the textual representation of the message object structure rooted at *msg*
53 to the output file specified when the :class:`Generator` instance was created.
54 Subparts are visited depth-first and the resulting text will be properly MIME
55 encoded.
56
57 Optional *unixfrom* is a flag that forces the printing of the envelope header
58 delimiter before the first :rfc:`2822` header of the root message object. If
59 the root object has no envelope header, a standard one is crafted. By default,
60 this is set to ``False`` to inhibit the printing of the envelope delimiter.
61
62 Note that for subparts, no envelope header is ever printed.
63
Georg Brandl116aa622007-08-15 14:28:22 +000064
65.. method:: Generator.clone(fp)
66
67 Return an independent clone of this :class:`Generator` instance with the exact
68 same options.
69
Georg Brandl116aa622007-08-15 14:28:22 +000070
71.. method:: Generator.write(s)
72
73 Write the string *s* to the underlying file object, i.e. *outfp* passed to
74 :class:`Generator`'s constructor. This provides just enough file-like API for
Georg Brandl6911e3c2007-09-04 07:15:32 +000075 :class:`Generator` instances to be used in the :func:`print` function.
Georg Brandl116aa622007-08-15 14:28:22 +000076
77As a convenience, see the methods :meth:`Message.as_string` and
78``str(aMessage)``, a.k.a. :meth:`Message.__str__`, which simplify the generation
79of a formatted string representation of a message object. For more detail, see
80:mod:`email.message`.
81
82The :mod:`email.generator` module also provides a derived class, called
83:class:`DecodedGenerator` which is like the :class:`Generator` base class,
84except that non-\ :mimetype:`text` parts are substituted with a format string
85representing the part.
86
87
88.. class:: DecodedGenerator(outfp[, mangle_from_[, maxheaderlen[, fmt]]])
89
90 This class, derived from :class:`Generator` walks through all the subparts of a
91 message. If the subpart is of main type :mimetype:`text`, then it prints the
92 decoded payload of the subpart. Optional *_mangle_from_* and *maxheaderlen* are
93 as with the :class:`Generator` base class.
94
95 If the subpart is not of main type :mimetype:`text`, optional *fmt* is a format
96 string that is used instead of the message payload. *fmt* is expanded with the
97 following keywords, ``%(keyword)s`` format:
98
99 * ``type`` -- Full MIME type of the non-\ :mimetype:`text` part
100
101 * ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part
102
103 * ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part
104
105 * ``filename`` -- Filename of the non-\ :mimetype:`text` part
106
107 * ``description`` -- Description associated with the non-\ :mimetype:`text` part
108
109 * ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part
110
111 The default value for *fmt* is ``None``, meaning ::
112
113 [Non-text (%(type)s) part of message omitted, filename %(filename)s]