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 \deprecated{2.3}{The \refmodule{email} package should be used in
   8                  preference to the \module{mimetools} module.  This
   9                  module is present only to maintain backward
  10                  compatibility.}
  11
  12 This module defines a subclass of the
  13 \refmodule{rfc822}\refstmodindex{rfc822} module's
  14 \class{Message} class and a number of utility functions that are
  15 useful for the manipulation for MIME multipart or encoded message.
  16
  17 It defines the following items:
  18
  19 \begin{classdesc}{Message}{fp\optional{, seekable}}
  20 Return a new instance of the \class{Message} class.  This is a
  21 subclass of the \class{rfc822.Message} class, with some additional
  22 methods (see below).  The \var{seekable} argument has the same meaning
  23 as for \class{rfc822.Message}.
  24 \end{classdesc}
  25
  26 \begin{funcdesc}{choose_boundary}{}
  27 Return a unique string that has a high likelihood of being usable as a
  28 part boundary.  The string has the form
  29 \code{'\var{hostipaddr}.\var{uid}.\var{pid}.\var{timestamp}.\var{random}'}.
  30 \end{funcdesc}
  31
  32 \begin{funcdesc}{decode}{input, output, encoding}
  33 Read data encoded using the allowed MIME \var{encoding} from open file
  34 object \var{input} and write the decoded data to open file object
  35 \var{output}.  Valid values for \var{encoding} include
  36 \code{'base64'}, \code{'quoted-printable'}, \code{'uuencode'},
  37 \code{'x-uuencode'}, \code{'uue'}, \code{'x-uue'}, \code{'7bit'}, and
  38 \code{'8bit'}.  Decoding messages encoded in \code{'7bit'} or \code{'8bit'}
  39 has no effect.  The input is simply copied to the output.
  40 \end{funcdesc}
  41
  42 \begin{funcdesc}{encode}{input, output, encoding}
  43 Read data from open file object \var{input} and write it encoded using
  44 the allowed MIME \var{encoding} to open file object \var{output}.
  45 Valid values for \var{encoding} are the same as for \method{decode()}.
  46 \end{funcdesc}
  47
  48 \begin{funcdesc}{copyliteral}{input, output}
  49 Read lines from open file \var{input} until \EOF{} and write them to
  50 open file \var{output}.
  51 \end{funcdesc}
  52
  53 \begin{funcdesc}{copybinary}{input, output}
  54 Read blocks until \EOF{} from open file \var{input} and write them to
  55 open file \var{output}.  The block size is currently fixed at 8192.
  56 \end{funcdesc}
  57
  58
  59 \begin{seealso}
  60   \seemodule{email}{Comprehensive email handling package; supercedes
  61                     the \module{mimetools} module.}
  62   \seemodule{rfc822}{Provides the base class for
  63                      \class{mimetools.Message}.}
  64   \seemodule{multifile}{Support for reading files which contain
  65                         distinct parts, such as MIME data.}
  66   \seeurl{http://www.cs.uu.nl/wais/html/na-dir/mail/mime-faq/.html}{
  67           The MIME Frequently Asked Questions document.  For an
  68           overview of MIME, see the answer to question 1.1 in Part 1
  69           of this document.}
  70 \end{seealso}
  71
  72
  73 \subsection{Additional Methods of Message Objects
  74             \label{mimetools-message-objects}}
  75
  76 The \class{Message} class defines the following methods in
  77 addition to the \class{rfc822.Message} methods:
  78
  79 \begin{methoddesc}{getplist}{}
  80 Return the parameter list of the \mailheader{Content-Type} header.
  81 This is a list of strings.  For parameters of the form
  82 \samp{\var{key}=\var{value}}, \var{key} is converted to lower case but
  83 \var{value} is not.  For example, if the message contains the header
  84 \samp{Content-type: text/html; spam=1; Spam=2; Spam} then
  85 \method{getplist()} will return the Python list \code{['spam=1',
  86 'spam=2', 'Spam']}.
  87 \end{methoddesc}
  88
  89 \begin{methoddesc}{getparam}{name}
  90 Return the \var{value} of the first parameter (as returned by
  91 \method{getplist()} of the form \samp{\var{name}=\var{value}} for the
  92 given \var{name}.  If \var{value} is surrounded by quotes of the form
  93 `\code{<}...\code{>}' or `\code{"}...\code{"}', these are removed.
  94 \end{methoddesc}
  95
  96 \begin{methoddesc}{getencoding}{}
  97 Return the encoding specified in the
  98 \mailheader{Content-Transfer-Encoding} message header.  If no such
  99 header exists, return \code{'7bit'}.  The encoding is converted to
 100 lower case.
 101 \end{methoddesc}
 102
 103 \begin{methoddesc}{gettype}{}
 104 Return the message type (of the form \samp{\var{type}/\var{subtype}})
 105 as specified in the \mailheader{Content-Type} header.  If no such
 106 header exists, return \code{'text/plain'}.  The type is converted to
 107 lower case.
 108 \end{methoddesc}
 109
 110 \begin{methoddesc}{getmaintype}{}
 111 Return the main type as specified in the \mailheader{Content-Type}
 112 header.  If no such header exists, return \code{'text'}.  The main
 113 type is converted to lower case.
 114 \end{methoddesc}
 115
 116 \begin{methoddesc}{getsubtype}{}
 117 Return the subtype as specified in the \mailheader{Content-Type}
 118 header.  If no such header exists, return \code{'plain'}.  The subtype
 119 is converted to lower case.
 120 \end{methoddesc}