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 12 This module provides data encoding and decoding as specified in :rfc:`3548`. 13 This standard defines the Base16, Base32, and Base64 algorithms for encoding and 14 decoding arbitrary binary strings into text strings that can be safely sent by 15 email, used as parts of URLs, or included as part of an HTTP POST request. The 16 encoding algorithm is not the same as the :program:`uuencode` program. 17 18 There are two interfaces provided by this module. The modern interface supports 19 encoding and decoding string objects using both base-64 alphabets defined 20 in :rfc:`3548` (normal, and URL- and filesystem-safe). 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 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 124 The 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 157 An 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
