| 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 |
.. index:: |
| 9 |
pair: module; base64 |
| 10 |
|
| 11 |
-------------- |
| 12 |
|
| 13 |
The :mod:`!binascii` module contains a number of methods to convert between |
| 14 |
binary and various ASCII-encoded binary representations. Normally, you will not |
| 15 |
use these functions directly but use wrapper modules like |
| 16 |
:mod:`base64` instead. The :mod:`!binascii` module contains |
| 17 |
low-level functions written in C for greater speed that are used by the |
| 18 |
higher-level modules. |
| 19 |
|
| 20 |
.. note:: |
| 21 |
|
| 22 |
``a2b_*`` functions accept Unicode strings containing only ASCII characters. |
| 23 |
Other functions only accept :term:`bytes-like objects <bytes-like object>` (such as |
| 24 |
:class:`bytes`, :class:`bytearray` and other objects that support the buffer |
| 25 |
protocol). |
| 26 |
|
| 27 |
.. versionchanged:: 3.3 |
| 28 |
ASCII-only unicode strings are now accepted by the ``a2b_*`` functions. |
| 29 |
|
| 30 |
|
| 31 |
The :mod:`!binascii` module defines the following functions: |
| 32 |
|
| 33 |
|
| 34 |
.. function:: a2b_uu(string) |
| 35 |
|
| 36 |
Convert a single line of uuencoded data back to binary and return the binary |
| 37 |
data. Lines normally contain 45 (binary) bytes, except for the last line. Line |
| 38 |
data may be followed by whitespace. |
| 39 |
|
| 40 |
|
| 41 |
.. function:: b2a_uu(data, *, backtick=False) |
| 42 |
|
| 43 |
Convert binary data to a line of ASCII characters, the return value is the |
| 44 |
converted line, including a newline char. The length of *data* should be at most |
| 45 |
45. If *backtick* is true, zeros are represented by ``'`'`` instead of spaces. |
| 46 |
|
| 47 |
.. versionchanged:: 3.7 |
| 48 |
Added the *backtick* parameter. |
| 49 |
|
| 50 |
|
| 51 |
.. function:: a2b_base64(string, /, *, strict_mode=False) |
| 52 |
|
| 53 |
Convert a block of base64 data back to binary and return the binary data. More |
| 54 |
than one line may be passed at a time. |
| 55 |
|
| 56 |
If *strict_mode* is true, only valid base64 data will be converted. Invalid base64 |
| 57 |
data will raise :exc:`binascii.Error`. |
| 58 |
|
| 59 |
Valid base64: |
| 60 |
|
| 61 |
* Conforms to :rfc:`3548`. |
| 62 |
* Contains only characters from the base64 alphabet. |
| 63 |
* Contains no excess data after padding (including excess padding, newlines, etc.). |
| 64 |
* Does not start with a padding. |
| 65 |
|
| 66 |
.. versionchanged:: 3.11 |
| 67 |
Added the *strict_mode* parameter. |
| 68 |
|
| 69 |
|
| 70 |
.. function:: b2a_base64(data, *, newline=True) |
| 71 |
|
| 72 |
Convert binary data to a line of ASCII characters in base64 coding. The return |
| 73 |
value is the converted line, including a newline char if *newline* is |
| 74 |
true. The output of this function conforms to :rfc:`3548`. |
| 75 |
|
| 76 |
.. versionchanged:: 3.6 |
| 77 |
Added the *newline* parameter. |
| 78 |
|
| 79 |
|
| 80 |
.. function:: a2b_qp(data, header=False) |
| 81 |
|
| 82 |
Convert a block of quoted-printable data back to binary and return the binary |
| 83 |
data. More than one line may be passed at a time. If the optional argument |
| 84 |
*header* is present and true, underscores will be decoded as spaces. |
| 85 |
|
| 86 |
|
| 87 |
.. function:: b2a_qp(data, quotetabs=False, istext=True, header=False) |
| 88 |
|
| 89 |
Convert binary data to a line(s) of ASCII characters in quoted-printable |
| 90 |
encoding. The return value is the converted line(s). If the optional argument |
| 91 |
*quotetabs* is present and true, all tabs and spaces will be encoded. If the |
| 92 |
optional argument *istext* is present and true, newlines are not encoded but |
| 93 |
trailing whitespace will be encoded. If the optional argument *header* is |
| 94 |
present and true, spaces will be encoded as underscores per :rfc:`1522`. If the |
| 95 |
optional argument *header* is present and false, newline characters will be |
| 96 |
encoded as well; otherwise linefeed conversion might corrupt the binary data |
| 97 |
stream. |
| 98 |
|
| 99 |
|
| 100 |
.. function:: crc_hqx(data, value) |
| 101 |
|
| 102 |
Compute a 16-bit CRC value of *data*, starting with *value* as the |
| 103 |
initial CRC, and return the result. This uses the CRC-CCITT polynomial |
| 104 |
*x*:sup:`16` + *x*:sup:`12` + *x*:sup:`5` + 1, often represented as |
| 105 |
0x1021. This CRC is used in the binhex4 format. |
| 106 |
|
| 107 |
|
| 108 |
.. function:: crc32(data[, value]) |
| 109 |
|
| 110 |
Compute CRC-32, the unsigned 32-bit checksum of *data*, starting with an |
| 111 |
initial CRC of *value*. The default initial CRC is zero. The algorithm |
| 112 |
is consistent with the ZIP file checksum. Since the algorithm is designed for |
| 113 |
use as a checksum algorithm, it is not suitable for use as a general hash |
| 114 |
algorithm. Use as follows:: |
| 115 |
|
| 116 |
print(binascii.crc32(b"hello world")) |
| 117 |
# Or, in two pieces: |
| 118 |
crc = binascii.crc32(b"hello") |
| 119 |
crc = binascii.crc32(b" world", crc) |
| 120 |
print('crc32 = {:#010x}'.format(crc)) |
| 121 |
|
| 122 |
.. versionchanged:: 3.0 |
| 123 |
The result is always unsigned. |
| 124 |
|
| 125 |
.. function:: b2a_hex(data[, sep[, bytes_per_sep=1]]) |
| 126 |
hexlify(data[, sep[, bytes_per_sep=1]]) |
| 127 |
|
| 128 |
Return the hexadecimal representation of the binary *data*. Every byte of |
| 129 |
*data* is converted into the corresponding 2-digit hex representation. The |
| 130 |
returned bytes object is therefore twice as long as the length of *data*. |
| 131 |
|
| 132 |
Similar functionality (but returning a text string) is also conveniently |
| 133 |
accessible using the :meth:`bytes.hex` method. |
| 134 |
|
| 135 |
If *sep* is specified, it must be a single character str or bytes object. |
| 136 |
It will be inserted in the output after every *bytes_per_sep* input bytes. |
| 137 |
Separator placement is counted from the right end of the output by default, |
| 138 |
if you wish to count from the left, supply a negative *bytes_per_sep* value. |
| 139 |
|
| 140 |
>>> import binascii |
| 141 |
>>> binascii.b2a_hex(b'\xb9\x01\xef') |
| 142 |
b'b901ef' |
| 143 |
>>> binascii.hexlify(b'\xb9\x01\xef', '-') |
| 144 |
b'b9-01-ef' |
| 145 |
>>> binascii.b2a_hex(b'\xb9\x01\xef', b'_', 2) |
| 146 |
b'b9_01ef' |
| 147 |
>>> binascii.b2a_hex(b'\xb9\x01\xef', b' ', -2) |
| 148 |
b'b901 ef' |
| 149 |
|
| 150 |
.. versionchanged:: 3.8 |
| 151 |
The *sep* and *bytes_per_sep* parameters were added. |
| 152 |
|
| 153 |
.. function:: a2b_hex(hexstr) |
| 154 |
unhexlify(hexstr) |
| 155 |
|
| 156 |
Return the binary data represented by the hexadecimal string *hexstr*. This |
| 157 |
function is the inverse of :func:`b2a_hex`. *hexstr* must contain an even number |
| 158 |
of hexadecimal digits (which can be upper or lower case), otherwise an |
| 159 |
:exc:`Error` exception is raised. |
| 160 |
|
| 161 |
Similar functionality (but more liberal towards whitespace) is also accessible |
| 162 |
using the :meth:`bytes.fromhex` class method. |
| 163 |
|
| 164 |
.. exception:: Error |
| 165 |
|
| 166 |
Exception raised on errors. These are usually programming errors. |
| 167 |
|
| 168 |
|
| 169 |
.. exception:: Incomplete |
| 170 |
|
| 171 |
Exception raised on incomplete data. These are usually not programming errors, |
| 172 |
but may be handled by reading a little more data and trying again. |
| 173 |
|
| 174 |
|
| 175 |
.. seealso:: |
| 176 |
|
| 177 |
Module :mod:`base64` |
| 178 |
Support for RFC compliant base64-style encoding in base 16, 32, 64, |
| 179 |
and 85. |
| 180 |
|
| 181 |
Module :mod:`quopri` |
| 182 |
Support for quoted-printable encoding used in MIME email messages. |