base64 – кодирование данных Base16, Base32, Base64, Base85¶base64 – Base16, Base32, Base64, Base85 Data Encodings

Кодировки RFC 4648¶RFC 4648 Encodings

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

base64.b64encode(s, altchars=None, *, padded=True, wrapcol=0)¶

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

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

Если padded равен True (по умолчанию), закодированные данные дополняются символом ‘=’ до размера, кратного 4. Если padded равен False, символы дополнения не добавляются.

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

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

base64.b64decode(s, altchars=None, validate=False, *, padded=True, canonical=False)¶

base64.b64decode(s, altchars=None, validate=True, *, ignorechars, padded=True, canonical=False)

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

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

Если padded равен True, последняя группа из 4 символов алфавита base64 должна быть дополнена символом ‘=’. Если padded равен False, дополнение не требуется и не распознаётся: символ ‘=’ рассматривается не как дополнение, а как символ вне алфавита; это означает, что он молча отбрасывается, когда validate равен False, или вызывает Error, когда validate равен True, если только b’=’ не включён в ignorechars.

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

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

Если validate равен False, символы, не входящие ни в основной алфавит base64, ни (если не указан ignorechars) в альтернативный алфавит, отбрасываются до проверки дополнения; однако символы + и / сохраняют своё значение, если они не входят в altchars (в будущих версиях Python они будут отбрасываться).

Если validate равен True, эти символы вне алфавита во входных данных приводят к binascii.Error.

Если canonical равен True, ненулевые биты дополнения отвергаются. Подробнее см. binascii.a2b_base64().

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

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

Устарело с версии 3.15: Приём символов + и / с альтернативным алфавитом теперь устарел.

base64.standard_b64encode(s)¶

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

base64.standard_b64decode(s)¶

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

base64.urlsafe_b64encode(s, *, padded=True)¶

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

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

base64.urlsafe_b64decode(s, *, padded=False)¶

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

Изменено в версии 3.15: Добавлен параметр padded. Дополнение входных данных больше не требуется по умолчанию.

Устарело с версии 3.15: Приём символов + и / теперь устарел.

base64.b32encode(s, *, padded=True, wrapcol=0)¶

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

Если padded равен True (по умолчанию), закодированные данные дополняются символом ‘=’ до размера, кратного 8. Если padded равен False, символы дополнения не добавляются.

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

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

base64.b32decode(s, casefold=False, map01=None, *, padded=True, ignorechars=b'', canonical=False)¶

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

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

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

Если padded равен True, последняя группа из 8 символов алфавита base32 должна быть дополнена символом ‘=’. Если padded равен False, дополнение не требуется и не распознаётся: символ ‘=’ рассматривается не как дополнение, а как символ вне алфавита; это означает, что он вызывает Error, если только b’=’ не включён в ignorechars.

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

Если canonical равен True, ненулевые биты дополнения отвергаются. Подробнее см. binascii.a2b_base32().

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

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

base64.b32hexencode(s, *, padded=True, wrapcol=0)¶

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

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

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

base64.b32hexdecode(s, casefold=False, *, padded=True, ignorechars=b'', canonical=False)¶

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

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

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

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

base64.b16encode(s, *, wrapcol=0)¶

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

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

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

base64.b16decode(s, casefold=False, *, ignorechars=b'')¶

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

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

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

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

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

Кодировки Base85¶Base85 Encodings

Кодировка Base85 – это семейство алгоритмов, которые представляют четыре байта с помощью пяти ASCII-символов. Изначально реализованная в утилите Unix btoa(1), её версия позже была принята Adobe в языке PostScript и стандартизирована в PDF 2.0 (ISO 32000-2). Эта версия, как в варианте btoa, так и в варианте PDF, реализована в a85encode().

Отдельная версия, использующая другой набор выходных символов, была определена как первоапрельская шутка в RFC 1924, но теперь используется Git и другим программным обеспечением. Эта версия реализована в b85encode().

Наконец, третья версия, использующая еще один набор выходных символов, предназначенный для безопасного включения в строки языков программирования, определена ZeroMQ и реализована здесь в z85encode().

Функции, представленные в этом модуле, различаются тем, как они обрабатывают следующее:

• Нужно ли включать и ожидать обрамляющие маркеры <~ и ~>.

• Нужно ли разбивать входные данные на несколько строк.

• Набор ASCII-символов, используемых для кодирования.

• Компактное кодирование последовательностей пробелов и нулевых байтов.

• Кодирование байтов нулевого дополнения, применяемых к входным данным.

Обратитесь к документации отдельных функций для получения дополнительной информации.

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

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

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

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

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

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

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

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

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

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

adobe управляет наличием маркеров <~ и ~>. Хотя начальный <~ не требуется, входные данные должны заканчиваться на ~>, иначе будет вызвано ValueError.

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

Если canonical имеет значение true, неканонические кодировки отклоняются. Подробнее см. binascii.a2b_ascii85().

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

Изменено в версии 3.15: Добавлен параметр canonical. Односимвольные конечные группы теперь всегда отклоняются как нарушение кодировки.

base64.b85encode(b, pad=False, *, wrapcol=0)¶

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

Входные данные дополняются b'\0', чтобы их длина была кратна 4 байтам перед кодированием. Если pad истинно, все результирующие символы сохраняются в выходных данных, которые всегда будут кратны 5 байтам, и поэтому длина данных может не сохраниться при декодировании.

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

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

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

base64.b85decode(b, *, ignorechars=b'', canonical=False)¶

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

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

Если canonical имеет значение true, неканонические кодировки отклоняются. Подробнее см. binascii.a2b_base85().

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

Изменено в версии 3.15: Добавлены параметры canonical и ignorechars. Односимвольные конечные группы теперь всегда отклоняются как нарушение кодировки.

base64.z85encode(s, pad=False, *, wrapcol=0)¶

Кодирует байтоподобный объект s с помощью Z85 (используется в ZeroMQ) и возвращает закодированный bytes.

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

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

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

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

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

base64.z85decode(s, *, ignorechars=b'', canonical=False)¶

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

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

Если canonical имеет значение true, неканонические кодировки отклоняются. Подробнее см. binascii.a2b_base85().

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

Изменено в версии 3.15: Добавлены параметры canonical и ignorechars. Односимвольные конечные группы теперь всегда отклоняются как нарушение кодировки.

Устаревший интерфейс¶Legacy Interface

base64.decode(input, output)¶

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

base64.decodebytes(s)¶

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

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

Вопросы безопасности¶Security Considerations

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