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

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

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

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

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

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

Современный интерфейс предоставляет следующие функции:

base64.b64encode(s, altchars=None)

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

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

Может вызвать утверждение или исключение ValueError, если длина altchars не равна 2. Вызывает исключение TypeError, если altchars не является объектом, подобным bytes.

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

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

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

Если строка s имеет неверные символы дополнения, возникает исключение binascii.Error.

Если validate равно False (значение по умолчанию), символы, не входящие ни в обычную алфавитную таблицу base-64, ни в альтернативную, отбрасываются перед проверкой символов дополнения. Если validate равно True, наличие во входных данных символов, не принадлежащих алфавиту, приводит к исключению binascii.Error.

Подробнее о строгой проверке base64 см. в описании binascii.a2b_base64()

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

base64.standard_b64encode(s)

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

base64.standard_b64decode(s)

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

base64.urlsafe_b64encode(s)

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

base64.urlsafe_b64decode(s)

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

base64.b32encode(s)

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

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

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

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

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

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

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 s с помощью Base16 и возвращает закодированный объект bytes.

base64.b16decode(s, casefold=False)

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

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

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

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

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

foldspaces — это необязательный флаг, включающий использование специальной короткой последовательности ‘y’ вместо четырёх последовательных пробелов (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')

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

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

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

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

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

base64.b85encode(b, pad=False)

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

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

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

base64.b85decode(b)

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

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

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

base64.decode(input, output)

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

base64.decodebytes(s)

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

Добавлено в версии 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)

Кодирует объект, подобный bytes s, который может содержать произвольные двоичные данные, и возвращает bytes с данными, закодированными в base64. После каждых 76 байтов выходных данных вставляются символы новой строки (b'\n'), а в конце обязательно добавляется завершающий символ новой строки, в соответствии с 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'