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