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

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

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

binascii.a2b_uu(string)

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

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

Преобразует двоичные данные в строку ASCII-символов, результат — преобразованная строка, включающая символ новой строки. Длина data должна быть не более 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) иметь оставшиеся биты равными нулю.

binascii.rledecode_hqx(data)

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

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

binascii.rlecode_hqx(data)

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

binascii.b2a_hqx(data)

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

binascii.crc_hqx(data, value)

Вычисляет значение CRC-16 для 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 используйте crc32(data) & 0xffffffff.

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

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