Debian Codegraph @

Doc/library/base64.rst

raw
1 :mod:`!base64` --- Base16, Base32, Base64, Base85 Data Encodings
2 ================================================================
3
4 .. module:: base64
5 :synopsis: RFC 4648: Base16, Base32, Base64 Data Encodings;
6 Base85 and Ascii85
7
8 **Source code:** :source:`Lib/base64.py`
9
10 .. index::
11 pair: base64; encoding
12 single: MIME; base64 encoding
13
14 --------------
15
16 This module provides functions for encoding binary data to printable
17 ASCII characters and decoding such encodings back to binary data.
18 This includes the :ref:`encodings specified in <base64-rfc-4648>`
19 :rfc:`4648` (Base64, Base32 and Base16)
20 and the non-standard :ref:`Base85 encodings <base64-base-85>`.
21
22 There are two interfaces provided by this module. The modern interface
23 supports encoding :term:`bytes-like objects <bytes-like object>` to ASCII
24 :class:`bytes`, and decoding :term:`bytes-like objects <bytes-like object>` or
25 strings containing ASCII to :class:`bytes`. Both base-64 alphabets
26 defined in :rfc:`4648` (normal, and URL- and filesystem-safe) are supported.
27
28 The :ref:`legacy interface <base64-legacy>` does not support decoding from strings, but it does
29 provide functions for encoding and decoding to and from :term:`file objects
30 <file object>`. It only supports the Base64 standard alphabet, and it adds
31 newlines every 76 characters as per :rfc:`2045`. Note that if you are looking
32 for :rfc:`2045` support you probably want to be looking at the :mod:`email`
33 package instead.
34
35
36 .. versionchanged:: 3.3
37 ASCII-only Unicode strings are now accepted by the decoding functions of
38 the modern interface.
39
40 .. versionchanged:: 3.4
41 Any :term:`bytes-like objects <bytes-like object>` are now accepted by all
42 encoding and decoding functions in this module. Ascii85/Base85 support added.
43
44
45 .. _base64-rfc-4648:
46
47 RFC 4648 Encodings
48 ------------------
49
50 The :rfc:`4648` encodings are suitable for encoding binary data so that it can be
51 safely sent by email, used as parts of URLs, or included as part of an HTTP
52 POST request.
53
54 .. function:: b64encode(s, altchars=None)
55
56 Encode the :term:`bytes-like object` *s* using Base64 and return the encoded
57 :class:`bytes`.
58
59 Optional *altchars* must be a :term:`bytes-like object` of length 2 which
60 specifies an alternative alphabet for the ``+`` and ``/`` characters.
61 This allows an application to e.g. generate URL or filesystem safe Base64
62 strings. The default is ``None``, for which the standard Base64 alphabet is used.
63
64 May assert or raise a :exc:`ValueError` if the length of *altchars* is not 2. Raises a
65 :exc:`TypeError` if *altchars* is not a :term:`bytes-like object`.
66
67
68 .. function:: b64decode(s, altchars=None, validate=False)
69
70 Decode the Base64 encoded :term:`bytes-like object` or ASCII string
71 *s* and return the decoded :class:`bytes`.
72
73 Optional *altchars* must be a :term:`bytes-like object` or ASCII string
74 of length 2 which specifies the alternative alphabet used instead of the
75 ``+`` and ``/`` characters.
76
77 A :exc:`binascii.Error` exception is raised
78 if *s* is incorrectly padded.
79
80 If *validate* is ``False`` (the default), characters that are neither
81 in the normal base-64 alphabet nor the alternative alphabet are
82 discarded prior to the padding check. If *validate* is ``True``,
83 these non-alphabet characters in the input result in a
84 :exc:`binascii.Error`.
85
86 For more information about the strict base64 check, see :func:`binascii.a2b_base64`
87
88 May assert or raise a :exc:`ValueError` if the length of *altchars* is not 2.
89
90 .. function:: standard_b64encode(s)
91
92 Encode :term:`bytes-like object` *s* using the standard Base64 alphabet
93 and return the encoded :class:`bytes`.
94
95
96 .. function:: standard_b64decode(s)
97
98 Decode :term:`bytes-like object` or ASCII string *s* using the standard
99 Base64 alphabet and return the decoded :class:`bytes`.
100
101
102 .. function:: urlsafe_b64encode(s)
103
104 Encode :term:`bytes-like object` *s* using the
105 URL- and filesystem-safe alphabet, which
106 substitutes ``-`` instead of ``+`` and ``_`` instead of ``/`` in the
107 standard Base64 alphabet, and return the encoded :class:`bytes`. The result
108 can still contain ``=``.
109
110
111 .. function:: urlsafe_b64decode(s)
112
113 Decode :term:`bytes-like object` or ASCII string *s*
114 using the URL- and filesystem-safe
115 alphabet, which substitutes ``-`` instead of ``+`` and ``_`` instead of
116 ``/`` in the standard Base64 alphabet, and return the decoded
117 :class:`bytes`.
118
119
120 .. function:: b32encode(s)
121
122 Encode the :term:`bytes-like object` *s* using Base32 and return the
123 encoded :class:`bytes`.
124
125
126 .. function:: b32decode(s, casefold=False, map01=None)
127
128 Decode the Base32 encoded :term:`bytes-like object` or ASCII string *s* and
129 return the decoded :class:`bytes`.
130
131 Optional *casefold* is a flag specifying
132 whether a lowercase alphabet is acceptable as input. For security purposes,
133 the default is ``False``.
134
135 :rfc:`4648` allows for optional mapping of the digit 0 (zero) to the letter O
136 (oh), and for optional mapping of the digit 1 (one) to either the letter I (eye)
137 or letter L (el). The optional argument *map01* when not ``None``, specifies
138 which letter the digit 1 should be mapped to (when *map01* is not ``None``, the
139 digit 0 is always mapped to the letter O). For security purposes the default is
140 ``None``, so that 0 and 1 are not allowed in the input.
141
142 A :exc:`binascii.Error` is raised if *s* is
143 incorrectly padded or if there are non-alphabet characters present in the
144 input.
145
146
147 .. function:: b32hexencode(s)
148
149 Similar to :func:`b32encode` but uses the Extended Hex Alphabet, as defined in
150 :rfc:`4648`.
151
152 .. versionadded:: 3.10
153
154
155 .. function:: b32hexdecode(s, casefold=False)
156
157 Similar to :func:`b32decode` but uses the Extended Hex Alphabet, as defined in
158 :rfc:`4648`.
159
160 This version does not allow the digit 0 (zero) to the letter O (oh) and digit
161 1 (one) to either the letter I (eye) or letter L (el) mappings, all these
162 characters are included in the Extended Hex Alphabet and are not
163 interchangeable.
164
165 .. versionadded:: 3.10
166
167
168 .. function:: b16encode(s)
169
170 Encode the :term:`bytes-like object` *s* using Base16 and return the
171 encoded :class:`bytes`.
172
173
174 .. function:: b16decode(s, casefold=False)
175
176 Decode the Base16 encoded :term:`bytes-like object` or ASCII string *s* and
177 return the decoded :class:`bytes`.
178
179 Optional *casefold* is a flag specifying whether a
180 lowercase alphabet is acceptable as input. For security purposes, the default
181 is ``False``.
182
183 A :exc:`binascii.Error` is raised if *s* is
184 incorrectly padded or if there are non-alphabet characters present in the
185 input.
186
187 .. _base64-base-85:
188
189 Base85 Encodings
190 -----------------
191
192 Base85 encoding is not formally specified but rather a de facto standard,
193 thus different systems perform the encoding differently.
194
195 The :func:`a85encode` and :func:`b85encode` functions in this module are two implementations of
196 the de facto standard. You should call the function with the Base85
197 implementation used by the software you intend to work with.
198
199 The two functions present in this module differ in how they handle the following:
200
201 * Whether to include enclosing ``<~`` and ``~>`` markers
202 * Whether to include newline characters
203 * The set of ASCII characters used for encoding
204 * Handling of null bytes
205
206 Refer to the documentation of the individual functions for more information.
207
208 .. function:: a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)
209
210 Encode the :term:`bytes-like object` *b* using Ascii85 and return the
211 encoded :class:`bytes`.
212
213 *foldspaces* is an optional flag that uses the special short sequence 'y'
214 instead of 4 consecutive spaces (ASCII 0x20) as supported by 'btoa'. This
215 feature is not supported by the "standard" Ascii85 encoding.
216
217 *wrapcol* controls whether the output should have newline (``b'\n'``)
218 characters added to it. If this is non-zero, each output line will be
219 at most this many characters long, excluding the trailing newline.
220
221 *pad* controls whether the input is padded to a multiple of 4
222 before encoding. Note that the ``btoa`` implementation always pads.
223
224 *adobe* controls whether the encoded byte sequence is framed with ``<~``
225 and ``~>``, which is used by the Adobe implementation.
226
227 .. versionadded:: 3.4
228
229
230 .. function:: a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\v')
231
232 Decode the Ascii85 encoded :term:`bytes-like object` or ASCII string *b* and
233 return the decoded :class:`bytes`.
234
235 *foldspaces* is a flag that specifies whether the 'y' short sequence
236 should be accepted as shorthand for 4 consecutive spaces (ASCII 0x20).
237 This feature is not supported by the "standard" Ascii85 encoding.
238
239 *adobe* controls whether the input sequence is in Adobe Ascii85 format
240 (i.e. is framed with <~ and ~>).
241
242 *ignorechars* should be a byte string containing characters to ignore
243 from the input. This should only contain whitespace characters, and by
244 default contains all whitespace characters in ASCII.
245
246 .. versionadded:: 3.4
247
248
249 .. function:: b85encode(b, pad=False)
250
251 Encode the :term:`bytes-like object` *b* using base85 (as used in e.g.
252 git-style binary diffs) and return the encoded :class:`bytes`.
253
254 If *pad* is true, the input is padded with ``b'\0'`` so its length is a
255 multiple of 4 bytes before encoding.
256
257 .. versionadded:: 3.4
258
259
260 .. function:: b85decode(b)
261
262 Decode the base85-encoded :term:`bytes-like object` or ASCII string *b* and
263 return the decoded :class:`bytes`. Padding is implicitly removed, if
264 necessary.
265
266 .. versionadded:: 3.4
267
268
269 .. function:: z85encode(s)
270
271 Encode the :term:`bytes-like object` *s* using Z85 (as used in ZeroMQ)
272 and return the encoded :class:`bytes`. See `Z85 specification
273 <https://rfc.zeromq.org/spec/32/>`_ for more information.
274
275 .. versionadded:: 3.13
276
277
278 .. function:: z85decode(s)
279
280 Decode the Z85-encoded :term:`bytes-like object` or ASCII string *s* and
281 return the decoded :class:`bytes`. See `Z85 specification
282 <https://rfc.zeromq.org/spec/32/>`_ for more information.
283
284 .. versionadded:: 3.13
285
286
287 .. _base64-legacy:
288
289 Legacy Interface
290 ----------------
291
292 .. function:: decode(input, output)
293
294 Decode the contents of the binary *input* file and write the resulting binary
295 data to the *output* file. *input* and *output* must be :term:`file objects
296 <file object>`. *input* will be read until ``input.readline()`` returns an
297 empty bytes object.
298
299
300 .. function:: decodebytes(s)
301
302 Decode the :term:`bytes-like object` *s*, which must contain one or more
303 lines of base64 encoded data, and return the decoded :class:`bytes`.
304
305 .. versionadded:: 3.1
306
307
308 .. function:: encode(input, output)
309
310 Encode the contents of the binary *input* file and write the resulting base64
311 encoded data to the *output* file. *input* and *output* must be :term:`file
312 objects <file object>`. *input* will be read until ``input.read()`` returns
313 an empty bytes object. :func:`encode` inserts a newline character (``b'\n'``)
314 after every 76 bytes of the output, as well as ensuring that the output
315 always ends with a newline, as per :rfc:`2045` (MIME).
316
317
318 .. function:: encodebytes(s)
319
320 Encode the :term:`bytes-like object` *s*, which can contain arbitrary binary
321 data, and return :class:`bytes` containing the base64-encoded data, with newlines
322 (``b'\n'``) inserted after every 76 bytes of output, and ensuring that
323 there is a trailing newline, as per :rfc:`2045` (MIME).
324
325 .. versionadded:: 3.1
326
327
328 An example usage of the module:
329
330 >>> import base64
331 >>> encoded = base64.b64encode(b'data to be encoded')
332 >>> encoded
333 b'ZGF0YSB0byBiZSBlbmNvZGVk'
334 >>> data = base64.b64decode(encoded)
335 >>> data
336 b'data to be encoded'
337
338 .. _base64-security:
339
340 Security Considerations
341 -----------------------
342
343 A new security considerations section was added to :rfc:`4648` (section 12); it's
344 recommended to review the security section for any code deployed to production.
345
346 .. seealso::
347
348 Module :mod:`binascii`
349 Support module containing ASCII-to-binary and binary-to-ASCII conversions.
350
351 :rfc:`1521` - MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies
352 Section 5.2, "Base64 Content-Transfer-Encoding," provides the definition of the
353 base64 encoding.
354