binascii – Преобразование между двоичным представлением и ASCII¶binascii – Convert between binary and ASCII

Модуль binascii содержит несколько методов для преобразования между двоичным представлением и различными ASCII-кодированными двоичными представлениями. Обычно эти функции не используются напрямую – вместо них применяются модули-обёртки, такие как 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, /, *, padded=True, alphabet=BASE64_ALPHABET, strict_mode=False, canonical=False)¶

binascii.a2b_base64(string, /, *, ignorechars, padded=True, alphabet=BASE64_ALPHABET, strict_mode=True, canonical=False)

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

Необязательный параметр alphabet должен быть объектом bytes длиной 64, который задаёт альтернативный алфавит.

Если padded равен true, последняя группа из 4 символов алфавита base64 должна быть дополнена символом '='. Если padded равен false, дополнение не требуется и не распознаётся: символ '=' не считается дополнением, а рассматривается как символ, не входящий в алфавит, и значит, он молча отбрасывается, когда strict_mode равен false, или вызывает Error, когда strict_mode равен true, если только b'=' не включён в ignorechars.

Если указан ignorechars, он должен быть bytes-подобным объектом, содержащим символы, которые следует игнорировать во входных данных, когда strict_mode равен true. Если ignorechars содержит символ-дополнитель '=', то символы дополнения, встречающиеся до конца закодированных данных, а также лишние символы дополнения будут проигнорированы. Значение по умолчанию strict_mode равно True, если указан ignorechars, иначе False.

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

Корректный base64:

• Соответствует спецификации RFC 4648.

• Содержит только символы алфавита base64.

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

• Не начинается с символа заполнения.

Если canonical равен true, ненулевые биты дополнения в последней группе отвергаются с binascii.Error, что обеспечивает каноническое кодирование, как определено в RFC 4648, раздел 3.5. Эта проверка не зависит от strict_mode.

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

Изменено в версии 3.15: Добавлены параметры alphabet, canonical, ignorechars и padded.

binascii.b2a_base64(data, *, padded=True, alphabet=BASE64_ALPHABET, wrapcol=0, newline=True)¶

Преобразует двоичные данные в строку (или строки) символов ASCII в кодировке base64, как указано в спецификации RFC 4648.

Если padded равен true (по умолчанию), дополнить закодированные данные символом '=' до размера, кратного 4. Если padded равен false, символы дополнения не добавляются.

Если wrapcol не равен нулю, вставлять символ новой строки (b'\n') не более чем после каждых wrapcol символов. Если wrapcol равен нулю (по умолчанию), не вставлять ни одной новой строки.

Если newline равен true (по умолчанию), в конец вывода будет добавлен символ новой строки.

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

Изменено в версии 3.15: Добавлены параметры alphabet, padded и wrapcol.

binascii.a2b_ascii85(string, /, *, foldspaces=False, adobe=False, ignorechars=b'', canonical=False)¶

Преобразует данные Ascii85 обратно в двоичные и возвращает двоичные данные.

Корректные данные Ascii85 содержат символы алфавита Ascii85, сгруппированные по пять символов (за исключением последней группы, которая может содержать от двух до пяти символов). Каждая группа кодирует 32 бита двоичных данных в диапазоне от 0 до 2 ** 32 - 1 включительно. Специальный символ z принимается как сокращённая форма группы !!!!!, которая кодирует четыре байта нулей. Последняя группа из одного символа всегда отвергается как нарушение кодирования.

foldspaces – это флаг, указывающий, следует ли принимать короткую последовательность 'y' в качестве сокращения для 4 последовательных пробелов (ASCII 0x20). Эта возможность не поддерживается «стандартной» кодировкой Ascii85.

adobe управляет тем, обрамляется ли закодированная последовательность байтов символами <~ и ~>, как в строковом литерале PostScript base-85. Если adobe равен true, начальный символ <~ опционально принимается, а завершающий символ ~> обязателен, и возбуждается binascii.Error, если он не найден.

ignorechars должен быть bytes-подобным объектом, содержащим символы, которые следует игнорировать во входных данных. Он должен содержать только пробельные символы.

