Doc/lib/libuu.tex

   1 \section{\module{uu} ---
   2          Encode and decode uuencode files}
   3
   4 \declaremodule{standard}{uu}
   5 \modulesynopsis{Encode and decode files in uuencode format.}
   6 \moduleauthor{Lance Ellinghouse}{}
   7
   8
   9 This module encodes and decodes files in uuencode format, allowing
  10 arbitrary binary data to be transferred over ASCII-only connections.
  11 Wherever a file argument is expected, the methods accept a file-like
  12 object.  For backwards compatibility, a string containing a pathname
  13 is also accepted, and the corresponding file will be opened for
  14 reading and writing; the pathname \code{'-'} is understood to mean the
  15 standard input or output.  However, this interface is deprecated; it's
  16 better for the caller to open the file itself, and be sure that, when
  17 required, the mode is \code{'rb'} or \code{'wb'} on Windows.
  18
  19 This code was contributed by Lance Ellinghouse, and modified by Jack
  20 Jansen.
  21 \index{Jansen, Jack}
  22 \index{Ellinghouse, Lance}
  23
  24 The \module{uu} module defines the following functions:
  25
  26 \begin{funcdesc}{encode}{in_file, out_file\optional{, name\optional{, mode}}}
  27   Uuencode file \var{in_file} into file \var{out_file}.  The uuencoded
  28   file will have the header specifying \var{name} and \var{mode} as
  29   the defaults for the results of decoding the file. The default
  30   defaults are taken from \var{in_file}, or \code{'-'} and \code{0666}
  31   respectively.
  32 \end{funcdesc}
  33
  34 \begin{funcdesc}{decode}{in_file\optional{, out_file\optional{, mode\optional{, quiet}}}}
  35   This call decodes uuencoded file \var{in_file} placing the result on
  36   file \var{out_file}. If \var{out_file} is a pathname, \var{mode} is
  37   used to set the permission bits if the file must be
  38   created. Defaults for \var{out_file} and \var{mode} are taken from
  39   the uuencode header.  However, if the file specified in the header
  40   already exists, a \exception{uu.Error} is raised.
  41
  42   \function{decode()} may print a warning to standard error if the
  43   input was produced by an incorrect uuencoder and Python could
  44   recover from that error.  Setting \var{quiet} to a true value
  45   silences this warning.
  46 \end{funcdesc}
  47
  48 \begin{excclassdesc}{Error}{}
  49   Subclass of \exception{Exception}, this can be raised by
  50   \function{uu.decode()} under various situations, such as described
  51   above, but also including a badly formatted header, or truncated
  52   input file.
  53 \end{excclassdesc}
  54
  55 \begin{seealso}
  56   \seemodule{binascii}{Support module containing \ASCII-to-binary
  57                        and binary-to-\ASCII{} conversions.}
  58 \end{seealso}