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