|
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:`Parser` class, and back to flat text, is idempotent |
|
20 (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 :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 |
|
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 |