R David Murray | 79cf3ba | 2012-05-27 17:10:36 -0400 | [diff] [blame] | 1 | :mod:`email.encoders`: Encoders |
| 2 | ------------------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | |
| 4 | .. module:: email.encoders |
| 5 | :synopsis: Encoders for email message payloads. |
| 6 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 7 | **Source code:** :source:`Lib/email/encoders.py` |
| 8 | |
| 9 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 11 | This module is part of the legacy (``Compat32``) email API. In the |
| 12 | new API the functionality is provided by the *cte* parameter of |
| 13 | the :meth:`~email.message.EmailMessage.set_content` method. |
| 14 | |
| 15 | The remaining text in this section is the original documentation of the module. |
| 16 | |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 17 | When creating :class:`~email.message.Message` objects from scratch, you often |
| 18 | need to encode the payloads for transport through compliant mail servers. This |
| 19 | is especially true for :mimetype:`image/\*` and :mimetype:`text/\*` type messages |
| 20 | containing binary data. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 21 | |
| 22 | The :mod:`email` package provides some convenient encodings in its |
| 23 | :mod:`encoders` module. These encoders are actually used by the |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 24 | :class:`~email.mime.audio.MIMEAudio` and :class:`~email.mime.image.MIMEImage` |
| 25 | class constructors to provide default encodings. All encoder functions take |
| 26 | exactly one argument, the message object to encode. They usually extract the |
| 27 | payload, encode it, and reset the payload to this newly encoded value. They |
| 28 | should also set the :mailheader:`Content-Transfer-Encoding` header as appropriate. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 29 | |
R David Murray | 69ebfe4 | 2012-03-16 22:03:17 -0400 | [diff] [blame] | 30 | Note that these functions are not meaningful for a multipart message. They |
R David Murray | 4191434 | 2012-03-16 22:10:00 -0400 | [diff] [blame] | 31 | must be applied to individual subparts instead, and will raise a |
R David Murray | 69ebfe4 | 2012-03-16 22:03:17 -0400 | [diff] [blame] | 32 | :exc:`TypeError` if passed a message whose type is multipart. |
| 33 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 34 | Here are the encoding functions provided: |
| 35 | |
| 36 | |
| 37 | .. function:: encode_quopri(msg) |
| 38 | |
| 39 | Encodes the payload into quoted-printable form and sets the |
| 40 | :mailheader:`Content-Transfer-Encoding` header to ``quoted-printable`` [#]_. |
| 41 | This is a good encoding to use when most of your payload is normal printable |
| 42 | data, but contains a few unprintable characters. |
| 43 | |
| 44 | |
| 45 | .. function:: encode_base64(msg) |
| 46 | |
| 47 | Encodes the payload into base64 form and sets the |
| 48 | :mailheader:`Content-Transfer-Encoding` header to ``base64``. This is a good |
| 49 | encoding to use when most of your payload is unprintable data since it is a more |
| 50 | compact form than quoted-printable. The drawback of base64 encoding is that it |
| 51 | renders the text non-human readable. |
| 52 | |
| 53 | |
| 54 | .. function:: encode_7or8bit(msg) |
| 55 | |
| 56 | This doesn't actually modify the message's payload, but it does set the |
| 57 | :mailheader:`Content-Transfer-Encoding` header to either ``7bit`` or ``8bit`` as |
| 58 | appropriate, based on the payload data. |
| 59 | |
| 60 | |
| 61 | .. function:: encode_noop(msg) |
| 62 | |
| 63 | This does nothing; it doesn't even set the |
| 64 | :mailheader:`Content-Transfer-Encoding` header. |
| 65 | |
| 66 | .. rubric:: Footnotes |
| 67 | |
| 68 | .. [#] Note that encoding with :meth:`encode_quopri` also encodes all tabs and space |
| 69 | characters in the data. |
| 70 | |