Doc/library/uu.rst

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