mirror of https://github.com/python/cpython
48 lines
2.0 KiB
TeX
48 lines
2.0 KiB
TeX
\declaremodule{standard}{email.Encoders}
|
|
\modulesynopsis{Encoders for email message payloads.}
|
|
|
|
When creating \class{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 \module{email} package provides some convenient encodings in its
|
|
\module{Encoders} module. These encoders are actually used by the
|
|
\class{MIMEAudio} and \class{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:
|
|
|
|
\begin{funcdesc}{encode_quopri}{msg}
|
|
Encodes the payload into quoted-printable form and sets the
|
|
\mailheader{Content-Transfer-Encoding} header to
|
|
\code{quoted-printable}\footnote{Note that encoding with
|
|
\method{encode_quopri()} also encodes all tabs and space characters in
|
|
the data.}.
|
|
This is a good encoding to use when most of your payload is normal
|
|
printable data, but contains a few unprintable characters.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{encode_base64}{msg}
|
|
Encodes the payload into base64 form and sets the
|
|
\mailheader{Content-Transfer-Encoding} header to
|
|
\code{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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{encode_7or8bit}{msg}
|
|
This doesn't actually modify the message's payload, but it does set
|
|
the \mailheader{Content-Transfer-Encoding} header to either \code{7bit} or
|
|
\code{8bit} as appropriate, based on the payload data.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{encode_noop}{msg}
|
|
This does nothing; it doesn't even set the
|
|
\mailheader{Content-Transfer-Encoding} header.
|
|
\end{funcdesc}
|