"base64" --- Base16, Base32, Base64, Base85 Data Encodings
**********************************************************

**Code source :** Lib/base64.py

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

This module provides functions for encoding binary data to printable
ASCII characters and decoding such encodings back to binary data. It
provides encoding and decoding functions for the encodings specified
in **RFC 4648**, which defines the Base16, Base32, and Base64
algorithms, and for the de-facto standard Ascii85 and Base85
encodings.

The **RFC 4648** encodings are suitable for encoding binary data so
that it can be safely sent by email, used as parts of URLs, or
included as part of an HTTP POST request.  The encoding algorithm is
not the same as the **uuencode** program.

There are two interfaces provided by this module.  The modern
interface supports encoding *bytes-like objects* to ASCII "bytes", and
decoding *bytes-like objects* or strings containing ASCII to "bytes".
Both base-64 alphabets defined in **RFC 4648** (normal, and URL- and
filesystem-safe) are supported.

L'interface historique ne permet pas le décodage des chaînes de
caractères mais fournit des fonctions permettant d'encoder et décoder
depuis et vers des *objets fichiers*. Elle ne gère que l'alphabet
base64 standard et ajoute une nouvelle ligne tous les 76 caractères,
comme spécifié par la **RFC 2045**. Notez que le paquet "email" est
probablement ce que vous cherchez si vous souhaitez une implémentation
de la **RFC 2045**.

Modifié dans la version 3.3: Les chaînes de caractères Unicode
contenant uniquement des caractères ASCII sont désormais acceptées par
les fonctions de décodage de l'interface moderne.

Modifié dans la version 3.4: Tous les *objets octet-compatibles* sont
désormais acceptés par l'ensemble des fonctions d'encodage et de
décodage de ce module. La gestion de Ascii85/base85 a été ajoutée.

L'interface moderne propose :

base64.b64encode(s, altchars=None)

   Encode un *objet octet-compatible* *s* en utilisant l'algorithme
   base64 et renvoie les "bytes" encodés.

   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)

   Décode un *objet octet-compatible* ou une chaîne de caractères
   ASCII *s* encodée en base64 et renvoie les "bytes" décodés.

   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.

   Une exception "binascii.Error" est levée si *s* n'est pas remplie à
   une longueur attendue.

   Si *validate* est "False" (par défaut), les caractères qui ne sont
   ni dans l'alphabet base64 normal, ni dans l'alphabet alternatif,
   sont ignorés avant la vérification de la longueur du remplissage.
   Si *validate* est "True", les caractères hors de l'alphabet de
   l'entrée produisent une "binascii.Error".

   For more information about the strict base64 check, see
   "binascii.a2b_base64()"

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

base64.standard_b64encode(s)

   Encode un *objet octet-compatible* *s* en utilisant l'alphabet
   standard base64 et renvoie les "bytes" encodés.

base64.standard_b64decode(s)

   Décode un *objet octet-compatible* ou une chaîne de caractères
   ASCII *s* utilisant l'alphabet base64 standard et renvoie les
   "bytes" décodés.

base64.urlsafe_b64encode(s)

   Encode un *objet byte-compatible* *s* en utilisant un alphabet sûr
   pour les URL et systèmes de fichiers qui substitue "-" et "_" à "+"
   et "/" dans l'alphabet standard base64 et renvoie les "bytes"
   encodés.

base64.urlsafe_b64decode(s)

   Décode un *objet octet-compatible* ou une chaîne de caractères
   ASCII *s* utilisant un alphabet sûr pour les URL et systèmes de
   fichiers qui substitue "-" et "_" à "+" et "/" dans l'alphabet
   standard base64 et renvoie les "bytes" décodés.

base64.b32encode(s)

   Encode un *objet byte-compatible* *s* en utilisant l'algorithme
   base32 et renvoie les "bytes" encodés.

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

   Décode un *objet octet-compatible* ou une chaîne de caractères
   ASCII *s* encodé en base32 et renvoie les "bytes" décodés.

   L'option *casefold* est un drapeau spécifiant si l'utilisation d'un
   alphabet en minuscules est acceptable comme entrée. Pour des
   raisons de sécurité, cette option est à "False" par défaut.

   **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.

   Une exception "binascii.Error" est levée si *s* n'est pas remplie à
   une longueur attendue ou si elle contient des caractères hors de
   l'alphabet.

base64.b32hexencode(s)

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

   Ajouté dans la version 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.

   Ajouté dans la version 3.10.

base64.b16encode(s)

   Encode un *objet byte-compatible* *s* en utilisant l'algorithme
   base16 et renvoie les "bytes" encodés.

