17db96d56Sopenharmony_ci:mod:`binascii` --- Convert between binary and ASCII 27db96d56Sopenharmony_ci==================================================== 37db96d56Sopenharmony_ci 47db96d56Sopenharmony_ci.. module:: binascii 57db96d56Sopenharmony_ci :synopsis: Tools for converting between binary and various ASCII-encoded binary 67db96d56Sopenharmony_ci representations. 77db96d56Sopenharmony_ci 87db96d56Sopenharmony_ci.. index:: 97db96d56Sopenharmony_ci pair: module; uu 107db96d56Sopenharmony_ci pair: module; base64 117db96d56Sopenharmony_ci 127db96d56Sopenharmony_ci-------------- 137db96d56Sopenharmony_ci 147db96d56Sopenharmony_ciThe :mod:`binascii` module contains a number of methods to convert between 157db96d56Sopenharmony_cibinary and various ASCII-encoded binary representations. Normally, you will not 167db96d56Sopenharmony_ciuse these functions directly but use wrapper modules like :mod:`uu` or 177db96d56Sopenharmony_ci:mod:`base64` instead. The :mod:`binascii` module contains 187db96d56Sopenharmony_cilow-level functions written in C for greater speed that are used by the 197db96d56Sopenharmony_cihigher-level modules. 207db96d56Sopenharmony_ci 217db96d56Sopenharmony_ci.. note:: 227db96d56Sopenharmony_ci 237db96d56Sopenharmony_ci ``a2b_*`` functions accept Unicode strings containing only ASCII characters. 247db96d56Sopenharmony_ci Other functions only accept :term:`bytes-like objects <bytes-like object>` (such as 257db96d56Sopenharmony_ci :class:`bytes`, :class:`bytearray` and other objects that support the buffer 267db96d56Sopenharmony_ci protocol). 277db96d56Sopenharmony_ci 287db96d56Sopenharmony_ci .. versionchanged:: 3.3 297db96d56Sopenharmony_ci ASCII-only unicode strings are now accepted by the ``a2b_*`` functions. 307db96d56Sopenharmony_ci 317db96d56Sopenharmony_ci 327db96d56Sopenharmony_ciThe :mod:`binascii` module defines the following functions: 337db96d56Sopenharmony_ci 347db96d56Sopenharmony_ci 357db96d56Sopenharmony_ci.. function:: a2b_uu(string) 367db96d56Sopenharmony_ci 377db96d56Sopenharmony_ci Convert a single line of uuencoded data back to binary and return the binary 387db96d56Sopenharmony_ci data. Lines normally contain 45 (binary) bytes, except for the last line. Line 397db96d56Sopenharmony_ci data may be followed by whitespace. 407db96d56Sopenharmony_ci 417db96d56Sopenharmony_ci 427db96d56Sopenharmony_ci.. function:: b2a_uu(data, *, backtick=False) 437db96d56Sopenharmony_ci 447db96d56Sopenharmony_ci Convert binary data to a line of ASCII characters, the return value is the 457db96d56Sopenharmony_ci converted line, including a newline char. The length of *data* should be at most 467db96d56Sopenharmony_ci 45. If *backtick* is true, zeros are represented by ``'`'`` instead of spaces. 477db96d56Sopenharmony_ci 487db96d56Sopenharmony_ci .. versionchanged:: 3.7 497db96d56Sopenharmony_ci Added the *backtick* parameter. 507db96d56Sopenharmony_ci 517db96d56Sopenharmony_ci 527db96d56Sopenharmony_ci.. function:: a2b_base64(string, /, *, strict_mode=False) 537db96d56Sopenharmony_ci 547db96d56Sopenharmony_ci Convert a block of base64 data back to binary and return the binary data. More 557db96d56Sopenharmony_ci than one line may be passed at a time. 567db96d56Sopenharmony_ci 577db96d56Sopenharmony_ci If *strict_mode* is true, only valid base64 data will be converted. Invalid base64 587db96d56Sopenharmony_ci data will raise :exc:`binascii.Error`. 597db96d56Sopenharmony_ci 607db96d56Sopenharmony_ci Valid base64: 617db96d56Sopenharmony_ci * Conforms to :rfc:`3548`. 627db96d56Sopenharmony_ci * Contains only characters from the base64 alphabet. 637db96d56Sopenharmony_ci * Contains no excess data after padding (including excess padding, newlines, etc.). 647db96d56Sopenharmony_ci * Does not start with a padding. 657db96d56Sopenharmony_ci 667db96d56Sopenharmony_ci .. versionchanged:: 3.11 677db96d56Sopenharmony_ci Added the *strict_mode* parameter. 687db96d56Sopenharmony_ci 697db96d56Sopenharmony_ci 707db96d56Sopenharmony_ci.. function:: b2a_base64(data, *, newline=True) 717db96d56Sopenharmony_ci 727db96d56Sopenharmony_ci Convert binary data to a line of ASCII characters in base64 coding. The return 737db96d56Sopenharmony_ci value is the converted line, including a newline char if *newline* is 747db96d56Sopenharmony_ci true. The output of this function conforms to :rfc:`3548`. 757db96d56Sopenharmony_ci 767db96d56Sopenharmony_ci .. versionchanged:: 3.6 777db96d56Sopenharmony_ci Added the *newline* parameter. 787db96d56Sopenharmony_ci 797db96d56Sopenharmony_ci 807db96d56Sopenharmony_ci.. function:: a2b_qp(data, header=False) 817db96d56Sopenharmony_ci 827db96d56Sopenharmony_ci Convert a block of quoted-printable data back to binary and return the binary 837db96d56Sopenharmony_ci data. More than one line may be passed at a time. If the optional argument 847db96d56Sopenharmony_ci *header* is present and true, underscores will be decoded as spaces. 857db96d56Sopenharmony_ci 867db96d56Sopenharmony_ci 877db96d56Sopenharmony_ci.. function:: b2a_qp(data, quotetabs=False, istext=True, header=False) 887db96d56Sopenharmony_ci 897db96d56Sopenharmony_ci Convert binary data to a line(s) of ASCII characters in quoted-printable 907db96d56Sopenharmony_ci encoding. The return value is the converted line(s). If the optional argument 917db96d56Sopenharmony_ci *quotetabs* is present and true, all tabs and spaces will be encoded. If the 927db96d56Sopenharmony_ci optional argument *istext* is present and true, newlines are not encoded but 937db96d56Sopenharmony_ci trailing whitespace will be encoded. If the optional argument *header* is 947db96d56Sopenharmony_ci present and true, spaces will be encoded as underscores per :rfc:`1522`. If the 957db96d56Sopenharmony_ci optional argument *header* is present and false, newline characters will be 967db96d56Sopenharmony_ci encoded as well; otherwise linefeed conversion might corrupt the binary data 977db96d56Sopenharmony_ci stream. 987db96d56Sopenharmony_ci 997db96d56Sopenharmony_ci 1007db96d56Sopenharmony_ci.. function:: crc_hqx(data, value) 1017db96d56Sopenharmony_ci 1027db96d56Sopenharmony_ci Compute a 16-bit CRC value of *data*, starting with *value* as the 1037db96d56Sopenharmony_ci initial CRC, and return the result. This uses the CRC-CCITT polynomial 1047db96d56Sopenharmony_ci *x*:sup:`16` + *x*:sup:`12` + *x*:sup:`5` + 1, often represented as 1057db96d56Sopenharmony_ci 0x1021. This CRC is used in the binhex4 format. 1067db96d56Sopenharmony_ci 1077db96d56Sopenharmony_ci 1087db96d56Sopenharmony_ci.. function:: crc32(data[, value]) 1097db96d56Sopenharmony_ci 1107db96d56Sopenharmony_ci Compute CRC-32, the unsigned 32-bit checksum of *data*, starting with an 1117db96d56Sopenharmony_ci initial CRC of *value*. The default initial CRC is zero. The algorithm 1127db96d56Sopenharmony_ci is consistent with the ZIP file checksum. Since the algorithm is designed for 1137db96d56Sopenharmony_ci use as a checksum algorithm, it is not suitable for use as a general hash 1147db96d56Sopenharmony_ci algorithm. Use as follows:: 1157db96d56Sopenharmony_ci 1167db96d56Sopenharmony_ci print(binascii.crc32(b"hello world")) 1177db96d56Sopenharmony_ci # Or, in two pieces: 1187db96d56Sopenharmony_ci crc = binascii.crc32(b"hello") 1197db96d56Sopenharmony_ci crc = binascii.crc32(b" world", crc) 1207db96d56Sopenharmony_ci print('crc32 = {:#010x}'.format(crc)) 1217db96d56Sopenharmony_ci 1227db96d56Sopenharmony_ci .. versionchanged:: 3.0 1237db96d56Sopenharmony_ci The result is always unsigned. 1247db96d56Sopenharmony_ci 1257db96d56Sopenharmony_ci.. function:: b2a_hex(data[, sep[, bytes_per_sep=1]]) 1267db96d56Sopenharmony_ci hexlify(data[, sep[, bytes_per_sep=1]]) 1277db96d56Sopenharmony_ci 1287db96d56Sopenharmony_ci Return the hexadecimal representation of the binary *data*. Every byte of 1297db96d56Sopenharmony_ci *data* is converted into the corresponding 2-digit hex representation. The 1307db96d56Sopenharmony_ci returned bytes object is therefore twice as long as the length of *data*. 1317db96d56Sopenharmony_ci 1327db96d56Sopenharmony_ci Similar functionality (but returning a text string) is also conveniently 1337db96d56Sopenharmony_ci accessible using the :meth:`bytes.hex` method. 1347db96d56Sopenharmony_ci 1357db96d56Sopenharmony_ci If *sep* is specified, it must be a single character str or bytes object. 1367db96d56Sopenharmony_ci It will be inserted in the output after every *bytes_per_sep* input bytes. 1377db96d56Sopenharmony_ci Separator placement is counted from the right end of the output by default, 1387db96d56Sopenharmony_ci if you wish to count from the left, supply a negative *bytes_per_sep* value. 1397db96d56Sopenharmony_ci 1407db96d56Sopenharmony_ci >>> import binascii 1417db96d56Sopenharmony_ci >>> binascii.b2a_hex(b'\xb9\x01\xef') 1427db96d56Sopenharmony_ci b'b901ef' 1437db96d56Sopenharmony_ci >>> binascii.hexlify(b'\xb9\x01\xef', '-') 1447db96d56Sopenharmony_ci b'b9-01-ef' 1457db96d56Sopenharmony_ci >>> binascii.b2a_hex(b'\xb9\x01\xef', b'_', 2) 1467db96d56Sopenharmony_ci b'b9_01ef' 1477db96d56Sopenharmony_ci >>> binascii.b2a_hex(b'\xb9\x01\xef', b' ', -2) 1487db96d56Sopenharmony_ci b'b901 ef' 1497db96d56Sopenharmony_ci 1507db96d56Sopenharmony_ci .. versionchanged:: 3.8 1517db96d56Sopenharmony_ci The *sep* and *bytes_per_sep* parameters were added. 1527db96d56Sopenharmony_ci 1537db96d56Sopenharmony_ci.. function:: a2b_hex(hexstr) 1547db96d56Sopenharmony_ci unhexlify(hexstr) 1557db96d56Sopenharmony_ci 1567db96d56Sopenharmony_ci Return the binary data represented by the hexadecimal string *hexstr*. This 1577db96d56Sopenharmony_ci function is the inverse of :func:`b2a_hex`. *hexstr* must contain an even number 1587db96d56Sopenharmony_ci of hexadecimal digits (which can be upper or lower case), otherwise an 1597db96d56Sopenharmony_ci :exc:`Error` exception is raised. 1607db96d56Sopenharmony_ci 1617db96d56Sopenharmony_ci Similar functionality (accepting only text string arguments, but more 1627db96d56Sopenharmony_ci liberal towards whitespace) is also accessible using the 1637db96d56Sopenharmony_ci :meth:`bytes.fromhex` class method. 1647db96d56Sopenharmony_ci 1657db96d56Sopenharmony_ci.. exception:: Error 1667db96d56Sopenharmony_ci 1677db96d56Sopenharmony_ci Exception raised on errors. These are usually programming errors. 1687db96d56Sopenharmony_ci 1697db96d56Sopenharmony_ci 1707db96d56Sopenharmony_ci.. exception:: Incomplete 1717db96d56Sopenharmony_ci 1727db96d56Sopenharmony_ci Exception raised on incomplete data. These are usually not programming errors, 1737db96d56Sopenharmony_ci but may be handled by reading a little more data and trying again. 1747db96d56Sopenharmony_ci 1757db96d56Sopenharmony_ci 1767db96d56Sopenharmony_ci.. seealso:: 1777db96d56Sopenharmony_ci 1787db96d56Sopenharmony_ci Module :mod:`base64` 1797db96d56Sopenharmony_ci Support for RFC compliant base64-style encoding in base 16, 32, 64, 1807db96d56Sopenharmony_ci and 85. 1817db96d56Sopenharmony_ci 1827db96d56Sopenharmony_ci Module :mod:`uu` 1837db96d56Sopenharmony_ci Support for UU encoding used on Unix. 1847db96d56Sopenharmony_ci 1857db96d56Sopenharmony_ci Module :mod:`quopri` 1867db96d56Sopenharmony_ci Support for quoted-printable encoding used in MIME email messages. 187