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


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

Примечание

Функции a2b_* принимают Юникод строки, содержащие только символы ASCII. Другие функции принимают только байтоподобные объекты (например, bytes, bytearray и другие объекты, поддерживающие протокол буфера).

Изменено в версии 3.3: Строки Юникода, содержащие только ASCII, теперь принимаются функциями a2b_*.

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

binascii.a2b_uu(string)

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

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

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

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

binascii.a2b_base64(string)

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

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

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

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

binascii.a2b_qp(data, header=False)

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

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

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

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 для data и возвращает результат.

binascii.b2a_hqx(data)

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

binascii.crc_hqx(data, value)

Вычисляет 16-битное значение CRC data, начиная с value в качестве начального CRC, и возвращает результат. Здесь используется полином CRC-CCITT x16 + x12 + x5 + 1, часто представляемый как 0x1021. CRC используется в формате binhex4.

binascii.crc32(data[, value])

Вычисляет CRC-32, 32-битную контрольную сумму data, начиная с исходной CRC value. Начальная CRC по умолчанию равна нулю. Алгоритм согласуется с контрольной суммой ZIP-файла. Поскольку алгоритм предназначен для использования в качестве алгоритма контрольной суммы, он не подходит для использования в качестве общего алгоритма хеширования. Используйте следующим образом:

print(binascii.crc32(b"hello world"))
# Или в двух частях:
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 преобразуется в соответствующее 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

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

См.также

Модуль base64
Поддержка RFC-совместимого кодирования в стиле base64 с основанием 16, 32, 64, и 85.
Модуль binhex
Поддержка формата binhex, используемого на Macintosh.
Модуль uu
Поддержка кодировки UU, используемой в Unix.
Модуль quopri
Поддержка кодировки с возможностью печати в кавычках, используемой в MIME сообщениях электронной почты.