Если canonical равен true, неканонические кодирования отвергаются с binascii.Error. Здесь «каноническое» означает кодирование, которое дала бы b2a_ascii85(): для полностью нулевых групп должна использоваться аббревиатура z (а не !!!!!), а неполные последние группы должны использовать те же символы дополнения, что и кодировщик.

Некорректные данные Ascii85 приведут к возбуждению binascii.Error.

Добавлено в версии 3.15.

binascii.b2a_ascii85(data, /, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)¶

Преобразует двоичные данные в форматированную последовательность символов ASCII в кодировке Ascii85. Возвращаемое значение – преобразованные данные.

foldspaces – необязательный флаг, который использует специальную короткую последовательность 'y' вместо 4 последовательных пробелов (ASCII 0x20), как поддерживается в 'btoa'. Эта возможность не поддерживается «стандартной» кодировкой Ascii85.

Если wrapcol не равен нулю, вставлять символ новой строки (b'\n') не более чем после каждых wrapcol символов. Если wrapcol равен нулю (по умолчанию), не вставлять ни одной новой строки.

Если pad равен true, дополнение нулями, применённое к концу входных данных, полностью сохраняется в выходной кодировке, как это делает btoa, что даёт выходные данные, кратные 5 байтам. Это не является частью стандартной кодировки, используемой в PDF, так как она не сохраняет длину данных.

adobe управляет, обрамляется ли закодированная последовательность байтов маркерами <~ и ~>, как в строковом литерале PostScript base-85. Обратите внимание: хотя потоки ASCII85Decode в документах PDF должны завершаться ~>, они не должны использовать начальный <~.

Добавлено в версии 3.15.

binascii.a2b_base85(string, /, *, alphabet=BASE85_ALPHABET, ignorechars=b'', canonical=False)¶

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

Допустимые данные в кодировке Base85 содержат символы из алфавита Base85, сгруппированные по пять (кроме последней группы, которая может содержать от двух до пяти символов). Каждая группа кодирует 32 бита двоичных данных в диапазоне от 0 до 2 ** 32 - 1 включительно. Последняя группа из одного символа всегда отклоняется как нарушение кодировки.

Необязательный параметр alphabet должен быть объектом bytes длиной 85, который задаёт альтернативный алфавит.

Параметр ignorechars должен быть байтовым объектом, содержащим символы, которые следует игнорировать во входных данных.

Если canonical имеет значение true, неканонические кодировки отклоняются с помощью binascii.Error. Здесь «каноническая» означает кодировку, которую создала бы функция b2a_base85(): частичные конечные группы должны использовать те же дополняющие цифры, что и кодировщик.

Недопустимые данные в кодировке Base85 вызовут исключение binascii.Error.

Добавлено в версии 3.15.

binascii.b2a_base85(data, /, *, alphabet=BASE85_ALPHABET, wrapcol=0, pad=False)¶

Преобразовывает двоичные данные в строку символов ASCII в кодировке Base85. Возвращаемое значение – преобразованная строка.

Необязательный параметр alphabet должен быть байтовым объектом длиной 85, который задаёт альтернативный алфавит.

Если wrapcol не равно нулю, вставляет символ новой строки (b'\n') не чаще чем после каждых wrapcol символов. Если wrapcol равно нулю (по умолчанию), символы новой строки не вставляются.

Если pad имеет значение true, нулевое дополнение, применённое к концу входных данных, сохраняется в выходных, которые всегда будут кратны 5 байтам, и поэтому длина данных может не сохраниться при декодировании.

Добавлено в версии 3.15.

binascii.a2b_base32(string, /, *, padded=True, alphabet=BASE32_ALPHABET, ignorechars=b'', canonical=False)¶

Преобразовывает данные в кодировке base32 обратно в двоичные и возвращает двоичные данные.

Допустимые данные в кодировке base32 содержат символы из алфавита base32, указанного в RFC 4648, сгруппированные по восемь (при необходимости последняя группа дополняется до восьми символов символом =). Каждая группа кодирует 40 бит двоичных данных в диапазоне от 0 до 2 ** 40 - 1 включительно.

Примечание

