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