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

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