Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 1 | :mod:`base64` --- Base16, Base32, Base64, Base85 Data Encodings |
| 2 | =============================================================== |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | |
| 4 | .. module:: base64 |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 5 | :synopsis: RFC 3548: Base16, Base32, Base64 Data Encodings; |
| 6 | Base85 and Ascii85 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 8 | **Source code:** :source:`Lib/base64.py` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 9 | |
| 10 | .. index:: |
| 11 | pair: base64; encoding |
| 12 | single: MIME; base64 encoding |
| 13 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 14 | -------------- |
| 15 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 16 | This module provides functions for encoding binary data to printable |
| 17 | ASCII characters and decoding such encodings back to binary data. |
| 18 | It provides encoding and decoding functions for the encodings specified in |
Serhiy Storchaka | 56a6d85 | 2014-12-01 18:28:43 +0200 | [diff] [blame] | 19 | :rfc:`3548`, which defines the Base16, Base32, and Base64 algorithms, |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 20 | and for the de-facto standard Ascii85 and Base85 encodings. |
| 21 | |
| 22 | The :rfc:`3548` encodings are suitable for encoding binary data so that it can |
R. David Murray | 7cefc30 | 2010-10-17 23:12:16 +0000 | [diff] [blame] | 23 | safely sent by email, used as parts of URLs, or included as part of an HTTP |
| 24 | POST request. The encoding algorithm is not the same as the |
| 25 | :program:`uuencode` program. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 27 | There are two interfaces provided by this module. The modern interface |
| 28 | supports encoding :term:`bytes-like objects <bytes-like object>` to ASCII |
| 29 | :class:`bytes`, and decoding :term:`bytes-like objects <bytes-like object>` or |
Martin Panter | ee3074e | 2016-02-23 22:30:50 +0000 | [diff] [blame] | 30 | strings containing ASCII to :class:`bytes`. Both base-64 alphabets |
| 31 | defined in :rfc:`3548` (normal, and URL- and filesystem-safe) are supported. |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 32 | |
| 33 | The legacy interface does not support decoding from strings, but it does |
| 34 | provide functions for encoding and decoding to and from :term:`file objects |
| 35 | <file object>`. It only supports the Base64 standard alphabet, and it adds |
| 36 | newlines every 76 characters as per :rfc:`2045`. Note that if you are looking |
| 37 | for :rfc:`2045` support you probably want to be looking at the :mod:`email` |
| 38 | package instead. |
| 39 | |
Antoine Pitrou | ea6b4d5 | 2012-02-20 19:30:23 +0100 | [diff] [blame] | 40 | |
| 41 | .. versionchanged:: 3.3 |
| 42 | ASCII-only Unicode strings are now accepted by the decoding functions of |
| 43 | the modern interface. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 44 | |
Nick Coghlan | fdf239a | 2013-10-03 00:43:22 +1000 | [diff] [blame] | 45 | .. versionchanged:: 3.4 |
Serhiy Storchaka | e5ea1ab | 2016-05-18 13:54:54 +0300 | [diff] [blame] | 46 | Any :term:`bytes-like objects <bytes-like object>` are now accepted by all |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 47 | encoding and decoding functions in this module. Ascii85/Base85 support added. |
Nick Coghlan | fdf239a | 2013-10-03 00:43:22 +1000 | [diff] [blame] | 48 | |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 49 | The modern interface provides: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 50 | |
Georg Brandl | b868a66 | 2009-04-02 02:56:10 +0000 | [diff] [blame] | 51 | .. function:: b64encode(s, altchars=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 52 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 53 | Encode the :term:`bytes-like object` *s* using Base64 and return the encoded |
| 54 | :class:`bytes`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 55 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 56 | Optional *altchars* must be a :term:`bytes-like object` of at least |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | length 2 (additional characters are ignored) which specifies an alternative |
| 58 | alphabet for the ``+`` and ``/`` characters. This allows an application to e.g. |
| 59 | generate URL or filesystem safe Base64 strings. The default is ``None``, for |
| 60 | which the standard Base64 alphabet is used. |
| 61 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 62 | |
R. David Murray | 6495136 | 2010-11-11 20:09:20 +0000 | [diff] [blame] | 63 | .. function:: b64decode(s, altchars=None, validate=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 64 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 65 | Decode the Base64 encoded :term:`bytes-like object` or ASCII string |
| 66 | *s* and return the decoded :class:`bytes`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 67 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 68 | Optional *altchars* must be a :term:`bytes-like object` or ASCII string of |
R. David Murray | 7cefc30 | 2010-10-17 23:12:16 +0000 | [diff] [blame] | 69 | at least length 2 (additional characters are ignored) which specifies the |
| 70 | alternative alphabet used instead of the ``+`` and ``/`` characters. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 72 | A :exc:`binascii.Error` exception is raised |
Éric Araujo | 941afed | 2011-09-01 02:47:34 +0200 | [diff] [blame] | 73 | if *s* is incorrectly padded. |
R. David Murray | 6495136 | 2010-11-11 20:09:20 +0000 | [diff] [blame] | 74 | |
Martin Panter | ee3074e | 2016-02-23 22:30:50 +0000 | [diff] [blame] | 75 | If *validate* is ``False`` (the default), characters that are neither |
| 76 | in the normal base-64 alphabet nor the alternative alphabet are |
R. David Murray | 6495136 | 2010-11-11 20:09:20 +0000 | [diff] [blame] | 77 | discarded prior to the padding check. If *validate* is ``True``, |
Martin Panter | ee3074e | 2016-02-23 22:30:50 +0000 | [diff] [blame] | 78 | these non-alphabet characters in the input result in a |
R. David Murray | 6495136 | 2010-11-11 20:09:20 +0000 | [diff] [blame] | 79 | :exc:`binascii.Error`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 80 | |
| 81 | |
| 82 | .. function:: standard_b64encode(s) |
| 83 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 84 | Encode :term:`bytes-like object` *s* using the standard Base64 alphabet |
| 85 | and return the encoded :class:`bytes`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 86 | |
| 87 | |
| 88 | .. function:: standard_b64decode(s) |
| 89 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 90 | Decode :term:`bytes-like object` or ASCII string *s* using the standard |
| 91 | Base64 alphabet and return the decoded :class:`bytes`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | |
| 93 | |
| 94 | .. function:: urlsafe_b64encode(s) |
| 95 | |
Martin Panter | ee3074e | 2016-02-23 22:30:50 +0000 | [diff] [blame] | 96 | Encode :term:`bytes-like object` *s* using the |
| 97 | URL- and filesystem-safe alphabet, which |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 98 | substitutes ``-`` instead of ``+`` and ``_`` instead of ``/`` in the |
| 99 | standard Base64 alphabet, and return the encoded :class:`bytes`. The result |
Benjamin Peterson | d75fcb4 | 2009-02-19 04:22:03 +0000 | [diff] [blame] | 100 | can still contain ``=``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 101 | |
| 102 | |
| 103 | .. function:: urlsafe_b64decode(s) |
| 104 | |
Martin Panter | ee3074e | 2016-02-23 22:30:50 +0000 | [diff] [blame] | 105 | Decode :term:`bytes-like object` or ASCII string *s* |
| 106 | using the URL- and filesystem-safe |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 107 | alphabet, which substitutes ``-`` instead of ``+`` and ``_`` instead of |
| 108 | ``/`` in the standard Base64 alphabet, and return the decoded |
| 109 | :class:`bytes`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 110 | |
| 111 | |
| 112 | .. function:: b32encode(s) |
| 113 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 114 | Encode the :term:`bytes-like object` *s* using Base32 and return the |
| 115 | encoded :class:`bytes`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | |
| 117 | |
Georg Brandl | b868a66 | 2009-04-02 02:56:10 +0000 | [diff] [blame] | 118 | .. function:: b32decode(s, casefold=False, map01=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 119 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 120 | Decode the Base32 encoded :term:`bytes-like object` or ASCII string *s* and |
| 121 | return the decoded :class:`bytes`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 122 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 123 | Optional *casefold* is a flag specifying |
R. David Murray | 7cefc30 | 2010-10-17 23:12:16 +0000 | [diff] [blame] | 124 | whether a lowercase alphabet is acceptable as input. For security purposes, |
| 125 | the default is ``False``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
| 127 | :rfc:`3548` allows for optional mapping of the digit 0 (zero) to the letter O |
| 128 | (oh), and for optional mapping of the digit 1 (one) to either the letter I (eye) |
| 129 | or letter L (el). The optional argument *map01* when not ``None``, specifies |
| 130 | which letter the digit 1 should be mapped to (when *map01* is not ``None``, the |
| 131 | digit 0 is always mapped to the letter O). For security purposes the default is |
| 132 | ``None``, so that 0 and 1 are not allowed in the input. |
| 133 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 134 | A :exc:`binascii.Error` is raised if *s* is |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 135 | incorrectly padded or if there are non-alphabet characters present in the |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 136 | input. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 137 | |
| 138 | |
| 139 | .. function:: b16encode(s) |
| 140 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 141 | Encode the :term:`bytes-like object` *s* using Base16 and return the |
| 142 | encoded :class:`bytes`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 143 | |
| 144 | |
Georg Brandl | b868a66 | 2009-04-02 02:56:10 +0000 | [diff] [blame] | 145 | .. function:: b16decode(s, casefold=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 146 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 147 | Decode the Base16 encoded :term:`bytes-like object` or ASCII string *s* and |
| 148 | return the decoded :class:`bytes`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 149 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 150 | Optional *casefold* is a flag specifying whether a |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 151 | lowercase alphabet is acceptable as input. For security purposes, the default |
| 152 | is ``False``. |
| 153 | |
Martin Panter | ee3074e | 2016-02-23 22:30:50 +0000 | [diff] [blame] | 154 | A :exc:`binascii.Error` is raised if *s* is |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 155 | incorrectly padded or if there are non-alphabet characters present in the |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 156 | input. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 157 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 158 | |
Martin Panter | ee3074e | 2016-02-23 22:30:50 +0000 | [diff] [blame] | 159 | .. function:: a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False) |
Antoine Pitrou | 6dd0d46 | 2013-11-17 23:52:25 +0100 | [diff] [blame] | 160 | |
Martin Panter | ee3074e | 2016-02-23 22:30:50 +0000 | [diff] [blame] | 161 | Encode the :term:`bytes-like object` *b* using Ascii85 and return the |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 162 | encoded :class:`bytes`. |
Antoine Pitrou | 6dd0d46 | 2013-11-17 23:52:25 +0100 | [diff] [blame] | 163 | |
| 164 | *foldspaces* is an optional flag that uses the special short sequence 'y' |
| 165 | instead of 4 consecutive spaces (ASCII 0x20) as supported by 'btoa'. This |
| 166 | feature is not supported by the "standard" Ascii85 encoding. |
| 167 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 168 | *wrapcol* controls whether the output should have newline (``b'\n'``) |
Antoine Pitrou | 6dd0d46 | 2013-11-17 23:52:25 +0100 | [diff] [blame] | 169 | characters added to it. If this is non-zero, each output line will be |
| 170 | at most this many characters long. |
| 171 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 172 | *pad* controls whether the input is padded to a multiple of 4 |
Antoine Pitrou | 6dd0d46 | 2013-11-17 23:52:25 +0100 | [diff] [blame] | 173 | before encoding. Note that the ``btoa`` implementation always pads. |
| 174 | |
| 175 | *adobe* controls whether the encoded byte sequence is framed with ``<~`` |
| 176 | and ``~>``, which is used by the Adobe implementation. |
| 177 | |
| 178 | .. versionadded:: 3.4 |
| 179 | |
| 180 | |
Martin Panter | ee3074e | 2016-02-23 22:30:50 +0000 | [diff] [blame] | 181 | .. function:: a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \\t\\n\\r\\v') |
Antoine Pitrou | 6dd0d46 | 2013-11-17 23:52:25 +0100 | [diff] [blame] | 182 | |
Martin Panter | ee3074e | 2016-02-23 22:30:50 +0000 | [diff] [blame] | 183 | Decode the Ascii85 encoded :term:`bytes-like object` or ASCII string *b* and |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 184 | return the decoded :class:`bytes`. |
Antoine Pitrou | 6dd0d46 | 2013-11-17 23:52:25 +0100 | [diff] [blame] | 185 | |
| 186 | *foldspaces* is a flag that specifies whether the 'y' short sequence |
| 187 | should be accepted as shorthand for 4 consecutive spaces (ASCII 0x20). |
| 188 | This feature is not supported by the "standard" Ascii85 encoding. |
| 189 | |
| 190 | *adobe* controls whether the input sequence is in Adobe Ascii85 format |
| 191 | (i.e. is framed with <~ and ~>). |
| 192 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 193 | *ignorechars* should be a :term:`bytes-like object` or ASCII string |
| 194 | containing characters to ignore |
Antoine Pitrou | 6dd0d46 | 2013-11-17 23:52:25 +0100 | [diff] [blame] | 195 | from the input. This should only contain whitespace characters, and by |
| 196 | default contains all whitespace characters in ASCII. |
| 197 | |
| 198 | .. versionadded:: 3.4 |
| 199 | |
| 200 | |
Martin Panter | ee3074e | 2016-02-23 22:30:50 +0000 | [diff] [blame] | 201 | .. function:: b85encode(b, pad=False) |
Antoine Pitrou | 6dd0d46 | 2013-11-17 23:52:25 +0100 | [diff] [blame] | 202 | |
Martin Panter | ee3074e | 2016-02-23 22:30:50 +0000 | [diff] [blame] | 203 | Encode the :term:`bytes-like object` *b* using base85 (as used in e.g. |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 204 | git-style binary diffs) and return the encoded :class:`bytes`. |
Antoine Pitrou | 6dd0d46 | 2013-11-17 23:52:25 +0100 | [diff] [blame] | 205 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 206 | If *pad* is true, the input is padded with ``b'\0'`` so its length is a |
| 207 | multiple of 4 bytes before encoding. |
Antoine Pitrou | 6dd0d46 | 2013-11-17 23:52:25 +0100 | [diff] [blame] | 208 | |
| 209 | .. versionadded:: 3.4 |
| 210 | |
| 211 | |
| 212 | .. function:: b85decode(b) |
| 213 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 214 | Decode the base85-encoded :term:`bytes-like object` or ASCII string *b* and |
| 215 | return the decoded :class:`bytes`. Padding is implicitly removed, if |
Antoine Pitrou | 6dd0d46 | 2013-11-17 23:52:25 +0100 | [diff] [blame] | 216 | necessary. |
| 217 | |
| 218 | .. versionadded:: 3.4 |
| 219 | |
| 220 | |
| 221 | .. note:: |
| 222 | Both Base85 and Ascii85 have an expansion factor of 5 to 4 (5 Base85 or |
| 223 | Ascii85 characters can encode 4 binary bytes), while the better-known |
| 224 | Base64 has an expansion factor of 6 to 4. They are therefore more |
| 225 | efficient when space expensive. They differ by details such as the |
| 226 | character map used for encoding. |
| 227 | |
| 228 | |
Georg Brandl | b54d801 | 2009-06-04 09:11:51 +0000 | [diff] [blame] | 229 | The legacy interface: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 230 | |
| 231 | .. function:: decode(input, output) |
| 232 | |
Georg Brandl | b54d801 | 2009-06-04 09:11:51 +0000 | [diff] [blame] | 233 | 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] | 234 | data to the *output* file. *input* and *output* must be :term:`file objects |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 235 | <file object>`. *input* will be read until ``input.readline()`` returns an |
| 236 | empty bytes object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 237 | |
| 238 | |
Georg Brandl | b54d801 | 2009-06-04 09:11:51 +0000 | [diff] [blame] | 239 | .. function:: decodebytes(s) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 240 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 241 | Decode the :term:`bytes-like object` *s*, which must contain one or more |
| 242 | lines of base64 encoded data, and return the decoded :class:`bytes`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 243 | |
R David Murray | 75fd225 | 2012-08-17 20:55:21 -0400 | [diff] [blame] | 244 | .. versionadded:: 3.1 |
| 245 | |
Matthias Bussonnier | c643a96 | 2017-03-02 06:21:26 -0800 | [diff] [blame] | 246 | .. function:: decodestring(s) |
| 247 | |
| 248 | Deprecated alias of :func:`decodebytes`. |
| 249 | |
| 250 | .. deprecated:: 3.1 |
| 251 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 252 | |
| 253 | .. function:: encode(input, output) |
| 254 | |
Georg Brandl | b54d801 | 2009-06-04 09:11:51 +0000 | [diff] [blame] | 255 | 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] | 256 | encoded data to the *output* file. *input* and *output* must be :term:`file |
| 257 | objects <file object>`. *input* will be read until ``input.read()`` returns |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 258 | an empty bytes object. :func:`encode` inserts a newline character (``b'\n'``) |
| 259 | after every 76 bytes of the output, as well as ensuring that the output |
| 260 | always ends with a newline, as per :rfc:`2045` (MIME). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 261 | |
| 262 | |
Georg Brandl | b54d801 | 2009-06-04 09:11:51 +0000 | [diff] [blame] | 263 | .. function:: encodebytes(s) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 264 | |
R David Murray | a198645 | 2015-12-23 21:17:17 -0500 | [diff] [blame] | 265 | Encode the :term:`bytes-like object` *s*, which can contain arbitrary binary |
| 266 | data, and return :class:`bytes` containing the base64-encoded data, with newlines |
| 267 | (``b'\n'``) inserted after every 76 bytes of output, and ensuring that |
| 268 | there is a trailing newline, as per :rfc:`2045` (MIME). |
| 269 | |
Matthias Bussonnier | c643a96 | 2017-03-02 06:21:26 -0800 | [diff] [blame] | 270 | .. versionadded:: 3.1 |
| 271 | |
| 272 | .. function:: encodestring(s) |
| 273 | |
| 274 | Deprecated alias of :func:`encodebytes`. |
| 275 | |
| 276 | .. deprecated:: 3.1 |
Georg Brandl | b54d801 | 2009-06-04 09:11:51 +0000 | [diff] [blame] | 277 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 278 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 279 | An example usage of the module: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 280 | |
| 281 | >>> import base64 |
Georg Brandl | 134c35b | 2010-10-17 11:36:28 +0000 | [diff] [blame] | 282 | >>> encoded = base64.b64encode(b'data to be encoded') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 283 | >>> encoded |
Georg Brandl | 38d54f7 | 2009-01-18 10:43:58 +0000 | [diff] [blame] | 284 | b'ZGF0YSB0byBiZSBlbmNvZGVk' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 285 | >>> data = base64.b64decode(encoded) |
| 286 | >>> data |
Georg Brandl | 134c35b | 2010-10-17 11:36:28 +0000 | [diff] [blame] | 287 | b'data to be encoded' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 288 | |
| 289 | |
| 290 | .. seealso:: |
| 291 | |
| 292 | Module :mod:`binascii` |
| 293 | Support module containing ASCII-to-binary and binary-to-ASCII conversions. |
| 294 | |
| 295 | :rfc:`1521` - MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies |
| 296 | Section 5.2, "Base64 Content-Transfer-Encoding," provides the definition of the |
| 297 | base64 encoding. |
| 298 | |