"base64" --- Codificações de dados em Base16, Base32, Base64, Base85
********************************************************************

**Código-fonte:** Lib/base64.py

======================================================================

Este módulo fornece funções para codificar dados binários em
caracteres ASCII imprimíveis e decodificar essas codificações de volta
para dados binários. Ele fornece funções de codificação e
decodificação para as codificações especificadas em **RFC 4648**, que
define os algoritmos Base16, Base32 e Base64, e para as codificações
padrão de fato Ascii85 e Base85.

As codificações **RFC 4648** são adequadas para codificar dados
binários para que possam ser enviados com segurança por e-mail, usados
como parte de URLs ou incluídos como parte de uma solicitação HTTP
POST. O algoritmo de codificação não é o mesmo do programa
**uuencode**.

Existem duas interfaces fornecidas por este módulo. A interface
moderna oferece suporte a codificar *objetos bytes ou similares* para
"bytes" ASCII, e decodificar *objetos bytes ou similares* ou strings
contendo ASCII para "bytes". Ambos os alfabetos de base 64 definidos
em **RFC 4648** (normal e seguro para URL e sistema de arquivos) são
suportados.

A interface legada não oferece suporte a decodificação de strings, mas
fornece funções para codificação e decodificação de e para *objetos
arquivo*. Ele oferece suporte a apenas o alfabeto padrão Base64 e
adiciona novas linhas a cada 76 caracteres conforme **RFC 2045**. Note
que se você estiver procurando por suporte para **RFC 2045** você
provavelmente vai querer conferir o pacote "email".

Alterado na versão 3.3: Strings Unicode exclusivamente ASCII agora são
aceitas pelas funções de decodificação da interface moderna.

Alterado na versão 3.4: Quaisquer *objetos bytes ou similares* agora
são aceitos por todas as funções de codificação e decodificação neste
módulo. Adicionado suporte a ASCII85/Base85.

A interface moderna oferece:

base64.b64encode(s, altchars=None)

   Codifica o *objeto bytes ou similar* *s* usando Base64 e retorna o
   "bytes" codificado.

   Optional *altchars* must be a *bytes-like object* of length 2 which
   specifies an alternative alphabet for the "+" and "/" characters.
   This allows an application to e.g. generate URL or filesystem safe
   Base64 strings.  The default is "None", for which the standard
   Base64 alphabet is used.

   May assert or raise a "ValueError" if the length of *altchars* is
   not 2.  Raises a "TypeError" if *altchars* is not a *bytes-like
   object*.

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

   Decodifica o *objeto bytes ou similar* ou string ASCII *s*
   codificada em Base64 e retorna o "bytes" decodificado.

   Optional *altchars* must be a *bytes-like object* or ASCII string
   of length 2 which specifies the alternative alphabet used instead
   of the "+" and "/" characters.

   A "binascii.Error" exception is raised if *s* is incorrectly
   padded.

   If *validate* is "False" (the default), characters that are neither
   in the normal base-64 alphabet nor the alternative alphabet are
   discarded prior to the padding check.  If *validate* is "True",
   these non-alphabet characters in the input result in a
   "binascii.Error".

   May assert or raise a "ValueError" if the length of *altchars* is
   not 2.

base64.standard_b64encode(s)

   Encode *bytes-like object* *s* using the standard Base64 alphabet
   and return the encoded "bytes".

base64.standard_b64decode(s)

   Decode *bytes-like object* or ASCII string *s* using the standard
   Base64 alphabet and return the decoded "bytes".

base64.urlsafe_b64encode(s)

   Encode *bytes-like object* *s* using the URL- and filesystem-safe
   alphabet, which substitutes "-" instead of "+" and "_" instead of
   "/" in the standard Base64 alphabet, and return the encoded
   "bytes".  The result can still contain "=".

base64.urlsafe_b64decode(s)

   Decode *bytes-like object* or ASCII string *s* using the URL- and
   filesystem-safe alphabet, which substitutes "-" instead of "+" and
   "_" instead of "/" in the standard Base64 alphabet, and return the
   decoded "bytes".

base64.b32encode(s)

   Encode the *bytes-like object* *s* using Base32 and return the
   encoded "bytes".

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

   Decode the Base32 encoded *bytes-like object* or ASCII string *s*
   and return the decoded "bytes".

   *casefold* opcional é uma flag especificando se um alfabeto
   minúsculo é aceitável como entrada. Por razões de segurança, o
   padrão é "False".

   **RFC 4648** allows for optional mapping of the digit 0 (zero) to
   the letter O (oh), and for optional mapping of the digit 1 (one) to
   either the letter I (eye) or letter L (el).  The optional argument
   *map01* when not "None", specifies which letter the digit 1 should
   be mapped to (when *map01* is not "None", the digit 0 is always
   mapped to the letter O).  For security purposes the default is
   "None", so that 0 and 1 are not allowed in the input.

   A "binascii.Error" is raised if *s* is incorrectly padded or if
   there are non-alphabet characters present in the input.

