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.  The result
  67    can still contain ``=``.
  68
  69
  70 .. function:: urlsafe_b64decode(s)
  71
  72    Decode string *s* using a URL-safe alphabet, which substitutes ``-`` instead of
  73    ``+`` and ``_`` instead of ``/`` in the standard Base64 alphabet.
  74
  75
  76 .. function:: b32encode(s)
  77
  78    Encode a string using Base32.  *s* is the string to encode.  The encoded string
  79    is returned.
  80
  81
  82 .. function:: b32decode(s[, casefold[, map01]])
  83
  84    Decode a Base32 encoded string.
  85
  86    *s* is the string to decode.  Optional *casefold* is a flag specifying whether a
  87    lowercase alphabet is acceptable as input.  For security purposes, the default
  88    is ``False``.
  89
  90    :rfc:`3548` allows for optional mapping of the digit 0 (zero) to the letter O
  91    (oh), and for optional mapping of the digit 1 (one) to either the letter I (eye)
  92    or letter L (el).  The optional argument *map01* when not ``None``, specifies
  93    which letter the digit 1 should be mapped to (when *map01* is not ``None``, the
  94    digit 0 is always mapped to the letter O).  For security purposes the default is
  95    ``None``, so that 0 and 1 are not allowed in the input.
  96
  97    The decoded string is returned.  A :exc:`TypeError` is raised if *s* were
  98    incorrectly padded or if there are non-alphabet characters present in the
  99    string.
 100
 101
 102 .. function:: b16encode(s)
 103
 104    Encode a string using Base16.
 105
 106    *s* is the string to encode.  The encoded string is returned.
 107
 108
 109 .. function:: b16decode(s[, casefold])
 110
 111    Decode a Base16 encoded string.
 112
 113    *s* is the string to decode.  Optional *casefold* is a flag specifying whether a
 114    lowercase alphabet is acceptable as input.  For security purposes, the default
 115    is ``False``.
 116
 117    The decoded string is returned.  A :exc:`TypeError` is raised if *s* were
 118    incorrectly padded or if there are non-alphabet characters present in the
 119    string.
 120
 121 The legacy interface:
 122
 123
 124 .. function:: decode(input, output)
 125
 126    Decode the contents of the *input* file and write the resulting binary data to
 127    the *output* file. *input* and *output* must either be file objects or objects
 128    that mimic the file object interface. *input* will be read until
 129    ``input.read()`` returns an empty string.
 130
 131
 132 .. function:: decodestring(s)
 133
 134    Decode the string *s*, which must contain one or more lines of base64 encoded
 135    data, and return a string containing the resulting binary data.
 136
 137
 138 .. function:: encode(input, output)
 139
 140    Encode the contents of the *input* file and write the resulting base64 encoded
 141    data to the *output* file. *input* and *output* must either be file objects or
 142    objects that mimic the file object interface. *input* will be read until
 143    ``input.read()`` returns an empty string.  :func:`encode` returns the encoded
 144    data plus a trailing newline character (``'\n'``).
 145
 146
 147 .. function:: encodestring(s)
 148
 149    Encode the string *s*, which can contain arbitrary binary data, and return a
 150    string containing one or more lines of base64-encoded data.
 151    :func:`encodestring` returns a string containing one or more lines of
 152    base64-encoded data always including an extra trailing newline (``'\n'``).
 153
 154 An example usage of the module:
 155
 156    >>> import base64
 157    >>> encoded = base64.b64encode('data to be encoded')
 158    >>> encoded
 159    'ZGF0YSB0byBiZSBlbmNvZGVk'
 160    >>> data = base64.b64decode(encoded)
 161    >>> data
 162    'data to be encoded'
 163
 164
 165 .. seealso::
 166
 167    Module :mod:`binascii`
 168       Support module containing ASCII-to-binary and binary-to-ASCII conversions.
 169
 170    :rfc:`1521` - MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies
 171       Section 5.2, "Base64 Content-Transfer-Encoding," provides the definition of the
 172       base64 encoding.
 173