Эта функция не преобразует строчные символы (которые недопустимы в стандартном base32) в их заглавные эквиваленты, а также не выполняет контекстное отображение 0 на O и 1 на I/L, как это разрешено в RFC 4648.

Необязательный параметр alphabet должен быть объектом bytes длиной 32, который задаёт альтернативный алфавит.

Если padded имеет значение true, последняя группа из 8 символов алфавита base32 должна быть дополнена символом «=». Если padded имеет значение false, символ «=» обрабатывается как другие неалфавитные символы (в зависимости от значения ignorechars).

Параметр ignorechars должен быть байтовым объектом, содержащим символы, которые следует игнорировать во входных данных. Если ignorechars содержит символ дополнения '=', то символы дополнения, встреченные до конца закодированных данных, а также лишние символы дополнения будут игнорироваться.

Если canonical имеет значение true, ненулевые дополняющие биты в последней группе отклоняются с помощью binascii.Error, обеспечивая каноническую кодировку, как определено в RFC 4648, раздел 3.5.

Недопустимые данные в кодировке base32 вызовут исключение binascii.Error.

Добавлено в версии 3.15.

binascii.b2a_base32(data, /, *, padded=True, alphabet=BASE32_ALPHABET, wrapcol=0)¶

Преобразовывает двоичные данные в строку символов ASCII в кодировке base32, как указано в RFC 4648. Возвращаемое значение – преобразованная строка.

Необязательный параметр alphabet должен быть байтовым объектом длиной 32, который задаёт альтернативный алфавит.

Если padded имеет значение true (по умолчанию), дополните закодированные данные символом «=» до размера, кратного 8. Если padded имеет значение false, символы дополнения не добавляйте.

Если wrapcol не равно нулю, вставляет символ новой строки (b'\n') не чаще чем после каждых wrapcol символов. Если wrapcol равно нулю (по умолчанию), символы новой строки не вставляются.

Добавлено в версии 3.15.

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)¶

Вычисляет 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"))
# Или двумя частями:
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, *, ignorechars=b'')¶

binascii.unhexlify(hexstr, *, ignorechars=b'')¶

Возвращает двоичные данные, представленные шестнадцатеричной строкой hexstr. Эта функция является обратной к b2a_hex(). hexstr должна содержать чётное количество шестнадцатеричных цифр (может быть в верхнем или нижнем регистре), в противном случае вызывается исключение Error.

ignorechars должно быть байтоподобным объектом, содержащим символы, которые следует игнорировать во входных данных.

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

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

exception binascii.Error¶

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

exception binascii.Incomplete¶

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

binascii.BASE64_ALPHABET¶

Алфавит Base 64 в соответствии с RFC 4648.

Добавлено в версии 3.15.

binascii.URLSAFE_BASE64_ALPHABET¶

Алфавит Base 64, безопасный для URL и имён файлов, в соответствии с RFC 4648.

Добавлено в версии 3.15.

binascii.UU_ALPHABET¶

Алфавит uuencoding.

Добавлено в версии 3.15.

binascii.CRYPT_ALPHABET¶

Алфавит Base 64, используемый в процедуре crypt(3) и в формате GEDCOM.

Добавлено в версии 3.15.

binascii.BINHEX_ALPHABET¶

Алфавит Base 64, используемый в BinHex 4 (HQX) в классической Mac OS.

Добавлено в версии 3.15.

binascii.BASE85_ALPHABET¶

Алфавит Base85.

Добавлено в версии 3.15.

binascii.ASCII85_ALPHABET¶

Алфавит Ascii85.

Добавлено в версии 3.15.

binascii.Z85_ALPHABET¶

Алфавит Z85.

Добавлено в версии 3.15.

binascii.BASE32_ALPHABET¶

Алфавит Base 32 в соответствии с RFC 4648.

Добавлено в версии 3.15.

binascii.BASE32HEX_ALPHABET¶

Алфавит Base 32 «Extended Hex» в соответствии с RFC 4648. Данные, закодированные этим алфавитом, сохраняют свой порядок сортировки при побитовом сравнении.

Добавлено в версии 3.15.