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

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

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

binascii.a2b_uu(string)

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

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

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

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

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

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

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

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

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

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

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

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

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

binascii.a2b_qp(data, header=False)

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

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

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

binascii.crc_hqx(data, value)

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

binascii.crc32(data[, value])

Вычисляет CRC-32, 32-разрядную контрольную сумму данных data, начиная с начального значения CRC value. По умолчанию начальное значение 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 преобразуется в соответствующее 2-значное шестнадцатеричное представление. Возвращаемый объект байтов, следовательно, вдвое длиннее длины 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

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