base64 — Кодировки данных Base16, Base32, Base64, Base85

Исходный код: Lib/base64.py

Этот модуль предоставляет функции для кодирования двоичных данных в печатные ASCII-символы и декодирования таких кодировок обратно в двоичные данные. Он предоставляет функции кодирования и декодирования для кодировок, определённых в RFC 4648, который определяет алгоритмы Base16, Base32 и Base64, а также для фактических стандартов кодировок Ascii85 и Base85.

Кодировки RFC 4648 подходят для кодирования двоичных данных, чтобы их можно было безопасно отправлять по электронной почте, использовать в качестве частей URL-адресов или включать в часть запроса HTTP POST. Алгоритм кодирования отличается от программы uuencode.

Этот модуль предоставляет два интерфейса. Современный интерфейс поддерживает кодирование объектов типа байты в ASCII bytes и декодирование объектов типа байты или строк, содержащих ASCII, в bytes. Поддерживаются оба алфавита base-64, определённые в RFC 4648 (обычный, а также безопасный для URL и файловых систем).

Устаревший интерфейс не поддерживает декодирование из строк, но он предоставляет функции для кодирования и декодирования в и из объектов файлов. Он поддерживает только стандартный алфавит Base64 и добавляет новые строки каждые 76 символов, как указано в RFC 2045. Обратите внимание, что если вам нужна поддержка RFC 2045, вам, вероятно, следует обратиться к пакету email вместо этого.

Современный интерфейс предоставляет:

base64.b64encode(s, altchars=None)

Кодирует объект-последовательность байтов s с использованием Base64 и возвращает закодированную bytes.

Необязательный параметр altchars должен быть объектом-последовательностью байтов длиной 2, который указывает альтернавный алфавит для символов + и /. Это позволяет приложению, например, генерировать строки Base64, безопасные для использования в URL или файловых системах. По умолчанию используется None, что соответствует стандартному алфавиту Base64.

Может утверждать или генерировать исключение ValueError, если длина altchars не равна 2. Генерирует исключение TypeError, если altchars не является объектом-последовательностью байтов.

base64.b64decode(s, altchars=None, validate=False)

Декодирует закодированную в Base64 последовательность байтов или строку ASCII s и возвращает декодированную bytes.

Необязательный параметр altchars должен быть объектом-последовательностью байтов или строкой ASCII длиной 2, которая указывает альтернативный алфавит, используемый вместо символов + и /.

Исключение binascii.Error генерируется, если s неверно дополнено.

Если validate равно False (по умолчанию), символы, которые не являются ни символами обычного алфавита Base-64, ни символами альтернативного алфавита, отбрасываются до проверки дополнения. Если validate равно True, эти символы вне алфавита в входных данных приводят к исключению binascii.Error.

Дополнительная информация о строгой проверке Base64 см. в binascii.a2b_base64()

Может утверждать или генерировать исключение ValueError, если длина altchars не равна 2.

base64.standard_b64encode(s)

Кодирует объект-последовательность байтов s с использованием стандартного алфавита Base64 и возвращает закодированную bytes.

base64.standard_b64decode(s)

Декодирует объект-последовательность байтов или строку ASCII s с использованием стандартного алфавита Base64 и возвращает декодированную bytes.

base64.urlsafe_b64encode(s)

Кодирует объект-последовательность байтов s с использованием URL- и файлобезопасного алфавита, который заменяет - вместо + и _ вместо / в стандартном алфавите Base64, и возвращает закодированную bytes. Результат может всё ещё содержать =.

base64.urlsafe_b64decode(s)

Декодирует объект-последовательность байтов или строку ASCII s с использованием URL- и файлобезопасного алфавита, который заменяет - вместо + и _ вместо / в стандартном алфавите Base64, и возвращает декодированную bytes.

base64.b32encode(s)

Кодирует объект-последовательность байтов s с использованием Base32 и возвращает закодированную bytes.

base64.b32decode(s, casefold=False, map01=None)

Декодирует закодированную в Base32 последовательность байтов или строку ASCII s и возвращает декодированную bytes.

Необязательный параметр casefold указывает, допускается ли ввод в нижнем регистре. По соображениям безопасности, по умолчанию используется False.

