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)

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

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

Если указан sep, он должен быть строковым объектом или объектом 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

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