Doc/library/base64.rst

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