binascii — Преобразование между двоичными данными и ASCII

Модуль binascii содержит ряд методов для преобразования двоичных данных в различные представления двоичных данных, закодированные в ASCII, и обратно. Обычно эти функции не вызывают напрямую, а используют модули-обёртки, такие как base64. Модуль binascii содержит низкоуровневые функции, написанные на C для повышения скорости; они используются модулями более высокого уровня.

Модуль binascii определяет следующие функции:

binascii.a2b_uu(string)

Преобразует одну строку данных в кодировке uu обратно в двоичные данные и возвращает их. Обычно строки содержат 45 байтов (двоичных данных), за исключением последней строки. После данных в строке могут следовать пробельные символы.

binascii.b2a_uu(data, *, backtick=False)

Преобразует двоичные данные в строку символов ASCII. Возвращаемое значение — преобразованная строка, включая символ новой строки. Длина data должна быть не более 45. Если backtick имеет значение true, нули представлены символом '`' вместо пробелов.

Изменено в версии 3.7: Добавлен параметр backtick.

binascii.a2b_base64(string, /, *, strict_mode=False)

Преобразует блок данных в кодировке base64 обратно в двоичные данные и возвращает их. За один раз можно передать несколько строк.

Если strict_mode имеет значение true, преобразуются только корректные данные base64. Некорректные данные base64 вызывают исключение binascii.Error.

Корректные данные base64:

• Соответствуют RFC 3548.
• Содержат только символы из алфавита base64.
• Не содержат лишних данных после заполнения (включая лишние символы заполнения, символы новой строки и т. д.).
• Не начинаются с символа заполнения.

Изменено в версии 3.11: Добавлен параметр strict_mode.

binascii.b2a_base64(data, *, newline=True)

Преобразует двоичные данные в строку символов ASCII в кодировке base64. Возвращаемое значение — преобразованная строка, включая символ новой строки, если newline имеет значение true. Результат этой функции соответствует RFC 3548.

Изменено в версии 3.6: Добавлен параметр newline.

binascii.a2b_qp(data, header=False)

Преобразует блок данных в кодировке quoted-printable обратно в двоичные данные и возвращает их. За один раз можно передать несколько строк. Если необязательный аргумент header указан и имеет значение true, символы подчёркивания декодируются как пробелы.

binascii.b2a_qp(data, quotetabs=False, istext=True, header=False)

Преобразует двоичные данные в одну или несколько строк символов ASCII в кодировке quoted-printable. Возвращаемое значение — преобразованная строка или строки. Если необязательный аргумент quotetabs указан и имеет значение true, все табуляции и пробелы будут закодированы. Если необязательный аргумент istext указан и имеет значение true, символы новой строки не кодируются, но конечные пробельные символы кодируются. Если необязательный аргумент header указан и имеет значение true, пробелы кодируются символами подчёркивания в соответствии с RFC 1522. Если необязательный аргумент header указан и имеет значение false, символы новой строки также кодируются; в противном случае преобразование символов перевода строки может повредить поток двоичных данных.

binascii.crc_hqx(data, value)

Вычисляет 16-битное значение CRC для data, используя value в качестве начального значения CRC, и возвращает результат. Используется полином CRC-CCITT x¹⁶ + x¹² + x⁵ + 1, часто представляемый как 0x1021. Эта CRC используется в формате binhex4.

binascii.crc32(data[, value])

Вычисляет CRC-32 — беззнаковую 32-битную контрольную сумму для data, используя value в качестве начального значения CRC. По умолчанию начальное значение CRC равно нулю. Алгоритм соответствует алгоритму контрольной суммы файлов ZIP. Поскольку алгоритм предназначен для использования в качестве алгоритма контрольной суммы, он не подходит для применения в качестве универсального алгоритма хеширования. Используйте его следующим образом:

print(binascii.crc32(b"hello world"))
# Or, in two pieces:
crc = binascii.crc32(b"hello")
crc = binascii.crc32(b" world", crc)
print('crc32 = {:#010x}'.format(crc))

Изменено в версии 3.0: Результат всегда является беззнаковым.

binascii.b2a_hex(data[, sep[, bytes_per_sep=1]])

binascii.hexlify(data[, sep[, bytes_per_sep=1]])

Возвращает шестнадцатеричное представление двоичных данных data. Каждый байт data преобразуется в соответствующее двухзначное шестнадцатеричное представление. Поэтому возвращаемый объект bytes вдвое длиннее data.

Аналогичные возможности (с возвратом текстовой строки) также доступны с помощью метода bytes.hex().

Если указан sep, он должен быть односимвольным объектом str или bytes. Он будет вставляться в результат после каждых bytes_per_sep входных байтов. По умолчанию положение разделителя отсчитывается от правого конца результата; чтобы отсчитывать его слева, укажите отрицательное значение bytes_per_sep.

>>> import binascii
>>> binascii.b2a_hex(b'\xb9\x01\xef')
b'b901ef'
>>> binascii.hexlify(b'\xb9\x01\xef', '-')
b'b9-01-ef'
>>> binascii.b2a_hex(b'\xb9\x01\xef', b'_', 2)
b'b9_01ef'
>>> binascii.b2a_hex(b'\xb9\x01\xef', b' ', -2)
b'b901 ef'

Изменено в версии 3.8: Добавлены параметры sep и bytes_per_sep.

binascii.a2b_hex(hexstr)

binascii.unhexlify(hexstr)

Возвращает двоичные данные, представленные шестнадцатеричной строкой hexstr. Эта функция является обратной по отношению к b2a_hex(). hexstr должна содержать чётное число шестнадцатеричных цифр (в верхнем или нижнем регистре), иначе будет вызвано исключение Error.

Аналогичные возможности (с более свободной обработкой пробелов) также доступны с помощью метода класса bytes.fromhex().

exception binascii.Error

Исключение, возникающее при ошибках. Обычно это ошибки программирования.

exception binascii.Incomplete

Исключение, возникающее при неполных данных. Обычно это не ошибки программирования, но их можно обработать, считав ещё немного данных и повторив попытку.