cpython/Doc/lib/libmimetools.tex

98 lines
3.7 KiB
TeX
Raw Normal View History

\section{\module{mimetools} ---
Tools for parsing MIME messages}
\declaremodule{standard}{mimetools}
\modulesynopsis{Tools for parsing MIME style message bodies.}
1998-03-14 06:16:57 +00:00
This module defines a subclass of the \class{rfc822.Message} class and
1995-03-22 15:48:46 +00:00
a number of utility functions that are useful for the manipulation for
1998-03-14 06:16:57 +00:00
MIME multipart or encoded message.
1995-03-22 15:48:46 +00:00
It defines the following items:
1998-03-14 06:16:57 +00:00
\begin{classdesc}{Message}{fp\optional{, seekable}}
Return a new instance of the \class{Message} class. This is a
subclass of the \class{rfc822.Message} class, with some additional
methods (see below). The \var{seekable} argument has the same meaning
as for \class{rfc822.Message}.
\end{classdesc}
1995-03-22 15:48:46 +00:00
\begin{funcdesc}{choose_boundary}{}
Return a unique string that has a high likelihood of being usable as a
part boundary. The string has the form
1998-03-14 06:16:57 +00:00
\code{'\var{hostipaddr}.\var{uid}.\var{pid}.\var{timestamp}.\var{random}'}.
1995-03-22 15:48:46 +00:00
\end{funcdesc}
1998-03-14 06:16:57 +00:00
\begin{funcdesc}{decode}{input, output, encoding}
1995-03-22 15:48:46 +00:00
Read data encoded using the allowed MIME \var{encoding} from open file
object \var{input} and write the decoded data to open file object
\var{output}. Valid values for \var{encoding} include
1998-03-14 06:16:57 +00:00
\code{'base64'}, \code{'quoted-printable'} and \code{'uuencode'}.
1995-03-22 15:48:46 +00:00
\end{funcdesc}
\begin{funcdesc}{encode}{input, output, encoding}
1995-03-22 15:48:46 +00:00
Read data from open file object \var{input} and write it encoded using
the allowed MIME \var{encoding} to open file object \var{output}.
1998-03-14 06:16:57 +00:00
Valid values for \var{encoding} are the same as for \method{decode()}.
1995-03-22 15:48:46 +00:00
\end{funcdesc}
\begin{funcdesc}{copyliteral}{input, output}
Read lines until \EOF{} from open file \var{input} and write them to
open file \var{output}.
1995-03-22 15:48:46 +00:00
\end{funcdesc}
\begin{funcdesc}{copybinary}{input, output}
Read blocks until \EOF{} from open file \var{input} and write them to
open file \var{output}. The block size is currently fixed at 8192.
1995-03-22 15:48:46 +00:00
\end{funcdesc}
\subsection{Additional Methods of Message objects}
1995-03-22 15:48:46 +00:00
\nodename{mimetools.Message Methods}
1998-03-14 06:16:57 +00:00
The \class{Message} class defines the following methods in
addition to the \class{rfc822.Message} methods:
1995-03-22 15:48:46 +00:00
\begin{methoddesc}{getplist}{}
1998-03-14 06:16:57 +00:00
Return the parameter list of the \code{content-type} header. This is
1995-03-22 15:48:46 +00:00
a list if strings. For parameters of the form
\samp{\var{key}=\var{value}}, \var{key} is converted to lower case but
\var{value} is not. For example, if the message contains the header
\samp{Content-type: text/html; spam=1; Spam=2; Spam} then
1998-03-14 06:16:57 +00:00
\method{getplist()} will return the Python list \code{['spam=1',
1995-03-22 15:48:46 +00:00
'spam=2', 'Spam']}.
\end{methoddesc}
1995-03-22 15:48:46 +00:00
\begin{methoddesc}{getparam}{name}
1995-03-22 15:48:46 +00:00
Return the \var{value} of the first parameter (as returned by
1998-03-14 06:16:57 +00:00
\method{getplist()} of the form \samp{\var{name}=\var{value}} for the
1995-03-22 15:48:46 +00:00
given \var{name}. If \var{value} is surrounded by quotes of the form
`\code{<}...\code{>}' or `\code{"}...\code{"}', these are removed.
\end{methoddesc}
1995-03-22 15:48:46 +00:00
\begin{methoddesc}{getencoding}{}
1998-03-14 06:16:57 +00:00
Return the encoding specified in the \code{content-transfer-encoding}
message header. If no such header exists, return \code{'7bit'}. The
1995-03-22 15:48:46 +00:00
encoding is converted to lower case.
\end{methoddesc}
1995-03-22 15:48:46 +00:00
\begin{methoddesc}{gettype}{}
Return the message type (of the form \samp{\var{type}/\var{subtype}})
1998-03-14 06:16:57 +00:00
as specified in the \code{content-type} header. If no such header
exists, return \code{'text/plain'}. The type is converted to lower
1995-03-22 15:48:46 +00:00
case.
\end{methoddesc}
1995-03-22 15:48:46 +00:00
\begin{methoddesc}{getmaintype}{}
1998-03-14 06:16:57 +00:00
Return the main type as specified in the \code{content-type} header.
If no such header exists, return \code{'text'}. The main type is
1995-03-22 15:48:46 +00:00
converted to lower case.
\end{methoddesc}
1995-03-22 15:48:46 +00:00
\begin{methoddesc}{getsubtype}{}
1998-03-14 06:16:57 +00:00
Return the subtype as specified in the \code{content-type} header. If
no such header exists, return \code{'plain'}. The subtype is
1995-03-22 15:48:46 +00:00
converted to lower case.
\end{methoddesc}