mirror of
https://github.com/python/cpython.git
synced 2025-11-04 03:44:55 +00:00
47 lines
2 KiB
TeX
47 lines
2 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{MIMEImage} and \class{MIMEText} 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 \emph{Quoted-Printable} form and sets the
|
|
\code{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 \emph{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}
|