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

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

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

binascii.a2b_uu(string)

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

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