19.6. "base64" — Encodages base16, base32, base64 et base85
***********************************************************

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

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

Ce module fournit des fonctions permettant de coder des données
binaires en caractères ASCII affichables ainsi que de décoder ces
caractères vers des données binaires en retour. Il fournit des
fonctions d'encodage et de décodage pour les codages spécifiés par la
**RFC 3548** qui définit les algorithmes base16, base32 et base64,
ainsi que les encodages standards *de facto* Ascii85 et base85.

Les encodages définis par la **RFC 3548** sont adaptés au codage des
données binaires pour leur transfert par courriel, comme éléments
d'une URL ou d'une requête HTTP POST. L'algorithme d'encodage ne doit
pas être confondu avec le programme **uuencode**.

Ce module présente deux interfaces. L'interface moderne gère
l'encodage d'*objets octet-compatibles* en "bytes" ASCII ainsi que le
décodage d'*objets octet-compatibles* ou de chaînes de caractères
contenant de l'ASCII en "bytes". Les deux alphabets de l'algorithme
base64 définis par la **RFC 3548** (normal et sûr pour les systèmes de
fichiers ou URL) sont gérés.

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.

   L'option *altchars* doit être un *bytes-like object* de longueur au
   moins 2 (les caractères additionnels sont ignorés) qui spécifie un
   alphabet alternatif pour les délimiteurs "+" et "/". Cela permet de
   générer des chaînes de caractères base64 pouvant être utilisées
   pour une URL ou dans un système de fichiers. La valeur par défaut
   est "None", auquel cas l'alphabet standard base64 est utilisé.

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.

   L'option *altchars* doit être un *bytes-like object* de longueur au
   moins égale à 2 (les caractères additionnels sont ignorés) qui
   spécifie un alphabet alternatif pour les délimiteurs "+" et "/".

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

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.

   La **RFC 3548** autorise une correspondance optionnelle du chiffre
   0 (zéro) vers la lettre O (/o/) ainsi que du chiffre 1 (un) vers
   soit la lettre I (/i/) ou la lettre L (/l/). L'argument optionnel
   *map01*, lorsqu'il diffère de "None", spécifie en quelle lettre le
   chiffre 1 doit être transformé (lorsque *map01* n'est pas "None",
   le chiffre 0 est toujours transformé en la lettre O). Pour des
   raisons de sécurité, le défaut est "None", de telle sorte que 0 et
   1 ne sont pas autorisés dans l'entrée.

   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.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* contrôle l'ajout de caractères de saut de ligne ("b'\n'")
   à la sortie. Chaque ligne de sortie contient au maximum *wrapcol*
   caractères si cette option diffère de zéro.

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

   Nouveau dans la version 3.4.

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

   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.

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

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

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

   Nouveau dans la version 3.1.

base64.decodestring(s)

   Alias obsolète de "decodebytes()".

   Obsolète depuis 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).

   Nouveau dans la version 3.1.

base64.encodestring(s)

   Alias obsolète de "encodebytes()".

   Obsolète depuis 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'

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.