base64.b16decode(s, casefold=False)

   Décode un *objet octet-compatible* ou une chaîne de caractères
   ASCII *s* encodé en base16 et renvoie les "bytes" décodés.

   L'option *casefold* est un drapeau spécifiant si l'utilisation d'un
   alphabet en minuscules est acceptable comme entrée. Pour des
   raisons de sécurité, cette option est à "False" par défaut.

   Une exception "binascii.Error" est levée si *s* n'est pas remplie à
   une longueur attendue ou si elle contient des caractères hors de
   l'alphabet.

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

   Encode un *objet byte-compatible* *s* en utilisant l'algorithme
   Ascii85 et renvoie les "bytes" encodés.

   L'option *foldspaces* permet d'utiliser la séquence spéciale 'y' à
   la place de quatre espaces consécutives (ASCII "0x20") comme  pris
   en charge par *btoa*. Cette fonctionnalité n'est pas gérée par
   l'encodage « standard » Ascii85.

   *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, excluding the trailing
   newline.

   *pad* spécifie l'ajout de caractères de remplissage (*padding* en
   anglais) à l'entrée jusqu'à ce que sa longueur soit un multiple de
   4 avant encodage. Notez que l'implémentation "btoa" effectue
   systématiquement ce remplissage.

   *adobe* contrôle si oui ou non la séquence encodée d'octets est
   encadrée par "<~" et "~>" comme utilisé dans l'implémentation
   Adobe.

   Ajouté dans la version 3.4.

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

   Décode un *objet octet-compatible* ou une chaîne de caractères
   ASCII *s* encodé en Ascii85 et renvoie les "bytes" décodés.

   L'option *foldspaces* permet d'utiliser la séquence spéciale 'y' à
   la place de quatre espaces consécutives (ASCII "0x20") comme  pris
   en charge par *btoa*. Cette fonctionnalité n'est pas gérée par
   l'encodage « standard » Ascii85.

   *adobe* indique si la séquence d'entrée utilise le format Adobe
   Ascii85 (c'est-à-dire utilise l'encadrement par "<~" et "~>").

   *ignorechars* doit être un *bytes-like object* ou une chaîne ASCII
   contenant des caractères à ignorer dans l'entrée. Il ne doit
   contenir que des caractères d'espacement et contient par défaut
   l'ensemble des caractères d'espacement de l'alphabet ASCII.

   Ajouté dans la version 3.4.

base64.b85encode(b, pad=False)

   Encode un *objet byte-compatible* *s* en utilisant l'algorithme
   base85 (tel qu'utilisé par exemple par le programme *git-diff* sur
   des données binaires) et renvoie les "bytes" encodés.

   Si *pad* est vrai, des caractères de remplissage "b'\0'" (*padding*
   en anglais) sont ajoutés à l'entrée jusqu'à ce que sa longueur soit
   un multiple de 4 octets avant encodage.

   Ajouté dans la version 3.4.

base64.b85decode(b)

   Décode un *objet octet-compatible* ou une chaîne de caractères
   ASCII *b* encodé en base85 et renvoie les "bytes" décodés. Les
   caractères de remplissage sont implicitement retirés si nécessaire.

   Ajouté dans la version 3.4.

L'interface historique :

base64.decode(input, output)

   Décode le contenu d'un fichier binaire *input* et écrit les données
   binaires résultantes dans le fichier *output*. *input* et *output*
   doivent être des *objets fichiers*. *input* est lu jusqu'à ce que
   "input.readline()" renvoie un objet *bytes* vide.

base64.decodebytes(s)

   Décode un *objet octet-compatible* *s* devant contenir une ou
   plusieurs lignes de données encodées en base64 et renvoie les
   "bytes" décodés.

   Ajouté dans la version 3.1.

base64.encode(input, output)

   Encode le contenu du fichier binaire *input* et écrit les données
   encodées en base64 résultantes dans le fichier *output. *input* et
   *output* doivent être des *objets fichiers*. *input* est lu jusqu'à
   ce que "input.readline()" renvoie un objet *bytes* vide. "encode()"
   insère un caractère de saut de ligne ("b'\n'") tous les 76 octets
   de sortie et assure que celle-ci se termine par une nouvelle ligne,
   comme spécifié par la **RFC 2045** (MIME).

base64.encodebytes(s)

   Encode un *objet octet-compatible* *s* pouvant contenir des données
   binaires arbitraires et renvoie les "bytes" contenant les données
   encodées en base64. Un caractère de saut de ligne ("b'\n'") est
   inséré tous les 76 octets de sortie et celle-ci se termine par une
   nouvelle ligne, comme spécifié par la **RFC 2045** (MIME).

   Ajouté dans la version 3.1.

Un exemple d'utilisation du module :

>>> 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
=======================

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.

Voir aussi:

  Module "binascii"
     Module secondaire contenant les conversions ASCII vers binaire et
     binaire vers ASCII.

  **RFC 1521** — MIME (*Multipurpose Internet Mail Extensions*) *Part
  One: Mechanisms for Specifying and Describing the Format of Internet
  Message Bodies*
     La Section 5.2, "*Base64 Content-Transfer-Encoding*", donne la
     définition de l'encodage base64.
