Doc/libmimetools.tex

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