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.