| 1 |
:mod:`!email.encoders`: Encoders |
| 2 |
-------------------------------- |
| 3 |
|
| 4 |
.. module:: email.encoders |
| 5 |
:synopsis: Encoders for email message payloads. |
| 6 |
|
| 7 |
**Source code:** :source:`Lib/email/encoders.py` |
| 8 |
|
| 9 |
-------------- |
| 10 |
|
| 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 |
This module is deprecated in Python 3. The functions provided here |
| 16 |
should not be called explicitly since the :class:`~email.mime.text.MIMEText` |
| 17 |
class sets the content type and CTE header using the *_subtype* and *_charset* |
| 18 |
values passed during the instantiation of that class. |
| 19 |
|
| 20 |
The remaining text in this section is the original documentation of the module. |
| 21 |
|
| 22 |
When creating :class:`~email.message.Message` objects from scratch, you often |
| 23 |
need to encode the payloads for transport through compliant mail servers. This |
| 24 |
is especially true for :mimetype:`image/\*` and :mimetype:`text/\*` type messages |
| 25 |
containing binary data. |
| 26 |
|
| 27 |
The :mod:`email` package provides some convenient encoders in its |
| 28 |
:mod:`!encoders` module. These encoders are actually used by the |
| 29 |
:class:`~email.mime.audio.MIMEAudio` and :class:`~email.mime.image.MIMEImage` |
| 30 |
class constructors to provide default encodings. All encoder functions take |
| 31 |
exactly one argument, the message object to encode. They usually extract the |
| 32 |
payload, encode it, and reset the payload to this newly encoded value. They |
| 33 |
should also set the :mailheader:`Content-Transfer-Encoding` header as appropriate. |
| 34 |
|
| 35 |
Note that these functions are not meaningful for a multipart message. They |
| 36 |
must be applied to individual subparts instead, and will raise a |
| 37 |
:exc:`TypeError` if passed a message whose type is multipart. |
| 38 |
|
| 39 |
Here are the encoding functions provided: |
| 40 |
|
| 41 |
|
| 42 |
.. function:: encode_quopri(msg) |
| 43 |
|
| 44 |
Encodes the payload into quoted-printable form and sets the |
| 45 |
:mailheader:`Content-Transfer-Encoding` header to ``quoted-printable`` [#]_. |
| 46 |
This is a good encoding to use when most of your payload is normal printable |
| 47 |
data, but contains a few unprintable characters. |
| 48 |
|
| 49 |
|
| 50 |
.. function:: encode_base64(msg) |
| 51 |
|
| 52 |
Encodes the payload into base64 form and sets the |
| 53 |
:mailheader:`Content-Transfer-Encoding` header to ``base64``. This is a good |
| 54 |
encoding to use when most of your payload is unprintable data since it is a more |
| 55 |
compact form than quoted-printable. The drawback of base64 encoding is that it |
| 56 |
renders the text non-human readable. |
| 57 |
|
| 58 |
|
| 59 |
.. function:: encode_7or8bit(msg) |
| 60 |
|
| 61 |
This doesn't actually modify the message's payload, but it does set the |
| 62 |
:mailheader:`Content-Transfer-Encoding` header to either ``7bit`` or ``8bit`` as |
| 63 |
appropriate, based on the payload data. |
| 64 |
|
| 65 |
|
| 66 |
.. function:: encode_noop(msg) |
| 67 |
|
| 68 |
This does nothing; it doesn't even set the |
| 69 |
:mailheader:`Content-Transfer-Encoding` header. |
| 70 |
|
| 71 |
.. rubric:: Footnotes |
| 72 |
|
| 73 |
.. [#] Note that encoding with :meth:`encode_quopri` also encodes all tabs and space |
| 74 |
characters in the data. |
| 75 |
|