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

Кодировки RFC 4648

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

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)

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

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

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

Если validate равно False (значение по умолчанию), символы, отсутствующие в обычном алфавите Base64 и альтернативном алфавите, отбрасываются перед проверкой заполнения. Если 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-адресов и файловых систем: в стандартном алфавите Base64 символ - используется вместо +, а _ — вместо /. Возвращает закодированный bytes. Результат всё ещё может содержать =.

base64.urlsafe_b64decode(s)

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

base64.b32encode(s)

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

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

Декодирует закодированный в Base32 объект, подобный bytes, или строку 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.

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

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

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

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

Кодировки Base85

Кодирование 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)

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

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

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

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

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

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

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

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

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

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

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

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

base64.b85encode(b, pad=False)

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

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

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

base64.b85decode(b)

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

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

base64.z85encode(s)

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

Спецификация ZeroMQ требует, чтобы длина данных, закодированных в Z85, была кратна 5 байтам. Чтобы сформировать соответствующие спецификации кадры данных, необходимо дополнить входные данные для этой функции до длины, кратной 4 байтам.

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

base64.z85decode(s)

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

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

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

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'

Меры безопасности

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