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 истинно, нули представляются символом '`', а не пробелами.

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

binascii.a2b_base64(string, /, *, strict_mode=False)

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

Если значение strict_mode истинно, будут преобразованы только корректные данные base64. При некорректных данных base64 будет вызвано исключение binascii.Error.

Корректные данные base64:

• Соответствуют RFC 3548.
• Содержат только символы из алфавита base64.
• Не содержат лишних данных после заполнения (включая лишние символы заполнения, символы новой строки и т. д.).
• Не начинаются с символа заполнения.

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

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

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

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

binascii.a2b_qp(data, header=False)

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

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

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

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, используя value в качестве начального значения CRC. Начальное значение 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, он должен быть односимвольной строкой 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

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