Doc/lib/libbase64.tex

   1 \section{\module{base64} ---
   2          RFC 3548: Base16, Base32, Base64 Data Encodings}
   3
   4 \declaremodule{standard}{base64}
   5 \modulesynopsis{RFC 3548: Base16, Base32, Base64 Data Encodings}
   6
   7
   8 \indexii{base64}{encoding}
   9 \index{MIME!base64 encoding}
  10
  11 This module provides data encoding and decoding as specified in
  12 \rfc{3548}.  This standard defines the Base16, Base32, and Base64
  13 algorithms for encoding and decoding arbitrary binary strings into
  14 text strings that can be safely sent by email, used as parts of URLs,
  15 or included as part of an HTTP POST request.  The encoding algorithm is
  16 not the same as the \program{uuencode} program.
  17
  18 There are two interfaces provided by this module.  The modern
  19 interface supports encoding and decoding string objects using all
  20 three alphabets.  The legacy interface provides for encoding and
  21 decoding to and from file-like objects as well as strings, but only
  22 using the Base64 standard alphabet.
  23
  24 The modern interface, which was introduced in Python 2.4, provides:
  25
  26 \begin{funcdesc}{b64encode}{s\optional{, altchars}}
  27 Encode a string use Base64.
  28
  29 \var{s} is the string to encode.  Optional \var{altchars} must be a
  30 string of at least length 2 (additional characters are ignored) which
  31 specifies an alternative alphabet for the \code{+} and \code{/}
  32 characters.  This allows an application to e.g. generate URL or
  33 filesystem safe Base64 strings.  The default is \code{None}, for which
  34 the standard Base64 alphabet is used.
  35
  36 The encoded string is returned.
  37 \end{funcdesc}
  38
  39 \begin{funcdesc}{b64decode}{s\optional{, altchars}}
  40 Decode a Base64 encoded string.
  41
  42 \var{s} is the string to decode.  Optional \var{altchars} must be a
  43 string of at least length 2 (additional characters are ignored) which
  44 specifies the alternative alphabet used instead of the \code{+} and
  45 \code{/} characters.
  46
  47 The decoded string is returned.  A \exception{TypeError} is raised if
  48 \var{s} were incorrectly padded or if there are non-alphabet
  49 characters present in the string.
  50 \end{funcdesc}
  51
  52 \begin{funcdesc}{standard_b64encode}{s}
  53 Encode string \var{s} using the standard Base64 alphabet.
  54 \end{funcdesc}
  55
  56 \begin{funcdesc}{standard_b64decode}{s}
  57 Decode string \var{s} using the standard Base64 alphabet.
  58 \end{funcdesc}
  59
  60 \begin{funcdesc}{urlsafe_b64encode}{s}
  61 Encode string \var{s} using a URL-safe alphabet, which substitutes
  62 \code{-} instead of \code{+} and \code{_} instead of \code{/} in the
  63 standard Base64 alphabet.
  64 \end{funcdesc}
  65
  66 \begin{funcdesc}{urlsafe_b64decode}{s}
  67 Decode string \var{s} using a URL-safe alphabet, which substitutes
  68 \code{-} instead of \code{+} and \code{_} instead of \code{/} in the
  69 standard Base64 alphabet.
  70 \end{funcdesc}
  71
  72 \begin{funcdesc}{b32encode}{s}
  73 Encode a string using Base32.  \var{s} is the string to encode.  The
  74 encoded string is returned.
  75 \end{funcdesc}
  76
  77 \begin{funcdesc}{b32decode}{s\optional{, casefold\optional{, map01}}}
  78 Decode a Base32 encoded string.
  79
  80 \var{s} is the string to decode.  Optional \var{casefold} is a flag
  81 specifying whether a lowercase alphabet is acceptable as input.  For
  82 security purposes, the default is \code{False}.
  83
  84 \rfc{3548} allows for optional mapping of the digit 0 (zero) to the
  85 letter O (oh), and for optional mapping of the digit 1 (one) to either
  86 the letter I (eye) or letter L (el).  The optional argument
  87 \var{map01} when not \code{None}, specifies which letter the digit 1 should
  88 be mapped to (when map01 is not \var{None}, the digit 0 is always
  89 mapped to the letter O).  For security purposes the default is
  90 \code{None}, so that 0 and 1 are not allowed in the input.
  91
  92 The decoded string is returned.  A \exception{TypeError} is raised if
  93 \var{s} were incorrectly padded or if there are non-alphabet characters
  94 present in the string.
  95 \end{funcdesc}
  96
  97 \begin{funcdesc}{b16encode}{s}
  98 Encode a string using Base16.
  99
 100 \var{s} is the string to encode.  The encoded string is returned.
 101 \end{funcdesc}
 102
 103 \begin{funcdesc}{b16decode}{s\optional{, casefold}}
 104 Decode a Base16 encoded string.
 105
 106 \var{s} is the string to decode.  Optional \var{casefold} is a flag
 107 specifying whether a lowercase alphabet is acceptable as input.  For
 108 security purposes, the default is \code{False}.
 109
 110 The decoded string is returned.  A \exception{TypeError} is raised if
 111 \var{s} were incorrectly padded or if there are non-alphabet
 112 characters present in the string.
 113 \end{funcdesc}
 114
 115 The legacy interface:
 116
 117 \begin{funcdesc}{decode}{input, output}
 118 Decode the contents of the \var{input} file and write the resulting
 119 binary data to the \var{output} file.
 120 \var{input} and \var{output} must either be file objects or objects that
 121 mimic the file object interface. \var{input} will be read until
 122 \code{\var{input}.read()} returns an empty string.
 123 \end{funcdesc}
 124
 125 \begin{funcdesc}{decodestring}{s}
 126 Decode the string \var{s}, which must contain one or more lines of
 127 base64 encoded data, and return a string containing the resulting
 128 binary data.
 129 \end{funcdesc}
 130
 131 \begin{funcdesc}{encode}{input, output}
 132 Encode the contents of the \var{input} file and write the resulting
 133 base64 encoded data to the \var{output} file.
 134 \var{input} and \var{output} must either be file objects or objects that
 135 mimic the file object interface. \var{input} will be read until
 136 \code{\var{input}.read()} returns an empty string.  \function{encode()}
 137 returns the encoded data plus a trailing newline character
 138 (\code{'\e n'}).
 139 \end{funcdesc}
 140
 141 \begin{funcdesc}{encodestring}{s}
 142 Encode the string \var{s}, which can contain arbitrary binary data,
 143 and return a string containing one or more lines of
 144 base64-encoded data.  \function{encodestring()} returns a
 145 string containing one or more lines of base64-encoded data
 146 always including an extra trailing newline (\code{'\e n'}).
 147 \end{funcdesc}
 148
 149 An example usage of the module:
 150
 151 \begin{verbatim}
 152 >>> import base64
 153 >>> encoded = base64.b64encode('data to be encoded')
 154 >>> encoded
 155 'ZGF0YSB0byBiZSBlbmNvZGVk'
 156 >>> data = base64.b64decode(encoded)
 157 >>> data
 158 'data to be encoded'
 159 \end{verbatim}
 160
 161 \begin{seealso}
 162   \seemodule{binascii}{Support module containing \ASCII-to-binary
 163                        and binary-to-\ASCII{} conversions.}
 164   \seerfc{1521}{MIME (Multipurpose Internet Mail Extensions) Part One:
 165           Mechanisms for Specifying and Describing the Format of
 166           Internet Message Bodies}{Section 5.2, ``Base64
 167           Content-Transfer-Encoding,'' provides the definition of the
 168           base64 encoding.}
 169 \end{seealso}