RFC 4648 допускает необязательное отображение цифры 0 (ноль) на букву O (о), и необязательное отображение цифры 1 (один) на букву I (ай) или букву L (эл). Необязательный аргумент map01, когда он не None, указывает, на какую букву должна быть отображена цифра 1 (когда map01 не None, цифра 0 всегда отображается на букву O). По соображениям безопасности, по умолчанию используется None, чтобы цифры 0 и 1 не допускались в вводе.

Исключение binascii.Error генерируется, если s неверно дополнено или если в вводе присутствуют символы, не являющиеся символами алфавита.

base64.b32hexencode(s)

Аналогично b32encode(), но использует расширенный шестнадцатеричный алфавит, как определено в RFC 4648.

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

base64.b32hexdecode(s, casefold=False)

Аналогично b32decode(), но использует Расширенный шестнадцатеричный алфавит, как определено в RFC 4648.

Данная версия не допускает сопоставления цифры 0 (ноль) с буквой O (о), а также цифры 1 (один) с буквами I (ай) или L (эль). Все эти символы включены в Расширенный шестнадцатеричный алфавит и не взаимозаменяемы.

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

base64.b16encode(s)

Кодирует объект типа bytes-like s с использованием Base16 и возвращает закодированную последовательность bytes.

base64.b16decode(s, casefold=False)

Декодирует закодированную в Base16 последовательность объекта типа bytes-like или строку ASCII s и возвращает декодированную последовательность bytes.

Необязательный параметр casefold — флаг, указывающий, допускается ли использование строчных букв в качестве входных данных. В целях безопасности, значение по умолчанию — False.

Исключение binascii.Error возникает, если последовательность s имеет неправильную длину или содержит символы, не являющиеся частью алфавита.

base64.a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)

Кодирует объект типа bytes-like b с использованием Ascii85 и возвращает закодированную последовательность bytes.

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

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

pad управляет тем, будет ли входные данные дополнены до кратности 4 перед кодированием. Обратите внимание, что реализация btoa всегда дополняет данные.

adobe управляет тем, будет ли закодированная последовательность байтов обрамлена символами <~ и ~>, что используется в реализации Adobe.

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

base64.a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\x0b')

Декодирует закодированную в Ascii85 последовательность объекта типа bytes-like или строку ASCII b и возвращает декодированную последовательность bytes.

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

adobe управляет тем, находится ли входная последовательность в формате Adobe Ascii85 (т.е. обрамлена символами <~ и ~>).

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

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

base64.b85encode(b, pad=False)

Кодирует объект типа bytes-like b с использованием base85 (как используется, например, в бинарных различиях в стиле git) и возвращает закодированную последовательность bytes.

Если pad равно True, входные данные дополняются b'\0', чтобы их длина была кратной 4 байтам перед кодированием.

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

base64.b85decode(b)

Декодирует закодированную в base85 последовательность объекта типа bytes-like или строку ASCII b и возвращает декодированную последовательность bytes. Дополнения, при необходимости, неявно удаляются.

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

Легальный интерфейс:

base64.decode(input, output)

Декодирует содержимое бинарного файла input и записывает полученные бинарные данные в файл output. input и output должны быть объектами файла. Файл input будет читаться до тех пор, пока input.readline() не вернёт пустой байтовый объект.

base64.decodebytes(s)

Декодирует объект типа bytes-like s, который должен содержать одну или несколько строк данных, закодированных в base64, и возвращает декодированную последовательность bytes.

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

base64.encode(input, output)

Кодирует содержимое бинарного файла input и записывает полученные данные, закодированные в base64, в файл output. input и output должны быть объектами файла. Файл input будет читаться до тех пор, пока input.read() не вернёт пустой байтовый объект. encode() вставляет символ новой строки (b'\n') после каждых 76 байт выходных данных, а также гарантирует, что вывод всегда заканчивается символом новой строки, в соответствии с RFC 2045 (MIME).

base64.encodebytes(s)

Кодирует объект типа bytes-like s, который может содержать произвольные бинарные данные, и возвращает последовательность bytes, содержащую данные, закодированные в base64, с символами новой строки (b'\n') после каждых 76 байт вывода и гарантирует наличие символа новой строки в конце, в соответствии с RFC 2045 (MIME).

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

Пример использования модуля:

>>> import base64
>>> encoded = base64.b64encode(b'data to be encoded')
>>> encoded
b'ZGF0YSB0byBiZSBlbmNvZGVk'
>>> data = base64.b64decode(encoded)
>>> data
b'data to be encoded'