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

Источник: Lib/base64.py

---

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

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

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

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

Изменено в версии 3.3: Строки Unicode только в формате ASCII теперь принимаются функциями декодирования современного интерфейса.

Изменено в версии 3.4: Любые bytes-like objects теперь принимаются всеми функциями кодирования и декодирования в этом модуле. Добавлена поддержка Ascii85/Base85.

Современный интерфейс обеспечивает:

base64.b64encode(s, altchars=None)

Закодируйте bytes-like object s с помощью Base64 и верните закодированный bytes.

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

Может утверждать или вызывать сообщение ValueError, если длина altchars не равна 2. Вызывает сообщение TypeError, если altchars не является bytes-like object.

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

Декодирует Base64-кодировку bytes-like object или ASCII-строку s и возвращает декодированную bytes.

Необязательная altchars должна быть строкой bytes-like object или 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-like object s с использованием стандартного алфавита Base64 и возвращает закодированный bytes.

base64.standard_b64decode(s)

Декодируйте bytes-like object или ASCII-строку s, используя стандартный алфавит Base64, и верните декодированную bytes.

base64.urlsafe_b64encode(s)

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

base64.urlsafe_b64decode(s)

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

base64.b32encode(s)

Закодируйте bytes-like object s с помощью Base32 и верните закодированный bytes.

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

Декодирует закодированную в Base32 bytes-like object или ASCII строку s и возвращает декодированную 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.

Added in version 3.10.

base64.b32hexdecode(s, casefold=False)

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

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

Added in version 3.10.

base64.b16encode(s)

Закодируйте bytes-like object s с помощью Base16 и верните закодированный bytes.

base64.b16decode(s, casefold=False)

Декодируйте закодированную в Base16 bytes-like object или ASCII строку s и верните декодированную bytes.

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

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

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

Закодируйте bytes-like object b с помощью Ascii85 и верните закодированный bytes.

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

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

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

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

Added in version 3.4.

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

Декодируйте закодированную в Ascii85 bytes-like object или ASCII-строку b и верните декодированную bytes.

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

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

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

Added in version 3.4.

base64.b85encode(b, pad=False)

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

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

Added in version 3.4.

base64.b85decode(b)

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

Added in version 3.4.

base64.z85encode(s)

Закодируйте bytes-like object s с помощью Z85 (как используется в ZeroMQ) и возвращает закодированный bytes. Дополнительную информацию см. в разделе Z85 specification.

Added in version 3.13.

base64.z85decode(s)

Декодируйте закодированную в Z85 bytes-like object или ASCII-строку s и верните декодированную bytes. Дополнительную информацию см. в разделе Z85 specification.

Added in version 3.13.

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

base64.decode(input, output)

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

base64.decodebytes(s)

Декодируйте bytes-like object s, которые должны содержать одну или несколько строк данных в кодировке base64, и вернуть декодированный bytes.

Added in version 3.1.

base64.encode(input, output)

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

base64.encodebytes(s)

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

Added in version 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'

Соображения безопасности

В RFC 4648 был добавлен новый раздел о мерах безопасности (раздел 12); рекомендуется просматривать раздел о мерах безопасности для любого кода, развертываемого в производстве.

См.также

Модуль binascii

Модуль поддержки, содержащий преобразования ASCII в двоичный код и двоичного кода в ASCII.

RFC 1521 - MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies

В разделе 5.2, «Base64 Content-Transfer-Encoding», дается определение кодировки base64.