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

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

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

binascii.a2b_uu(string)

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

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

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

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

binascii.a2b_base64(string)

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

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.a2b_hqx(string)

Преобразует данные ASCII в формате binhex4 в двоичные данные без выполнения RLE-декомпрессии. Строка должна содержать полное количество двоичных байтов или (в случае последней части данных binhex4) иметь оставшиеся биты равными нулю.

Устарело начиная с версии 3.9.

binascii.rledecode_hqx(data)

Выполняет RLE-декомпрессию данных в соответствии со стандартом binhex4. Алгоритм использует 0x90 после байта как индикатор повторения, за которым следует счётчик. Счётчик 0 указывает значение байта 0x90. Функция возвращает декомпрессированные данные, если входные данные завершаются орфанным индикатором повторения, в этом случае генерируется исключение Incomplete.

Изменено в версии 3.2: Принимает только объекты bytestring или bytearray в качестве входных данных.

Устарело начиная с версии 3.9.

binascii.rlecode_hqx(data)

Выполняет RLE-сжатие данных в стиле binhex4 для data и возвращает результат.

Устарело начиная с версии 3.9.

binascii.b2a_hqx(data)

Выполняет преобразование двоичных данных в ASCII в формате hexbin4 и возвращает полученную строку. Аргумент уже должен быть закодирован RLE и иметь длину, кратную 3 (кроме, возможно, последнего фрагмента).

Устарело начиная с версии 3.9.

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: Результат всегда является беззнаковым. Чтобы получить то же численное значение, что и при использовании Python 2 или ранее, используйте crc32(data) & 0xffffffff.

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

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