blob: 54d1fe04a3ff7efd5f0691f127ecbfbb0e3693d3 [file] [log] [blame]
Fred Drakefc576191998-04-04 07:15:02 +00001\section{Standard Module \module{mimetools}}
Guido van Rossume47da0a1997-07-17 16:34:52 +00002\label{module-mimetools}
Guido van Rossuma12ef941995-02-27 17:53:25 +00003\stmodindex{mimetools}
Guido van Rossum86751151995-02-28 17:14:32 +00004
Guido van Rossum86751151995-02-28 17:14:32 +00005
Fred Drake0f51fff1998-03-14 06:16:57 +00006This module defines a subclass of the \class{rfc822.Message} class and
Guido van Rossumcca8d2b1995-03-22 15:48:46 +00007a number of utility functions that are useful for the manipulation for
Fred Drake0f51fff1998-03-14 06:16:57 +00008MIME multipart or encoded message.
Guido van Rossumcca8d2b1995-03-22 15:48:46 +00009
10It defines the following items:
11
Fred Drake0f51fff1998-03-14 06:16:57 +000012\begin{classdesc}{Message}{fp\optional{, seekable}}
13Return a new instance of the \class{Message} class. This is a
14subclass of the \class{rfc822.Message} class, with some additional
15methods (see below). The \var{seekable} argument has the same meaning
16as for \class{rfc822.Message}.
17\end{classdesc}
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000018
19\begin{funcdesc}{choose_boundary}{}
20Return a unique string that has a high likelihood of being usable as a
21part boundary. The string has the form
Fred Drake0f51fff1998-03-14 06:16:57 +000022\code{'\var{hostipaddr}.\var{uid}.\var{pid}.\var{timestamp}.\var{random}'}.
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000023\end{funcdesc}
24
Fred Drake0f51fff1998-03-14 06:16:57 +000025\begin{funcdesc}{decode}{input, output, encoding}
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000026Read data encoded using the allowed MIME \var{encoding} from open file
27object \var{input} and write the decoded data to open file object
28\var{output}. Valid values for \var{encoding} include
Fred Drake0f51fff1998-03-14 06:16:57 +000029\code{'base64'}, \code{'quoted-printable'} and \code{'uuencode'}.
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000030\end{funcdesc}
31
Fred Drakecce10901998-03-17 06:33:25 +000032\begin{funcdesc}{encode}{input, output, encoding}
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000033Read data from open file object \var{input} and write it encoded using
34the allowed MIME \var{encoding} to open file object \var{output}.
Fred Drake0f51fff1998-03-14 06:16:57 +000035Valid values for \var{encoding} are the same as for \method{decode()}.
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000036\end{funcdesc}
37
Fred Drakecce10901998-03-17 06:33:25 +000038\begin{funcdesc}{copyliteral}{input, output}
Fred Drake01dbb881998-02-13 22:13:07 +000039Read lines until \EOF{} from open file \var{input} and write them to
40open file \var{output}.
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000041\end{funcdesc}
42
Fred Drakecce10901998-03-17 06:33:25 +000043\begin{funcdesc}{copybinary}{input, output}
Fred Drake01dbb881998-02-13 22:13:07 +000044Read blocks until \EOF{} from open file \var{input} and write them to
45open file \var{output}. The block size is currently fixed at 8192.
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000046\end{funcdesc}
47
48
Guido van Rossumecde7811995-03-28 13:35:14 +000049\subsection{Additional Methods of Message objects}
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000050\nodename{mimetools.Message Methods}
51
Fred Drake0f51fff1998-03-14 06:16:57 +000052The \class{Message} class defines the following methods in
53addition to the \class{rfc822.Message} methods:
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000054
Fred Drakefc576191998-04-04 07:15:02 +000055\begin{methoddesc}{getplist}{}
Fred Drake0f51fff1998-03-14 06:16:57 +000056Return the parameter list of the \code{content-type} header. This is
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000057a list if strings. For parameters of the form
58\samp{\var{key}=\var{value}}, \var{key} is converted to lower case but
59\var{value} is not. For example, if the message contains the header
60\samp{Content-type: text/html; spam=1; Spam=2; Spam} then
Fred Drake0f51fff1998-03-14 06:16:57 +000061\method{getplist()} will return the Python list \code{['spam=1',
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000062'spam=2', 'Spam']}.
Fred Drakefc576191998-04-04 07:15:02 +000063\end{methoddesc}
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000064
Fred Drakefc576191998-04-04 07:15:02 +000065\begin{methoddesc}{getparam}{name}
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000066Return the \var{value} of the first parameter (as returned by
Fred Drake0f51fff1998-03-14 06:16:57 +000067\method{getplist()} of the form \samp{\var{name}=\var{value}} for the
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000068given \var{name}. If \var{value} is surrounded by quotes of the form
Fred Drake01dbb881998-02-13 22:13:07 +000069`\code{<}...\code{>}' or `\code{"}...\code{"}', these are removed.
Fred Drakefc576191998-04-04 07:15:02 +000070\end{methoddesc}
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000071
Fred Drakefc576191998-04-04 07:15:02 +000072\begin{methoddesc}{getencoding}{}
Fred Drake0f51fff1998-03-14 06:16:57 +000073Return the encoding specified in the \code{content-transfer-encoding}
74message header. If no such header exists, return \code{'7bit'}. The
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000075encoding is converted to lower case.
Fred Drakefc576191998-04-04 07:15:02 +000076\end{methoddesc}
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000077
Fred Drakefc576191998-04-04 07:15:02 +000078\begin{methoddesc}{gettype}{}
Fred Drake4b3f0311996-12-13 22:04:31 +000079Return the message type (of the form \samp{\var{type}/\var{subtype}})
Fred Drake0f51fff1998-03-14 06:16:57 +000080as specified in the \code{content-type} header. If no such header
81exists, return \code{'text/plain'}. The type is converted to lower
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000082case.
Fred Drakefc576191998-04-04 07:15:02 +000083\end{methoddesc}
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000084
Fred Drakefc576191998-04-04 07:15:02 +000085\begin{methoddesc}{getmaintype}{}
Fred Drake0f51fff1998-03-14 06:16:57 +000086Return the main type as specified in the \code{content-type} header.
87If no such header exists, return \code{'text'}. The main type is
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000088converted to lower case.
Fred Drakefc576191998-04-04 07:15:02 +000089\end{methoddesc}
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000090
Fred Drakefc576191998-04-04 07:15:02 +000091\begin{methoddesc}{getsubtype}{}
Fred Drake0f51fff1998-03-14 06:16:57 +000092Return the subtype as specified in the \code{content-type} header. If
93no such header exists, return \code{'plain'}. The subtype is
Guido van Rossumcca8d2b1995-03-22 15:48:46 +000094converted to lower case.
Fred Drakefc576191998-04-04 07:15:02 +000095\end{methoddesc}