19.8. "binascii" --- Conversion entre binaire et ASCII
******************************************************

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

Le module "binascii" contient des méthodes pour convertir entre
binaire et diverses représentations binaires encodées en ASCII.
Normalement, vous n’allez pas utiliser ces fonctions directement mais
vous utiliserez des modules d’encapsulage comme "uu", "base64", or
"binhex" à la place. Le module "binascii" contient des fonctions bas-
niveau écrites en C plus rapides qui sont utilisées par des modules
haut-niveau.

Note:

  La fonction "a2b_*" accepte des chaînes de caractères contenant
  seulement des caractères ASCII. D’autres fonctions acceptent
  seulement des objets *bytes et similaire* (tel que "bytes",
  "bytearray" et autres objets qui supportent le protocole tampon).

  Modifié dans la version 3.3: Les chaines de caractères *unicode*
  seulement composées de caractères ASCII sont désormais acceptées par
  les fonctions "a2b_*".

Le module "binascii" définit les fonctions suivantes :

binascii.a2b_uu(string)

   Convertit une seule ligne de donnée *uuencoded* en binaire et
   renvoie la donnée binaire. Les lignes contiennent normalement 45
   octets (binaire), sauf pour la dernière ligne. Il se peut que la
   ligne de donnée soit suivie d’un espace blanc.

binascii.b2a_uu(data)

   Convert binary data to a line of ASCII characters, the return value
   is the converted line, including a newline char. The length of
   *data* should be at most 45.

binascii.a2b_base64(string)

   Convertit un bloc de donnée en *base64* en binaire et renvoie la
   donnée binaire. Plus d’une ligne peut être passé à la fois.

binascii.b2a_base64(data, *, newline=True)

   Convertit les données binaires en une ligne de caractères ASCII en
   codage base 64. La valeur de renvoyée et la ligne convertie,
   incluant un caractère de nouvelle ligne si *newline* est vraie. La
   sortie de cette fonction se conforme à **RFC 3548**.

   Modifié dans la version 3.6: Ajout du paramètre *newline*.

binascii.a2b_qp(data, header=False)

   Convertit un bloc de données *quoted-printable* en binaire et
   renvoie les données binaires. Plus d’une ligne peut être passée à
   la fois. Si l’argument optionnel *header* est présent et vrai, les
   traits soulignés seront décodés en espaces.

binascii.b2a_qp(data, quotetabs=False, istext=True, header=False)

   Convertit les données binaires en ligne(s) de caractères ASCII en
   codage imprimable entre guillemets. La valeur de retour est lales
   lignes(s) convertie(s). Si l’argument optionnel *quotetabs* est
   présent et vrai, toutes les tabulations et espaces seront encodés.
   Si l’argument optionnel *istext* est présent et faux, les nouvelles
   lignes ne sont pas encodées mais les espaces de fin de ligne le
   seront. Si l’argument optionnel *header* est présent et vrai, les
   espaces vont être encodés comme de traits soulignés selon **RFC
   1522**. Si l’argument optionnel *header* est présent et faux, les
   caractères de nouvelle ligne seront également encodés ; sinon la
   conversion de saut de ligne pourrait corrompre le flux de données
   binaire.

binascii.a2b_hqx(string)

   Convertit un bloc de donnée ASCII au format *binhex4* en binaire,
   sans faire de décompression RLE. La chaîne de caractères doit
   contenir un nombre complet d’octet binaires ou (au cas où la
   dernière portion de donnée est au format *binhex4*) avoir les bits
   restants à 0.

binascii.rledecode_hqx(data)

   Réalise une décompression RLE sur la donnée, d’après la norme
   *binhex4*. L’algorithme utilise "0x90" après un octet comme un
   indicateur de répétition, suivi d’un décompte. Un décompte de "0"
   définit une valeur d’octet de "0x90". La routine renvoie la donnée
   décompressée, sauf si la donnée entrante se finit sur un indicateur
   de répétition orphelin. Dans ce cas l’exception "Incomplete" est
   levée.

   Modifié dans la version 3.2: Accepte seulement des objets
   *bytestring* ou *bytearray* en entrée.

binascii.rlecode_hqx(data)

   Réalise une compression RLE de type *binhex4* sur *data* et renvoie
   le résultat.

binascii.b2a_hqx(data)

   Réalise une traduction *hexbin4* de binaire à ASCII et renvoie la
   chaîne de caractères résultante. L’argument doit être *RLE-coded*,
   et avoir une longueur divisible par 3 (sauf, éventuellement, le
   dernier fragment).

binascii.crc_hqx(data, value)

   Calcule une valeur en CRC 16-bit de *data*, commençant par *value*
   comme CRC initial et renvoie le résultat. Ceci utilise le CRC-CCITT
   polynomial *x*^16 + *x*^12 + *x*^5 + 1, souvent représenté comme
   *0x1021*. Ce CRC est utilisé dans le format *binhex4*.

binascii.crc32(data[, value])

   Calcule CRC-32, la somme de contrôle 32-bit de *data*, commençant
   par un CRC initial de *value*. Le CRC initial par défaut est zéro.
   L’algorithme est cohérent avec la somme de contrôle du fichier ZIP.
   Comme l’algorithme est conçu pour être utilisé comme un algorithme
   de somme de contrôle, il ne convient pas comme algorithme de
   hachage général. Utiliser comme suit :

      print(binascii.crc32(b"hello world"))
      # Or, in two pieces:
      crc = binascii.crc32(b"hello")
      crc = binascii.crc32(b" world", crc)
      print('crc32 = {:#010x}'.format(crc))

   Modifié dans la version 3.0: Le résultat est toujours non signé.
   Pour générer la même valeur numérique sur toutes les versions de
   Python et plateformes, utilisez "crc32(data) & 0xffffffff".

binascii.b2a_hex(data)
binascii.hexlify(data)

   Renvoie la représentation hexadécimale du binaire *data*. Chaque
   octet de *data* est converti en la représentation 2 chiffres
   correspondante. L’objet octets renvoyé est donc deux fois plus long
   que la longueur de *data*.

binascii.a2b_hex(hexstr)
binascii.unhexlify(hexstr)

   Renvoie la donnée binaire représentée par la chaîne de caractères
   hexadécimale *hexstr*. Cette fonction est l’inverse de "b2a_hex()".
   *hexstr* doit contenir un nombre pair de chiffres hexadécimaux (qui
   peuvent être en majuscule ou minuscule), sinon une exception
   "Error" est levée.

exception binascii.Error

   Exception levée en cas d'erreurs. Ce sont typiquement des erreurs
   de programmation.

exception binascii.Incomplete

   Exception levée par des données incomplète. Il ne s’agit
   généralement pas d’erreurs de programmation, mais elles peuvent
   être traitées en lisant un peu plus de données et en réessayant.

Voir aussi:

  Module "base64"
     Support de l’encodage *base64-style* conforme RFC en base 16, 32,
     64 et 85.

  Module "binhex"
     Support pour le format *binhex* utilisé sur Macintosh.

  Module "uu"
     Gestion de l'encodage UU utilisé sur Unix.

  Module "quopri"
     Support de l’encodage *quote-printable* utilisé par les messages
     *email* MIME.
