/Doc/library/email.encoders.rst
http://unladen-swallow.googlecode.com/ · ReStructuredText · 57 lines · 37 code · 20 blank · 0 comment · 0 complexity · 160e5f47333e62f63b129ed77b2ec1dc MD5 · raw file
- :mod:`email`: Encoders
- ----------------------
- .. module:: email.encoders
- :synopsis: Encoders for email message payloads.
- When creating :class:`~email.message.Message` objects from scratch, you often
- need to encode the payloads for transport through compliant mail servers. This
- is especially true for :mimetype:`image/\*` and :mimetype:`text/\*` type messages
- containing binary data.
- The :mod:`email` package provides some convenient encodings in its
- :mod:`encoders` module. These encoders are actually used by the
- :class:`~email.mime.audio.MIMEAudio` and :class:`~email.mime.image.MIMEImage`
- class constructors to provide default encodings. All encoder functions take
- exactly one argument, the message object to encode. They usually extract the
- payload, encode it, and reset the payload to this newly encoded value. They
- should also set the :mailheader:`Content-Transfer-Encoding` header as appropriate.
- Here are the encoding functions provided:
- .. function:: encode_quopri(msg)
- Encodes the payload into quoted-printable form and sets the
- :mailheader:`Content-Transfer-Encoding` header to ``quoted-printable`` [#]_.
- This is a good encoding to use when most of your payload is normal printable
- data, but contains a few unprintable characters.
- .. function:: encode_base64(msg)
- Encodes the payload into base64 form and sets the
- :mailheader:`Content-Transfer-Encoding` header to ``base64``. This is a good
- encoding to use when most of your payload is unprintable data since it is a more
- compact form than quoted-printable. The drawback of base64 encoding is that it
- renders the text non-human readable.
- .. function:: encode_7or8bit(msg)
- This doesn't actually modify the message's payload, but it does set the
- :mailheader:`Content-Transfer-Encoding` header to either ``7bit`` or ``8bit`` as
- appropriate, based on the payload data.
- .. function:: encode_noop(msg)
- This does nothing; it doesn't even set the
- :mailheader:`Content-Transfer-Encoding` header.
- .. rubric:: Footnotes
- .. [#] Note that encoding with :meth:`encode_quopri` also encodes all tabs and space
- characters in the data.