Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`binascii` --- Convert between binary and ASCII |
| 2 | ==================================================== |
| 3 | |
| 4 | .. module:: binascii |
| 5 | :synopsis: Tools for converting between binary and various ASCII-encoded binary |
| 6 | representations. |
| 7 | |
| 8 | |
| 9 | .. index:: |
| 10 | module: uu |
| 11 | module: base64 |
| 12 | module: binhex |
| 13 | |
| 14 | The :mod:`binascii` module contains a number of methods to convert between |
| 15 | binary and various ASCII-encoded binary representations. Normally, you will not |
| 16 | use these functions directly but use wrapper modules like :mod:`uu`, |
| 17 | :mod:`base64`, or :mod:`binhex` instead. The :mod:`binascii` module contains |
| 18 | low-level functions written in C for greater speed that are used by the |
| 19 | higher-level modules. |
| 20 | |
Florent Xicluna | f1046ca | 2010-07-27 21:20:15 +0000 | [diff] [blame] | 21 | .. note:: |
| 22 | |
Antoine Pitrou | 0831676 | 2011-12-20 13:58:41 +0100 | [diff] [blame] | 23 | ``a2b_*`` functions accept Unicode strings containing only ASCII characters. |
Ezio Melotti | c228e96 | 2013-05-04 18:06:34 +0300 | [diff] [blame] | 24 | Other functions only accept :term:`bytes-like object`\ s (such as |
| 25 | :class:`bytes`, :class:`bytearray` and other objects that support the buffer |
| 26 | protocol). |
Antoine Pitrou | 0831676 | 2011-12-20 13:58:41 +0100 | [diff] [blame] | 27 | |
| 28 | .. versionchanged:: 3.3 |
| 29 | ASCII-only unicode strings are now accepted by the ``a2b_*`` functions. |
| 30 | |
Florent Xicluna | f1046ca | 2010-07-27 21:20:15 +0000 | [diff] [blame] | 31 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 32 | The :mod:`binascii` module defines the following functions: |
| 33 | |
| 34 | |
| 35 | .. function:: a2b_uu(string) |
| 36 | |
| 37 | Convert a single line of uuencoded data back to binary and return the binary |
| 38 | data. Lines normally contain 45 (binary) bytes, except for the last line. Line |
| 39 | data may be followed by whitespace. |
| 40 | |
| 41 | |
| 42 | .. function:: b2a_uu(data) |
| 43 | |
| 44 | Convert binary data to a line of ASCII characters, the return value is the |
| 45 | converted line, including a newline char. The length of *data* should be at most |
| 46 | 45. |
| 47 | |
| 48 | |
| 49 | .. function:: a2b_base64(string) |
| 50 | |
| 51 | Convert a block of base64 data back to binary and return the binary data. More |
| 52 | than one line may be passed at a time. |
| 53 | |
| 54 | |
| 55 | .. function:: b2a_base64(data) |
| 56 | |
| 57 | Convert binary data to a line of ASCII characters in base64 coding. The return |
| 58 | value is the converted line, including a newline char. The length of *data* |
| 59 | should be at most 57 to adhere to the base64 standard. |
| 60 | |
| 61 | |
Georg Brandl | b868a66 | 2009-04-02 02:56:10 +0000 | [diff] [blame] | 62 | .. function:: a2b_qp(string, header=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 63 | |
| 64 | Convert a block of quoted-printable data back to binary and return the binary |
| 65 | data. More than one line may be passed at a time. If the optional argument |
| 66 | *header* is present and true, underscores will be decoded as spaces. |
| 67 | |
Florent Xicluna | f1046ca | 2010-07-27 21:20:15 +0000 | [diff] [blame] | 68 | .. versionchanged:: 3.2 |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 69 | Accept only bytestring or bytearray objects as input. |
Florent Xicluna | f1046ca | 2010-07-27 21:20:15 +0000 | [diff] [blame] | 70 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
Georg Brandl | b868a66 | 2009-04-02 02:56:10 +0000 | [diff] [blame] | 72 | .. function:: b2a_qp(data, quotetabs=False, istext=True, header=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | |
| 74 | Convert binary data to a line(s) of ASCII characters in quoted-printable |
| 75 | encoding. The return value is the converted line(s). If the optional argument |
| 76 | *quotetabs* is present and true, all tabs and spaces will be encoded. If the |
| 77 | optional argument *istext* is present and true, newlines are not encoded but |
| 78 | trailing whitespace will be encoded. If the optional argument *header* is |
| 79 | present and true, spaces will be encoded as underscores per RFC1522. If the |
| 80 | optional argument *header* is present and false, newline characters will be |
| 81 | encoded as well; otherwise linefeed conversion might corrupt the binary data |
| 82 | stream. |
| 83 | |
| 84 | |
| 85 | .. function:: a2b_hqx(string) |
| 86 | |
| 87 | Convert binhex4 formatted ASCII data to binary, without doing RLE-decompression. |
| 88 | The string should contain a complete number of binary bytes, or (in case of the |
| 89 | last portion of the binhex4 data) have the remaining bits zero. |
| 90 | |
| 91 | |
| 92 | .. function:: rledecode_hqx(data) |
| 93 | |
| 94 | Perform RLE-decompression on the data, as per the binhex4 standard. The |
| 95 | algorithm uses ``0x90`` after a byte as a repeat indicator, followed by a count. |
| 96 | A count of ``0`` specifies a byte value of ``0x90``. The routine returns the |
| 97 | decompressed data, unless data input data ends in an orphaned repeat indicator, |
| 98 | in which case the :exc:`Incomplete` exception is raised. |
| 99 | |
Florent Xicluna | f1046ca | 2010-07-27 21:20:15 +0000 | [diff] [blame] | 100 | .. versionchanged:: 3.2 |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 101 | Accept only bytestring or bytearray objects as input. |
Florent Xicluna | f1046ca | 2010-07-27 21:20:15 +0000 | [diff] [blame] | 102 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 103 | |
| 104 | .. function:: rlecode_hqx(data) |
| 105 | |
| 106 | Perform binhex4 style RLE-compression on *data* and return the result. |
| 107 | |
| 108 | |
| 109 | .. function:: b2a_hqx(data) |
| 110 | |
| 111 | Perform hexbin4 binary-to-ASCII translation and return the resulting string. The |
| 112 | argument should already be RLE-coded, and have a length divisible by 3 (except |
| 113 | possibly the last fragment). |
| 114 | |
| 115 | |
| 116 | .. function:: crc_hqx(data, crc) |
| 117 | |
| 118 | Compute the binhex4 crc value of *data*, starting with an initial *crc* and |
| 119 | returning the result. |
| 120 | |
| 121 | |
| 122 | .. function:: crc32(data[, crc]) |
| 123 | |
| 124 | Compute CRC-32, the 32-bit checksum of data, starting with an initial crc. This |
| 125 | is consistent with the ZIP file checksum. Since the algorithm is designed for |
| 126 | use as a checksum algorithm, it is not suitable for use as a general hash |
| 127 | algorithm. Use as follows:: |
| 128 | |
Georg Brandl | ede6c2a | 2010-01-05 10:22:04 +0000 | [diff] [blame] | 129 | print(binascii.crc32(b"hello world")) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 130 | # Or, in two pieces: |
Georg Brandl | ede6c2a | 2010-01-05 10:22:04 +0000 | [diff] [blame] | 131 | crc = binascii.crc32(b"hello") |
| 132 | crc = binascii.crc32(b" world", crc) & 0xffffffff |
| 133 | print('crc32 = {:#010x}'.format(crc)) |
Benjamin Peterson | 058e31e | 2009-01-16 03:54:08 +0000 | [diff] [blame] | 134 | |
| 135 | .. note:: |
| 136 | To generate the same numeric value across all Python versions and |
| 137 | platforms use crc32(data) & 0xffffffff. If you are only using |
| 138 | the checksum in packed binary format this is not necessary as the |
Gregory P. Smith | fa6cf39 | 2009-02-01 00:30:50 +0000 | [diff] [blame] | 139 | return value is the correct 32bit binary representation |
Benjamin Peterson | 058e31e | 2009-01-16 03:54:08 +0000 | [diff] [blame] | 140 | regardless of sign. |
| 141 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 142 | |
| 143 | .. function:: b2a_hex(data) |
| 144 | hexlify(data) |
| 145 | |
| 146 | Return the hexadecimal representation of the binary *data*. Every byte of |
| 147 | *data* is converted into the corresponding 2-digit hex representation. The |
R David Murray | 5fdb64b | 2013-11-03 13:21:38 -0500 | [diff] [blame] | 148 | returned bytes object is therefore twice as long as the length of *data*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 149 | |
| 150 | |
| 151 | .. function:: a2b_hex(hexstr) |
| 152 | unhexlify(hexstr) |
| 153 | |
| 154 | Return the binary data represented by the hexadecimal string *hexstr*. This |
| 155 | function is the inverse of :func:`b2a_hex`. *hexstr* must contain an even number |
| 156 | of hexadecimal digits (which can be upper or lower case), otherwise a |
| 157 | :exc:`TypeError` is raised. |
| 158 | |
Florent Xicluna | f1046ca | 2010-07-27 21:20:15 +0000 | [diff] [blame] | 159 | .. versionchanged:: 3.2 |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 160 | Accept only bytestring or bytearray objects as input. |
Florent Xicluna | f1046ca | 2010-07-27 21:20:15 +0000 | [diff] [blame] | 161 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 162 | |
| 163 | .. exception:: Error |
| 164 | |
| 165 | Exception raised on errors. These are usually programming errors. |
| 166 | |
| 167 | |
| 168 | .. exception:: Incomplete |
| 169 | |
| 170 | Exception raised on incomplete data. These are usually not programming errors, |
| 171 | but may be handled by reading a little more data and trying again. |
| 172 | |
| 173 | |
| 174 | .. seealso:: |
| 175 | |
| 176 | Module :mod:`base64` |
| 177 | Support for base64 encoding used in MIME email messages. |
| 178 | |
| 179 | Module :mod:`binhex` |
| 180 | Support for the binhex format used on the Macintosh. |
| 181 | |
| 182 | Module :mod:`uu` |
| 183 | Support for UU encoding used on Unix. |
| 184 | |
| 185 | Module :mod:`quopri` |
| 186 | Support for quoted-printable encoding used in MIME email messages. |