Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
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 | 101f278 | 2010-01-10 19:18:27 +0000 | [diff] [blame] | 20 | is idempotent (the input is identical to the output). On the other hand, using |
| 21 | the Generator on a :class:`~email.message.Message` constructed by program may |
| 22 | result in changes to the :class:`~email.message.Message` object as defaults are |
| 23 | 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 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 35 | .. class:: Generator(outfp, mangle_from_=True, maxheaderlen=78) |
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 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 56 | The other public :class:`Generator` methods are: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | |
| 58 | |
R. David Murray | 8451c4b | 2010-10-23 22:19:56 +0000 | [diff] [blame] | 59 | .. method:: flatten(msg, unixfrom=False, linesep='\\n') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 61 | Print the textual representation of the message object structure rooted at |
| 62 | *msg* to the output file specified when the :class:`Generator` instance |
| 63 | was created. Subparts are visited depth-first and the resulting text will |
| 64 | be properly MIME encoded. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 65 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 66 | Optional *unixfrom* is a flag that forces the printing of the envelope |
| 67 | header delimiter before the first :rfc:`2822` header of the root message |
| 68 | object. If the root object has no envelope header, a standard one is |
| 69 | crafted. By default, this is set to ``False`` to inhibit the printing of |
| 70 | the envelope delimiter. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 72 | Note that for subparts, no envelope header is ever printed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | |
R. David Murray | 8451c4b | 2010-10-23 22:19:56 +0000 | [diff] [blame] | 74 | Optional *linesep* specifies the line separator character used to |
| 75 | terminate lines in the output. It defaults to ``\n`` because that is |
| 76 | the most useful value for Python application code (other library packages |
| 77 | expect ``\n`` separated lines). ``linesep=\r\n`` can be used to |
| 78 | generate output with RFC-compliant line separators. |
| 79 | |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 80 | Messages parsed with a Bytes parser that have a |
| 81 | :mailheader:`Content-Transfer-Encoding` of 8bit will be converted to a |
| 82 | use a 7bit Content-Transfer-Encoding. Any other non-ASCII bytes in the |
| 83 | message structure will be converted to '?' characters. |
| 84 | |
R. David Murray | 8451c4b | 2010-10-23 22:19:56 +0000 | [diff] [blame] | 85 | .. versionchanged:: 3.2 |
Georg Brandl | 872a702 | 2010-10-24 14:32:45 +0000 | [diff] [blame] | 86 | Added support for re-encoding 8bit message bodies, and the *linesep* |
| 87 | argument. |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 88 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 89 | .. method:: clone(fp) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 90 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 91 | Return an independent clone of this :class:`Generator` instance with the |
| 92 | exact same options. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 93 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 94 | .. method:: write(s) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 95 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 96 | Write the string *s* to the underlying file object, i.e. *outfp* passed to |
| 97 | :class:`Generator`'s constructor. This provides just enough file-like API |
| 98 | for :class:`Generator` instances to be used in the :func:`print` function. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 99 | |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 100 | As a convenience, see the :class:`~email.message.Message` methods |
| 101 | :meth:`~email.message.Message.as_string` and ``str(aMessage)``, a.k.a. |
| 102 | :meth:`~email.message.Message.__str__`, which simplify the generation of a |
| 103 | formatted string representation of a message object. For more detail, see |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 104 | :mod:`email.message`. |
| 105 | |
R. David Murray | f19076e | 2010-10-19 23:05:35 +0000 | [diff] [blame] | 106 | .. class:: BytesGenerator(outfp, mangle_from_=True, maxheaderlen=78) |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 107 | |
R. David Murray | 8451c4b | 2010-10-23 22:19:56 +0000 | [diff] [blame] | 108 | The constructor for the :class:`BytesGenerator` class takes a binary |
| 109 | :term:`file-like object` called *outfp* for an argument. *outfp* must |
| 110 | support a :meth:`write` method that accepts binary data. |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 111 | |
R. David Murray | 8451c4b | 2010-10-23 22:19:56 +0000 | [diff] [blame] | 112 | Optional *mangle_from_* is a flag that, when ``True``, puts a ``>`` |
| 113 | character in front of any line in the body that starts exactly as ``From``, |
| 114 | i.e. ``From`` followed by a space at the beginning of the line. This is the |
| 115 | only guaranteed portable way to avoid having such lines be mistaken for a |
| 116 | Unix mailbox format envelope header separator (see `WHY THE CONTENT-LENGTH |
| 117 | FORMAT IS BAD <http://www.jwz.org/doc/content-length.html>`_ for details). |
| 118 | *mangle_from_* defaults to ``True``, but you might want to set this to |
| 119 | ``False`` if you are not writing Unix mailbox format files. |
| 120 | |
| 121 | Optional *maxheaderlen* specifies the longest length for a non-continued |
| 122 | header. When a header line is longer than *maxheaderlen* (in characters, |
| 123 | with tabs expanded to 8 spaces), the header will be split as defined in the |
| 124 | :class:`~email.header.Header` class. Set to zero to disable header |
| 125 | wrapping. The default is 78, as recommended (but not required) by |
| 126 | :rfc:`2822`. |
| 127 | |
| 128 | The other public :class:`BytesGenerator` methods are: |
| 129 | |
| 130 | |
| 131 | .. method:: flatten(msg, unixfrom=False, linesep='\n') |
| 132 | |
| 133 | Print the textual representation of the message object structure rooted |
| 134 | at *msg* to the output file specified when the :class:`BytesGenerator` |
| 135 | instance was created. Subparts are visited depth-first and the resulting |
| 136 | text will be properly MIME encoded. If the input that created the *msg* |
| 137 | contained bytes with the high bit set and those bytes have not been |
| 138 | modified, they will be copied faithfully to the output, even if doing so |
| 139 | is not strictly RFC compliant. (To produce strictly RFC compliant |
| 140 | output, use the :class:`Generator` class.) |
| 141 | |
| 142 | Messages parsed with a Bytes parser that have a |
| 143 | :mailheader:`Content-Transfer-Encoding` of 8bit will be reconstructed |
| 144 | as 8bit if they have not been modified. |
| 145 | |
| 146 | Optional *unixfrom* is a flag that forces the printing of the envelope |
| 147 | header delimiter before the first :rfc:`2822` header of the root message |
| 148 | object. If the root object has no envelope header, a standard one is |
| 149 | crafted. By default, this is set to ``False`` to inhibit the printing of |
| 150 | the envelope delimiter. |
| 151 | |
| 152 | Note that for subparts, no envelope header is ever printed. |
| 153 | |
| 154 | Optional *linesep* specifies the line separator character used to |
| 155 | terminate lines in the output. It defaults to ``\n`` because that is |
| 156 | the most useful value for Python application code (other library packages |
| 157 | expect ``\n`` separated lines). ``linesep=\r\n`` can be used to |
| 158 | generate output with RFC-compliant line separators. |
| 159 | |
| 160 | .. method:: clone(fp) |
| 161 | |
| 162 | Return an independent clone of this :class:`BytesGenerator` instance with |
| 163 | the exact same options. |
| 164 | |
| 165 | .. method:: write(s) |
| 166 | |
| 167 | Write the string *s* to the underlying file object. *s* is encoded using |
| 168 | the ``ASCII`` codec and written to the *write* method of the *outfp* |
| 169 | *outfp* passed to the :class:`BytesGenerator`'s constructor. This |
| 170 | provides just enough file-like API for :class:`BytesGenerator` instances |
| 171 | to be used in the :func:`print` function. |
R. David Murray | 96fd54e | 2010-10-08 15:55:28 +0000 | [diff] [blame] | 172 | |
| 173 | .. versionadded:: 3.2 |
| 174 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 175 | The :mod:`email.generator` module also provides a derived class, called |
| 176 | :class:`DecodedGenerator` which is like the :class:`Generator` base class, |
| 177 | except that non-\ :mimetype:`text` parts are substituted with a format string |
| 178 | representing the part. |
| 179 | |
| 180 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 181 | .. class:: DecodedGenerator(outfp[, mangle_from_=True, maxheaderlen=78, fmt=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 182 | |
| 183 | This class, derived from :class:`Generator` walks through all the subparts of a |
| 184 | message. If the subpart is of main type :mimetype:`text`, then it prints the |
| 185 | decoded payload of the subpart. Optional *_mangle_from_* and *maxheaderlen* are |
| 186 | as with the :class:`Generator` base class. |
| 187 | |
| 188 | If the subpart is not of main type :mimetype:`text`, optional *fmt* is a format |
| 189 | string that is used instead of the message payload. *fmt* is expanded with the |
| 190 | following keywords, ``%(keyword)s`` format: |
| 191 | |
| 192 | * ``type`` -- Full MIME type of the non-\ :mimetype:`text` part |
| 193 | |
| 194 | * ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part |
| 195 | |
| 196 | * ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part |
| 197 | |
| 198 | * ``filename`` -- Filename of the non-\ :mimetype:`text` part |
| 199 | |
| 200 | * ``description`` -- Description associated with the non-\ :mimetype:`text` part |
| 201 | |
| 202 | * ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part |
| 203 | |
| 204 | The default value for *fmt* is ``None``, meaning :: |
| 205 | |
| 206 | [Non-text (%(type)s) part of message omitted, filename %(filename)s] |