base64.b32hexencode(s)

   Similar to "b32encode()" but uses the Extended Hex Alphabet, as
   defined in **RFC 4648**.

   Novo na versão 3.10.

base64.b32hexdecode(s, casefold=False)

   Similar to "b32decode()" but uses the Extended Hex Alphabet, as
   defined in **RFC 4648**.

   This version does not allow the digit 0 (zero) to the letter O (oh)
   and digit 1 (one) to either the letter I (eye) or letter L (el)
   mappings, all these characters are included in the Extended Hex
   Alphabet and are not interchangeable.

   Novo na versão 3.10.

base64.b16encode(s)

   Encode the *bytes-like object* *s* using Base16 and return the
   encoded "bytes".

base64.b16decode(s, casefold=False)

   Decode the Base16 encoded *bytes-like object* or ASCII string *s*
   and return the decoded "bytes".

   *casefold* opcional é uma flag especificando se um alfabeto
   minúsculo é aceitável como entrada. Por razões de segurança, o
   padrão é "False".

   A "binascii.Error" is raised if *s* is incorrectly padded or if
   there are non-alphabet characters present in the input.

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

   Encode the *bytes-like object* *b* using Ascii85 and return the
   encoded "bytes".

   *foldspaces* is an optional flag that uses the special short
   sequence 'y' instead of 4 consecutive spaces (ASCII 0x20) as
   supported by 'btoa'. This feature is not supported by the
   "standard" Ascii85 encoding.

   *wrapcol* controls whether the output should have newline ("b'\n'")
   characters added to it. If this is non-zero, each output line will
   be at most this many characters long.

   *pad* controls whether the input is padded to a multiple of 4
   before encoding. Note that the "btoa" implementation always pads.

   *adobe* controls whether the encoded byte sequence is framed with
   "<~" and "~>", which is used by the Adobe implementation.

   Novo na versão 3.4.

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

   Decode the Ascii85 encoded *bytes-like object* or ASCII string *b*
   and return the decoded "bytes".

   *foldspaces* is a flag that specifies whether the 'y' short
   sequence should be accepted as shorthand for 4 consecutive spaces
   (ASCII 0x20). This feature is not supported by the "standard"
   Ascii85 encoding.

   *adobe* controla se a entrada está no formato Adobe Ascii85 (ou
   seja, cercada por <~ e ~>).

   *ignorechars* should be a *bytes-like object* or ASCII string
   containing characters to ignore from the input. This should only
   contain whitespace characters, and by default contains all
   whitespace characters in ASCII.

   Novo na versão 3.4.

base64.b85encode(b, pad=False)

   Encode the *bytes-like object* *b* using base85 (as used in e.g.
   git-style binary diffs) and return the encoded "bytes".

   If *pad* is true, the input is padded with "b'\0'" so its length is
   a multiple of 4 bytes before encoding.

   Novo na versão 3.4.

base64.b85decode(b)

   Decode the base85-encoded *bytes-like object* or ASCII string *b*
   and return the decoded "bytes".  Padding is implicitly removed, if
   necessary.

   Novo na versão 3.4.

A interface legada:

base64.decode(input, output)

   Decode the contents of the binary *input* file and write the
   resulting binary data to the *output* file. *input* and *output*
   must be *file objects*. *input* will be read until
   "input.readline()" returns an empty bytes object.

base64.decodebytes(s)

   Decode the *bytes-like object* *s*, which must contain one or more
   lines of base64 encoded data, and return the decoded "bytes".

   Novo na versão 3.1.

base64.encode(input, output)

   Encode the contents of the binary *input* file and write the
   resulting base64 encoded data to the *output* file. *input* and
   *output* must be *file objects*. *input* will be read until
   "input.read()" returns an empty bytes object. "encode()" inserts a
   newline character ("b'\n'") after every 76 bytes of the output, as
   well as ensuring that the output always ends with a newline, as per
   **RFC 2045** (MIME).

base64.encodebytes(s)

   Encode the *bytes-like object* *s*, which can contain arbitrary
   binary data, and return "bytes" containing the base64-encoded data,
   with newlines ("b'\n'") inserted after every 76 bytes of output,
   and ensuring that there is a trailing newline, as per **RFC 2045**
   (MIME).

   Novo na versão 3.1.

Um exemplo de uso do módulo:

>>> import base64
>>> encoded = base64.b64encode(b'data to be encoded')
>>> encoded
b'ZGF0YSB0byBiZSBlbmNvZGVk'
>>> data = base64.b64decode(encoded)
>>> data
b'data to be encoded'


Considerações de Segurança
==========================

A new security considerations section was added to **RFC 4648**
(section 12); it's recommended to review the security section for any
code deployed to production.

Ver também:

  Módulo "binascii"
     Módulo de suporte contendo conversões ASCII para binário e
     binário para ASCII.

  **RFC 1521** - MIME (Multipurpose Internet Mail Extensions) Part
  One: Mechanisms for Specifying and Describing the Format of Internet
  Message Bodies
     Section 5.2, "Base64 Content-Transfer-Encoding," provides the
     definition of the base64 encoding.
