Doc/lib/libmimetools.tex

   1 \section{\module{mimetools} ---
   2          Tools for parsing MIME messages}
   3
   4 \declaremodule{standard}{mimetools}
   5 \modulesynopsis{Tools for parsing MIME style message bodies.}
   6
   7
   8 This module defines a subclass of the \class{rfc822.Message} class and
   9 a number of utility functions that are useful for the manipulation for
  10 MIME multipart or encoded message.
  11
  12 It defines the following items:
  13
  14 \begin{classdesc}{Message}{fp\optional{, seekable}}
  15 Return a new instance of the \class{Message} class.  This is a
  16 subclass of the \class{rfc822.Message} class, with some additional
  17 methods (see below).  The \var{seekable} argument has the same meaning
  18 as for \class{rfc822.Message}.
  19 \end{classdesc}
  20
  21 \begin{funcdesc}{choose_boundary}{}
  22 Return a unique string that has a high likelihood of being usable as a
  23 part boundary.  The string has the form
  24 \code{'\var{hostipaddr}.\var{uid}.\var{pid}.\var{timestamp}.\var{random}'}.
  25 \end{funcdesc}
  26
  27 \begin{funcdesc}{decode}{input, output, encoding}
  28 Read data encoded using the allowed MIME \var{encoding} from open file
  29 object \var{input} and write the decoded data to open file object
  30 \var{output}.  Valid values for \var{encoding} include
  31 \code{'base64'}, \code{'quoted-printable'} and \code{'uuencode'}.
  32 \end{funcdesc}
  33
  34 \begin{funcdesc}{encode}{input, output, encoding}
  35 Read data from open file object \var{input} and write it encoded using
  36 the allowed MIME \var{encoding} to open file object \var{output}.
  37 Valid values for \var{encoding} are the same as for \method{decode()}.
  38 \end{funcdesc}
  39
  40 \begin{funcdesc}{copyliteral}{input, output}
  41 Read lines until \EOF{} from open file \var{input} and write them to
  42 open file \var{output}.
  43 \end{funcdesc}
  44
  45 \begin{funcdesc}{copybinary}{input, output}
  46 Read blocks until \EOF{} from open file \var{input} and write them to
  47 open file \var{output}.  The block size is currently fixed at 8192.
  48 \end{funcdesc}
  49
  50
  51 \subsection{Additional Methods of Message objects}
  52 \nodename{mimetools.Message Methods}
  53
  54 The \class{Message} class defines the following methods in
  55 addition to the \class{rfc822.Message} methods:
  56
  57 \begin{methoddesc}{getplist}{}
  58 Return the parameter list of the \code{content-type} header.  This is
  59 a list if strings.  For parameters of the form
  60 \samp{\var{key}=\var{value}}, \var{key} is converted to lower case but
  61 \var{value} is not.  For example, if the message contains the header
  62 \samp{Content-type: text/html; spam=1; Spam=2; Spam} then
  63 \method{getplist()} will return the Python list \code{['spam=1',
  64 'spam=2', 'Spam']}.
  65 \end{methoddesc}
  66
  67 \begin{methoddesc}{getparam}{name}
  68 Return the \var{value} of the first parameter (as returned by
  69 \method{getplist()} of the form \samp{\var{name}=\var{value}} for the
  70 given \var{name}.  If \var{value} is surrounded by quotes of the form
  71 `\code{<}...\code{>}' or `\code{"}...\code{"}', these are removed.
  72 \end{methoddesc}
  73
  74 \begin{methoddesc}{getencoding}{}
  75 Return the encoding specified in the \code{content-transfer-encoding}
  76 message header.  If no such header exists, return \code{'7bit'}.  The
  77 encoding is converted to lower case.
  78 \end{methoddesc}
  79
  80 \begin{methoddesc}{gettype}{}
  81 Return the message type (of the form \samp{\var{type}/\var{subtype}})
  82 as specified in the \code{content-type} header.  If no such header
  83 exists, return \code{'text/plain'}.  The type is converted to lower
  84 case.
  85 \end{methoddesc}
  86
  87 \begin{methoddesc}{getmaintype}{}
  88 Return the main type as specified in the \code{content-type} header.
  89 If no such header exists, return \code{'text'}.  The main type is
  90 converted to lower case.
  91 \end{methoddesc}
  92
  93 \begin{methoddesc}{getsubtype}{}
  94 Return the subtype as specified in the \code{content-type} header.  If
  95 no such header exists, return \code{'plain'}.  The subtype is
  96 converted to lower case.
  97 \end{methoddesc}