R David Murray | 79cf3ba | 2012-05-27 17:10:36 -0400 | [diff] [blame] | 1 | :mod:`email.generator`: Generating MIME documents |
| 2 | ------------------------------------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 19 | structure via the :class:`~email.parser.Parser` class, and back to flat text, |
R David Murray | ea1badb | 2012-05-15 22:07:52 -0400 | [diff] [blame] | 20 | is idempotent (the input is identical to the output) [#]_. On the other hand, |
R David Murray | 28e68ea | 2012-05-15 22:13:29 -0400 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 25 | :class:`bytes` output can be generated using the :class:`BytesGenerator` class. |
| 26 | If the message object structure contains non-ASCII bytes, this generator's |
| 27 | :meth:`~BytesGenerator.flatten` method will emit the original bytes. Parsing a |
| 28 | binary message and then flattening it with :class:`BytesGenerator` should be |
| 29 | idempotent for standards compliant messages. |
| 30 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 31 | Here are the public methods of the :class:`Generator` class, imported from the |
| 32 | :mod:`email.generator` module: |
| 33 | |
| 34 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 35 | .. class:: Generator(outfp, mangle_from_=True, maxheaderlen=78, *, policy=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 36 | |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 37 | The constructor for the :class:`Generator` class takes a :term:`file-like object` |
| 38 | called *outfp* for an argument. *outfp* must support the :meth:`write` method |
| 39 | and be usable as the output file for the :func:`print` function. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 40 | |
| 41 | Optional *mangle_from_* is a flag that, when ``True``, puts a ``>`` character in |
| 42 | front of any line in the body that starts exactly as ``From``, i.e. ``From`` |
| 43 | followed by a space at the beginning of the line. This is the only guaranteed |
| 44 | portable way to avoid having such lines be mistaken for a Unix mailbox format |
| 45 | envelope header separator (see `WHY THE CONTENT-LENGTH FORMAT IS BAD |
| 46 | <http://www.jwz.org/doc/content-length.html>`_ for details). *mangle_from_* |
| 47 | defaults to ``True``, but you might want to set this to ``False`` if you are not |
| 48 | writing Unix mailbox format files. |
| 49 | |
| 50 | Optional *maxheaderlen* specifies the longest length for a non-continued header. |
| 51 | When a header line is longer than *maxheaderlen* (in characters, with tabs |
| 52 | expanded to 8 spaces), the header will be split as defined in the |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 53 | :class:`~email.header.Header` class. Set to zero to disable header wrapping. |
| 54 | The default is 78, as recommended (but not required) by :rfc:`2822`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 55 | |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 56 | The *policy* keyword specifies a :mod:`~email.policy` object that controls a |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 57 | number of aspects of the generator's operation. If no *policy* is specified, |
Georg Brandl | 3539afd | 2012-05-30 22:03:20 +0200 | [diff] [blame] | 58 | then the *policy* attached to the message object passed to :attr:`flatten` |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 59 | is used. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 60 | |
| 61 | .. versionchanged:: 3.3 Added the *policy* keyword. |
| 62 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 63 | The other public :class:`Generator` methods are: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 64 | |
| 65 | |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 66 | .. method:: flatten(msg, unixfrom=False, linesep=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 67 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 68 | Print the textual representation of the message object structure rooted at |
| 69 | *msg* to the output file specified when the :class:`Generator` instance |
| 70 | was created. Subparts are visited depth-first and the resulting text will |
| 71 | be properly MIME encoded. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 72 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 73 | Optional *unixfrom* is a flag that forces the printing of the envelope |
| 74 | header delimiter before the first :rfc:`2822` header of the root message |
| 75 | object. If the root object has no envelope header, a standard one is |
| 76 | crafted. By default, this is set to ``False`` to inhibit the printing of |
| 77 | the envelope delimiter. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 79 | Note that for subparts, no envelope header is ever printed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 80 | |
R. David Murray | 8451c4b | 2010-10-23 22:19:56 +0000 | [diff] [blame] | 81 | Optional *linesep* specifies the line separator character used to |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 82 | terminate lines in the output. If specified it overrides the value |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 83 | specified by the *msg*\'s or ``Generator``\'s ``policy``. |
R. David Murray | 8451c4b | 2010-10-23 22:19:56 +0000 | [diff] [blame] | 84 | |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 85 | Because strings cannot represent non-ASCII bytes, if the policy that |
| 86 | applies when ``flatten`` is run has :attr:`~email.policy.Policy.cte_type` |
| 87 | set to ``8bit``, ``Generator`` will operate as if it were set to |
| 88 | ``7bit``. This means that messages parsed with a Bytes parser that have |
| 89 | a :mailheader:`Content-Transfer-Encoding` of ``8bit`` will be converted |
| 90 | to a use a ``7bit`` Content-Transfer-Encoding. Non-ASCII bytes in the |
| 91 | headers will be :rfc:`2047` encoded with a charset of ``unknown-8bit``. |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 92 | |
R. David Murray | 8451c4b | 2010-10-23 22:19:56 +0000 | [diff] [blame] | 93 | .. versionchanged:: 3.2 |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 94 | Added support for re-encoding ``8bit`` message bodies, and the |
| 95 | *linesep* argument. |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 96 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 97 | .. method:: clone(fp) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 98 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 99 | Return an independent clone of this :class:`Generator` instance with the |
| 100 | exact same options. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 101 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 102 | .. method:: write(s) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 103 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 104 | Write the string *s* to the underlying file object, i.e. *outfp* passed to |
| 105 | :class:`Generator`'s constructor. This provides just enough file-like API |
| 106 | for :class:`Generator` instances to be used in the :func:`print` function. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 107 | |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 108 | As a convenience, see the :class:`~email.message.Message` methods |
| 109 | :meth:`~email.message.Message.as_string` and ``str(aMessage)``, a.k.a. |
| 110 | :meth:`~email.message.Message.__str__`, which simplify the generation of a |
| 111 | formatted string representation of a message object. For more detail, see |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 112 | :mod:`email.message`. |
| 113 | |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 114 | .. class:: BytesGenerator(outfp, mangle_from_=True, maxheaderlen=78, *, \ |
| 115 | policy=policy.default) |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 116 | |
R. David Murray | 8451c4b | 2010-10-23 22:19:56 +0000 | [diff] [blame] | 117 | The constructor for the :class:`BytesGenerator` class takes a binary |
| 118 | :term:`file-like object` called *outfp* for an argument. *outfp* must |
| 119 | support a :meth:`write` method that accepts binary data. |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 120 | |
R. David Murray | 8451c4b | 2010-10-23 22:19:56 +0000 | [diff] [blame] | 121 | Optional *mangle_from_* is a flag that, when ``True``, puts a ``>`` |
| 122 | character in front of any line in the body that starts exactly as ``From``, |
| 123 | i.e. ``From`` followed by a space at the beginning of the line. This is the |
| 124 | only guaranteed portable way to avoid having such lines be mistaken for a |
| 125 | Unix mailbox format envelope header separator (see `WHY THE CONTENT-LENGTH |
| 126 | FORMAT IS BAD <http://www.jwz.org/doc/content-length.html>`_ for details). |
| 127 | *mangle_from_* defaults to ``True``, but you might want to set this to |
| 128 | ``False`` if you are not writing Unix mailbox format files. |
| 129 | |
| 130 | Optional *maxheaderlen* specifies the longest length for a non-continued |
| 131 | header. When a header line is longer than *maxheaderlen* (in characters, |
| 132 | with tabs expanded to 8 spaces), the header will be split as defined in the |
| 133 | :class:`~email.header.Header` class. Set to zero to disable header |
| 134 | wrapping. The default is 78, as recommended (but not required) by |
| 135 | :rfc:`2822`. |
| 136 | |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 137 | The *policy* keyword specifies a :mod:`~email.policy` object that controls a |
| 138 | number of aspects of the generator's operation. The default policy |
| 139 | maintains backward compatibility. |
| 140 | |
| 141 | .. versionchanged:: 3.3 Added the *policy* keyword. |
| 142 | |
R. David Murray | 8451c4b | 2010-10-23 22:19:56 +0000 | [diff] [blame] | 143 | The other public :class:`BytesGenerator` methods are: |
| 144 | |
| 145 | |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 146 | .. method:: flatten(msg, unixfrom=False, linesep=None) |
R. David Murray | 8451c4b | 2010-10-23 22:19:56 +0000 | [diff] [blame] | 147 | |
| 148 | Print the textual representation of the message object structure rooted |
| 149 | at *msg* to the output file specified when the :class:`BytesGenerator` |
| 150 | instance was created. Subparts are visited depth-first and the resulting |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 151 | text will be properly MIME encoded. If the :mod:`~email.policy` option |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 152 | :attr:`~email.policy.Policy.cte_type` is ``8bit`` (the default), |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 153 | then any bytes with the high bit set in the original parsed message that |
| 154 | have not been modified will be copied faithfully to the output. If |
R David Murray | c27e522 | 2012-05-25 15:01:48 -0400 | [diff] [blame] | 155 | ``cte_type`` is ``7bit``, the bytes will be converted as needed |
| 156 | using an ASCII-compatible Content-Transfer-Encoding. In particular, |
| 157 | RFC-invalid non-ASCII bytes in headers will be encoded using the MIME |
| 158 | ``unknown-8bit`` character set, thus rendering them RFC-compliant. |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 159 | |
| 160 | .. XXX: There should be a complementary option that just does the RFC |
| 161 | compliance transformation but leaves CTE 8bit parts alone. |
R. David Murray | 8451c4b | 2010-10-23 22:19:56 +0000 | [diff] [blame] | 162 | |
| 163 | Messages parsed with a Bytes parser that have a |
| 164 | :mailheader:`Content-Transfer-Encoding` of 8bit will be reconstructed |
| 165 | as 8bit if they have not been modified. |
| 166 | |
| 167 | Optional *unixfrom* is a flag that forces the printing of the envelope |
| 168 | header delimiter before the first :rfc:`2822` header of the root message |
| 169 | object. If the root object has no envelope header, a standard one is |
| 170 | crafted. By default, this is set to ``False`` to inhibit the printing of |
| 171 | the envelope delimiter. |
| 172 | |
| 173 | Note that for subparts, no envelope header is ever printed. |
| 174 | |
| 175 | Optional *linesep* specifies the line separator character used to |
R David Murray | 3edd22a | 2011-04-18 13:59:37 -0400 | [diff] [blame] | 176 | terminate lines in the output. If specified it overrides the value |
| 177 | specified by the ``Generator``\ 's ``policy``. |
R. David Murray | 8451c4b | 2010-10-23 22:19:56 +0000 | [diff] [blame] | 178 | |
| 179 | .. method:: clone(fp) |
| 180 | |
| 181 | Return an independent clone of this :class:`BytesGenerator` instance with |
| 182 | the exact same options. |
| 183 | |
| 184 | .. method:: write(s) |
| 185 | |
| 186 | Write the string *s* to the underlying file object. *s* is encoded using |
| 187 | the ``ASCII`` codec and written to the *write* method of the *outfp* |
| 188 | *outfp* passed to the :class:`BytesGenerator`'s constructor. This |
| 189 | provides just enough file-like API for :class:`BytesGenerator` instances |
| 190 | to be used in the :func:`print` function. |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 191 | |
| 192 | .. versionadded:: 3.2 |
| 193 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 194 | The :mod:`email.generator` module also provides a derived class, called |
| 195 | :class:`DecodedGenerator` which is like the :class:`Generator` base class, |
| 196 | except that non-\ :mimetype:`text` parts are substituted with a format string |
| 197 | representing the part. |
| 198 | |
| 199 | |
Hynek Schlawack | dfa4652 | 2012-05-21 11:01:54 +0200 | [diff] [blame] | 200 | .. class:: DecodedGenerator(outfp, mangle_from_=True, maxheaderlen=78, fmt=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 201 | |
| 202 | This class, derived from :class:`Generator` walks through all the subparts of a |
| 203 | message. If the subpart is of main type :mimetype:`text`, then it prints the |
| 204 | decoded payload of the subpart. Optional *_mangle_from_* and *maxheaderlen* are |
| 205 | as with the :class:`Generator` base class. |
| 206 | |
| 207 | If the subpart is not of main type :mimetype:`text`, optional *fmt* is a format |
| 208 | string that is used instead of the message payload. *fmt* is expanded with the |
| 209 | following keywords, ``%(keyword)s`` format: |
| 210 | |
| 211 | * ``type`` -- Full MIME type of the non-\ :mimetype:`text` part |
| 212 | |
| 213 | * ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part |
| 214 | |
| 215 | * ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part |
| 216 | |
| 217 | * ``filename`` -- Filename of the non-\ :mimetype:`text` part |
| 218 | |
| 219 | * ``description`` -- Description associated with the non-\ :mimetype:`text` part |
| 220 | |
| 221 | * ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part |
| 222 | |
| 223 | The default value for *fmt* is ``None``, meaning :: |
| 224 | |
| 225 | [Non-text (%(type)s) part of message omitted, filename %(filename)s] |
R David Murray | ea1badb | 2012-05-15 22:07:52 -0400 | [diff] [blame] | 226 | |
| 227 | |
| 228 | .. rubric:: Footnotes |
| 229 | |
| 230 | .. [#] This statement assumes that you use the appropriate setting for the |
| 231 | ``unixfrom`` argument, and that you set maxheaderlen=0 (which will |
| 232 | preserve whatever the input line lengths were). It is also not strictly |
| 233 | true, since in many cases runs of whitespace in headers are collapsed |
| 234 | into single blanks. The latter is a bug that will eventually be fixed. |