19.6. base64 – кодировки Base16, Base32, Base64, Base85¶base64 – Base16, Base32, Base64, Base85 Data Encodings

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

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

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

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

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

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

base64.b64encode(s, altchars=None)¶

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

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

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.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 3548 допускает необязательное отображение цифры 0 (ноль) на букву O (о) и необязательное отображение цифры 1 (один) на букву I(ай) или букву L (эл). Необязательный аргумент map01, когда он не None, указывает, на какую букву должна отображаться цифра 1 (когда map01 не None, цифра 0 всегда отображается на букву O). Из соображений безопасности значением по умолчанию является None, поэтому цифры 0 и 1 не допускаются во входных данных.

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

base64.b16encode(s)¶

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

base64.b16decode(s, casefold=False)¶

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

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

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

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

Кодирует байтоподобный объект 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\\v')¶

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

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

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

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

Новое в версии 3.4.

base64.b85encode(b, pad=False)¶

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

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

Новое в версии 3.4.

base64.b85decode(b)¶

Декодирует закодированный в base85 байтоподобный объект или строку ASCII b и возвращает декодированный bytes. Дополнение неявно удаляется при необходимости.

Новое в версии 3.4.

Устаревший интерфейс:

base64.decode(input, output)¶

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

base64.decodebytes(s)¶

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

Новое в версии 3.1.

base64.decodestring(s)¶

Устаревший псевдоним для decodebytes().

Устарело с версии 3.1.

base64.encode(input, output)¶

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

base64.encodebytes(s)¶

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

Новое в версии 3.1.

base64.encodestring(s)¶

Устаревший псевдоним для encodebytes().

Устарело с версии 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'