Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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`. |
R. David Murray | 7cefc30 | 2010-10-17 23:12:16 +0000 | [diff] [blame] | 13 | This standard defines the Base16, Base32, and Base64 algorithms for encoding |
| 14 | and decoding arbitrary binary strings into ASCII-only byte strings that can be |
| 15 | safely sent by email, used as parts of URLs, or included as part of an HTTP |
| 16 | POST request. The encoding algorithm is not the same as the |
| 17 | :program:`uuencode` program. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 18 | |
R. David Murray | 7cefc30 | 2010-10-17 23:12:16 +0000 | [diff] [blame] | 19 | There are two interfaces provided by this module. The modern interface |
| 20 | supports encoding and decoding ASCII byte string objects using all three |
| 21 | alphabets. The legacy interface provides for encoding and decoding to and from |
| 22 | file-like objects as well as byte strings, but only using the Base64 standard |
| 23 | alphabet. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 25 | The modern interface provides: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | |
Georg Brandl | b868a66 | 2009-04-02 02:56:10 +0000 | [diff] [blame] | 27 | .. function:: b64encode(s, altchars=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 28 | |
R. David Murray | 7cefc30 | 2010-10-17 23:12:16 +0000 | [diff] [blame] | 29 | Encode a byte string using Base64. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 62e4231 | 2010-08-02 20:39:35 +0000 | [diff] [blame] | 37 | The encoded byte string is returned. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 38 | |
| 39 | |
R. David Murray | 6495136 | 2010-11-11 20:09:20 +0000 | [diff] [blame] | 40 | .. function:: b64decode(s, altchars=None, validate=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 41 | |
Georg Brandl | 62e4231 | 2010-08-02 20:39:35 +0000 | [diff] [blame] | 42 | Decode a Base64 encoded byte string. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 43 | |
R. David Murray | 7cefc30 | 2010-10-17 23:12:16 +0000 | [diff] [blame] | 44 | *s* is the byte string to decode. Optional *altchars* must be a string of |
| 45 | at least length 2 (additional characters are ignored) which specifies the |
| 46 | alternative alphabet used instead of the ``+`` and ``/`` characters. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 47 | |
R. David Murray | 6495136 | 2010-11-11 20:09:20 +0000 | [diff] [blame] | 48 | The decoded string is returned. A `binascii.Error` is raised if *s* is |
| 49 | incorrectly padded. |
| 50 | |
| 51 | If *validate* is ``False`` (the default), non-base64-alphabet characters are |
| 52 | discarded prior to the padding check. If *validate* is ``True``, |
| 53 | non-base64-alphabet characters in the input result in a |
| 54 | :exc:`binascii.Error`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 55 | |
| 56 | |
| 57 | .. function:: standard_b64encode(s) |
| 58 | |
Georg Brandl | 62e4231 | 2010-08-02 20:39:35 +0000 | [diff] [blame] | 59 | Encode byte string *s* using the standard Base64 alphabet. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | |
| 61 | |
| 62 | .. function:: standard_b64decode(s) |
| 63 | |
Georg Brandl | 62e4231 | 2010-08-02 20:39:35 +0000 | [diff] [blame] | 64 | Decode byte string *s* using the standard Base64 alphabet. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 65 | |
| 66 | |
| 67 | .. function:: urlsafe_b64encode(s) |
| 68 | |
Georg Brandl | 62e4231 | 2010-08-02 20:39:35 +0000 | [diff] [blame] | 69 | Encode byte string *s* using a URL-safe alphabet, which substitutes ``-`` instead of |
Benjamin Peterson | d75fcb4 | 2009-02-19 04:22:03 +0000 | [diff] [blame] | 70 | ``+`` and ``_`` instead of ``/`` in the standard Base64 alphabet. The result |
| 71 | can still contain ``=``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 72 | |
| 73 | |
| 74 | .. function:: urlsafe_b64decode(s) |
| 75 | |
Georg Brandl | 62e4231 | 2010-08-02 20:39:35 +0000 | [diff] [blame] | 76 | Decode byte string *s* using a URL-safe alphabet, which substitutes ``-`` instead of |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 77 | ``+`` and ``_`` instead of ``/`` in the standard Base64 alphabet. |
| 78 | |
| 79 | |
| 80 | .. function:: b32encode(s) |
| 81 | |
Georg Brandl | 62e4231 | 2010-08-02 20:39:35 +0000 | [diff] [blame] | 82 | Encode a byte string using Base32. *s* is the string to encode. The encoded string |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 83 | is returned. |
| 84 | |
| 85 | |
Georg Brandl | b868a66 | 2009-04-02 02:56:10 +0000 | [diff] [blame] | 86 | .. function:: b32decode(s, casefold=False, map01=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 87 | |
Georg Brandl | 62e4231 | 2010-08-02 20:39:35 +0000 | [diff] [blame] | 88 | Decode a Base32 encoded byte string. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 89 | |
R. David Murray | 7cefc30 | 2010-10-17 23:12:16 +0000 | [diff] [blame] | 90 | *s* is the byte string to decode. Optional *casefold* is a flag specifying |
| 91 | whether a lowercase alphabet is acceptable as input. For security purposes, |
| 92 | the default is ``False``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 93 | |
| 94 | :rfc:`3548` allows for optional mapping of the digit 0 (zero) to the letter O |
| 95 | (oh), and for optional mapping of the digit 1 (one) to either the letter I (eye) |
| 96 | or letter L (el). The optional argument *map01* when not ``None``, specifies |
| 97 | which letter the digit 1 should be mapped to (when *map01* is not ``None``, the |
| 98 | digit 0 is always mapped to the letter O). For security purposes the default is |
| 99 | ``None``, so that 0 and 1 are not allowed in the input. |
| 100 | |
Georg Brandl | 62e4231 | 2010-08-02 20:39:35 +0000 | [diff] [blame] | 101 | The decoded byte string is returned. A :exc:`TypeError` is raised if *s* were |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 102 | incorrectly padded or if there are non-alphabet characters present in the |
| 103 | string. |
| 104 | |
| 105 | |
| 106 | .. function:: b16encode(s) |
| 107 | |
Georg Brandl | 62e4231 | 2010-08-02 20:39:35 +0000 | [diff] [blame] | 108 | Encode a byte string using Base16. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 109 | |
Georg Brandl | 62e4231 | 2010-08-02 20:39:35 +0000 | [diff] [blame] | 110 | *s* is the string to encode. The encoded byte string is returned. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 111 | |
| 112 | |
Georg Brandl | b868a66 | 2009-04-02 02:56:10 +0000 | [diff] [blame] | 113 | .. function:: b16decode(s, casefold=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 114 | |
Georg Brandl | 62e4231 | 2010-08-02 20:39:35 +0000 | [diff] [blame] | 115 | Decode a Base16 encoded byte string. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | |
| 117 | *s* is the string to decode. Optional *casefold* is a flag specifying whether a |
| 118 | lowercase alphabet is acceptable as input. For security purposes, the default |
| 119 | is ``False``. |
| 120 | |
Georg Brandl | 62e4231 | 2010-08-02 20:39:35 +0000 | [diff] [blame] | 121 | The decoded byte string is returned. A :exc:`TypeError` is raised if *s* were |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 122 | incorrectly padded or if there are non-alphabet characters present in the |
| 123 | string. |
| 124 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 125 | |
Georg Brandl | b54d801 | 2009-06-04 09:11:51 +0000 | [diff] [blame] | 126 | The legacy interface: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 127 | |
| 128 | .. function:: decode(input, output) |
| 129 | |
Georg Brandl | b54d801 | 2009-06-04 09:11:51 +0000 | [diff] [blame] | 130 | Decode the contents of the binary *input* file and write the resulting binary |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 131 | data to the *output* file. *input* and *output* must be :term:`file objects |
| 132 | <file object>`. *input* will be read until ``input.read()`` returns an empty |
| 133 | bytes object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 134 | |
| 135 | |
Georg Brandl | b54d801 | 2009-06-04 09:11:51 +0000 | [diff] [blame] | 136 | .. function:: decodebytes(s) |
| 137 | decodestring(s) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 138 | |
R. David Murray | 7cefc30 | 2010-10-17 23:12:16 +0000 | [diff] [blame] | 139 | Decode the byte string *s*, which must contain one or more lines of base64 |
| 140 | encoded data, and return a byte string containing the resulting binary data. |
Georg Brandl | b54d801 | 2009-06-04 09:11:51 +0000 | [diff] [blame] | 141 | ``decodestring`` is a deprecated alias. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 142 | |
| 143 | |
| 144 | .. function:: encode(input, output) |
| 145 | |
Georg Brandl | b54d801 | 2009-06-04 09:11:51 +0000 | [diff] [blame] | 146 | Encode the contents of the binary *input* file and write the resulting base64 |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 147 | encoded data to the *output* file. *input* and *output* must be :term:`file |
| 148 | objects <file object>`. *input* will be read until ``input.read()`` returns |
| 149 | an empty bytes object. :func:`encode` returns the encoded data plus a trailing |
| 150 | newline character (``b'\n'``). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 151 | |
| 152 | |
Georg Brandl | b54d801 | 2009-06-04 09:11:51 +0000 | [diff] [blame] | 153 | .. function:: encodebytes(s) |
| 154 | encodestring(s) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 155 | |
R. David Murray | 7cefc30 | 2010-10-17 23:12:16 +0000 | [diff] [blame] | 156 | Encode the byte string *s*, which can contain arbitrary binary data, and |
| 157 | return a byte string containing one or more lines of base64-encoded data. |
Georg Brandl | b54d801 | 2009-06-04 09:11:51 +0000 | [diff] [blame] | 158 | :func:`encodebytes` returns a string containing one or more lines of |
| 159 | base64-encoded data always including an extra trailing newline (``b'\n'``). |
| 160 | ``encodestring`` is a deprecated alias. |
| 161 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 162 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 163 | An example usage of the module: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 164 | |
| 165 | >>> import base64 |
Georg Brandl | 134c35b | 2010-10-17 11:36:28 +0000 | [diff] [blame] | 166 | >>> encoded = base64.b64encode(b'data to be encoded') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 167 | >>> encoded |
Georg Brandl | 38d54f7 | 2009-01-18 10:43:58 +0000 | [diff] [blame] | 168 | b'ZGF0YSB0byBiZSBlbmNvZGVk' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 169 | >>> data = base64.b64decode(encoded) |
| 170 | >>> data |
Georg Brandl | 134c35b | 2010-10-17 11:36:28 +0000 | [diff] [blame] | 171 | b'data to be encoded' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 172 | |
| 173 | |
| 174 | .. seealso:: |
| 175 | |
| 176 | Module :mod:`binascii` |
| 177 | Support module containing ASCII-to-binary and binary-to-ASCII conversions. |
| 178 | |
| 179 | :rfc:`1521` - MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies |
| 180 | Section 5.2, "Base64 Content-Transfer-Encoding," provides the definition of the |
| 181 | base64 encoding. |
| 182 | |