Doc/lib/libbase64.tex

   1 \section{\module{base64} ---
   2          Encode and decode MIME base64 data}
   3
   4 \declaremodule{standard}{base64}
   5 \modulesynopsis{Encode and decode files using the MIME base64 data.}
   6
   7
   8 \indexii{base64}{encoding}
   9 \index{MIME!base64 encoding}
  10
  11 This module performs base64 encoding and decoding of arbitrary binary
  12 strings into text strings that can be safely sent by email or included
  13 as part of an HTTP POST request.  The
  14 encoding scheme is defined in \rfc{1521} (\emph{MIME
  15 (Multipurpose Internet Mail Extensions) Part One: Mechanisms for
  16 Specifying and Describing the Format of Internet Message Bodies},
  17 section 5.2, ``Base64 Content-Transfer-Encoding'') and is used for
  18 MIME email and various other Internet-related applications; it is not
  19 the same as the output produced by the \program{uuencode} program.
  20 For example, the string \code{'www.python.org'} is encoded as the
  21 string \code{'d3d3LnB5dGhvbi5vcmc=\e n'}.
  22
  23
  24 \begin{funcdesc}{decode}{input, output}
  25 Decode the contents of the \var{input} file and write the resulting
  26 binary data to the \var{output} file.
  27 \var{input} and \var{output} must either be file objects or objects that
  28 mimic the file object interface. \var{input} will be read until
  29 \code{\var{input}.read()} returns an empty string.
  30 \end{funcdesc}
  31
  32 \begin{funcdesc}{decodestring}{s}
  33 Decode the string \var{s}, which must contain one or more lines of
  34 base64 encoded data, and return a string containing the resulting
  35 binary data.
  36 \end{funcdesc}
  37
  38 \begin{funcdesc}{encode}{input, output}
  39 Encode the contents of the \var{input} file and write the resulting
  40 base64 encoded data to the \var{output} file.
  41 \var{input} and \var{output} must either be file objects or objects that
  42 mimic the file object interface. \var{input} will be read until
  43 \code{\var{input}.read()} returns an empty string.  \function{encode()}
  44 returns the encoded data plus a trailing newline character
  45 (\code{'\e n'}).
  46 \end{funcdesc}
  47
  48 \begin{funcdesc}{encodestring}{s}
  49 Encode the string \var{s}, which can contain arbitrary binary data,
  50 and return a string containing one or more lines of
  51 base64-encoded data.  \function{encodestring()} returns a
  52 string containing one or more lines of base64-encoded data
  53 always including an extra trailing newline (\code{'\e n'}).
  54 \end{funcdesc}
  55
  56 \begin{seealso}
  57   \seemodule{binascii}{Support module containing \ASCII-to-binary
  58                        and binary-to-\ASCII{} conversions.}
  59   \seerfc{1521}{MIME (Multipurpose Internet Mail Extensions) Part One:
  60           Mechanisms for Specifying and Describing the Format of
  61           Internet Message Bodies}{Section 5.2, ``Base64
  62           Content-Transfer-Encoding,'' provides the definition of the
  63           base64 encoding.}
  64 \end{seealso}