/Doc/library/email.encoders.rst

 1:mod:`email`: Encoders
 2----------------------
 3
 4.. module:: email.encoders
 5   :synopsis: Encoders for email message payloads.
 6
 7
 8When creating :class:`~email.message.Message` objects from scratch, you often
 9need to encode the payloads for transport through compliant mail servers. This
10is especially true for :mimetype:`image/\*` and :mimetype:`text/\*` type messages
11containing binary data.
12
13The :mod:`email` package provides some convenient encodings in its
14:mod:`encoders` module.  These encoders are actually used by the
15:class:`~email.mime.audio.MIMEAudio` and :class:`~email.mime.image.MIMEImage`
16class constructors to provide default encodings.  All encoder functions take
17exactly one argument, the message object to encode.  They usually extract the
18payload, encode it, and reset the payload to this newly encoded value.  They
19should also set the :mailheader:`Content-Transfer-Encoding` header as appropriate.
20
21Here are the encoding functions provided:
22
23
24.. function:: encode_quopri(msg)
25
26   Encodes the payload into quoted-printable form and sets the
27   :mailheader:`Content-Transfer-Encoding` header to ``quoted-printable`` [#]_.
28   This is a good encoding to use when most of your payload is normal printable
29   data, but contains a few unprintable characters.
30
31
32.. function:: encode_base64(msg)
33
34   Encodes the payload into base64 form and sets the
35   :mailheader:`Content-Transfer-Encoding` header to ``base64``.  This is a good
36   encoding to use when most of your payload is unprintable data since it is a more
37   compact form than quoted-printable.  The drawback of base64 encoding is that it
38   renders the text non-human readable.
39
40
41.. function:: encode_7or8bit(msg)
42
43   This doesn't actually modify the message's payload, but it does set the
44   :mailheader:`Content-Transfer-Encoding` header to either ``7bit`` or ``8bit`` as
45   appropriate, based on the payload data.
46
47
48.. function:: encode_noop(msg)
49
50   This does nothing; it doesn't even set the
51   :mailheader:`Content-Transfer-Encoding` header.
52
53.. rubric:: Footnotes
54
55.. [#] Note that encoding with :meth:`encode_quopri` also encodes all tabs and space
56   characters in the data.
57