13.1. "zlib" — Compression compatible avec **gzip**
***************************************************

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

Pour des applications nécessitant de compresser des données, les
fonctions de ce module permettent la compression et la décompression
via la bibliothèque *zlib*. La bibliothèque *zlib* a sa propre page
web sur http://www.zlib.net. Il existe des incompatibilités connues
entre le module Python et les versions de la bibliothèque *zlib* plus
anciennes que la 1.1.3 ; 1.1.3 contient des failles de sécurité et
nous recommandons d'utiliser plutôt la version 1.14 ou plus récente.

Les fonctions *zlib* recèlent de nombreuses options et il est
nécessaire de suivre un ordre précis. Cette documentation n'a pas pour
but de couvrir la globalité des possibilités. Aussi, veuillez
consulter le manuel *zlib* en ligne sur
http://www.zlib.net/manual.html pour compléter davantage son
utilisation.

Pour lire ou écrire des fichiers ".gz" veuillez consulter le module
"gzip".

Les exceptions et fonctions disponibles dans ce module sont :

exception zlib.error

   Exception levée lors d'erreurs de compression et de décompression.

zlib.adler32(data[, value])

   Calcule une somme de contrôle Adler-32 de *data* (une somme de
   contrôle Adler-32 est aussi fiable qu'un CRC32 mais peut être
   calculée bien plus rapidement). Le résultat produit est un entier
   non signé de 32-bit. Si *value* est défini, il devient la valeur
   initiale de la somme de contrôle ; sinon une valeur par défaut de 1
   est utilisée. Définir *value* permet de calculer une somme de
   contrôle continue pendant la concaténation de plusieurs entrées.
   Cet algorithme n'a aucune garantie cryptographique puissante, et ne
   doit pas être utilisé ni pour l'authentification, ni pour des
   signatures numériques. Conçu comme un algorithme de somme de
   contrôle, il n'est pas adapté pour une utilisation sous forme de
   clé de hachage générique.

   Modifié dans la version 3.0: Renvoie une valeur non-signée. Pour
   produire la même valeur avec toutes les versions de Python sur
   différentes plateformes, utilisez "adler32(data) & 0xffffffff".

zlib.compress(data, level=-1)

   Compresse les octets contenus dans *data*, renvoie un objet *bytes*
   contenant les données compressées. *level* permet d'ajuster le
   niveau de compression, ce doit être un nombre entier compris entre
   "0" et "9" ou "-1" ; "1" étant plus rapide et procède à une
   compression légère, "9" est plus lent mais compresse plus
   fortement. "0" n'effectue aucune compression. La valeur par défaut
   est "-1" (*Z_DEFAULT_COMPRESSION*). *Z_DEFAULT_COMPRESSION* donne
   une valeur par défaut proposant un équilibre entre vitesse et taux
   de compression (actuellement équivalente à 6). Si une erreur
   surgit, l'exception "error" est levée.

   Modifié dans la version 3.6: *level* peut maintenant être passé par
   son nom.

zlib.compressobj(level=-1, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

   Renvoie un objet "compresseur", à utiliser pour compresser des flux
   de données qui ne peuvent pas être stockés entièrement en mémoire.

   *level* est le taux de compression -- un entier compris entre "0"
   et "9" ou "-1". La valeur "1" est la plus rapide avec taux de
   compression minimal, tandis que la valeur "9" est la plus lente
   mais produit une compression maximale. "0" ne produit aucune
   compression. La valeur par défaut est "-1"
   (*Z_DEFAULT_COMPRESSION*). La constante *Z_DEFAULT_COMPRESSION*
   équivaut à un bon compromis par défaut entre rapidité et bonne
   compression (valeur équivalente au niveau 6).

   *method* définit l'algorithme de compression. Pour le moment, la
   seule valeur acceptée est "DEFLATED".

   L'argument *wbits* contrôle la taille du tampon d'historique
   ("*window size*") utilisé lors de la compression, et si un en-tête
   et un bloc final seront inclus. Il accepte plusieurs intervalles de
   valeurs, et vaut "15" (MAX_WBITS) par défaut :

   * De +9 à +15 : le logarithme binaire de la taille du tampon, par
     conséquent compris entre 512 et 32 768. Des valeurs plus grandes
     produisent de meilleures compressions aux dépens d'une
     utilisation mémoire plus grande. Le résultat final inclus des en-
     têtes et des blocs spécifiques à *zlib*.

   * De "-9" à "-15" : utilise la valeur absolue de *wbits* comme
     logarithme binaire de la taille du tampon, et ne produit pas
     d'entêtes ni de bloc final.

   * De +25 à +31 = 16 + (9 à 15) : utilise les 4 bits de poids faible
     comme logarithme binaire de la taille du tampon, tout en incluant
     un entête **gzip** et une somme de contrôle finale.

   L'argument *memLevel* permet d'ajuster la quantité de mémoire
   utilisée pour stocker l'état interne de la compression. Les valeurs
   valides sont comprises entre "1" et "9". Des valeurs plus élevées
   occupent davantage de mémoire, mais sont plus rapides et produisent
   des sorties plus compressées.

   *strategy* permet d'ajuster l'algorithme de compression. Les
   valeurs possibles sont "Z_DEFAULT_STRATEGY", "Z_FILTERED", et
   "Z_HUFFMAN_ONLY", "Z_RLE" (*zlib* 1.2.0.1) et "Z_FIXED" (*zlib*
   1.2.2.2).

   *zdict* est un dictionnaire de compression prédéfini. C'est une
   séquence d'octets (tel qu'un objet "bytes") contenant des sous-
   séquences attendues régulièrement dans les données à compresser.
   Les sous-séquences les plus fréquentes sont à placer à la fin du
   dictionnaire.

   Modifié dans la version 3.3: Ajout du paramètre *zdict*.

zlib.crc32(data[, value])

   Calcule la somme de contrôle CRC (*Cyclic Redundancy Check* en
   anglais) de l'argument *data*. Il renvoie un entier non signé de 32
   bits. Si l'argument *value* est présent, il permet de définir la
   valeur de départ de la somme de contrôle. Sinon, la valeur par
   défaut est 0. L'argument *value* permet de calculer la somme de
   contrôle glissante d'une concaténation de données. L'algorithme
   n'est pas fort d'un point de vue cryptographique, et ne doit pas
   être utilisé pour l'authentification ou des signatures numériques.
   Cet algorithme a été conçu pour être exploité comme un algorithme
   de somme de contrôle, ce n'est pas un algorithme de hachage
   générique.

   Modifié dans la version 3.0: Renvoie une valeur non-signée. Pour
   obtenir la même valeur sur n'importe quelle version de Python et
   n'importe quelle plateforme, utilisez "crc32(data) & 0xffffffff".

zlib.decompress(data, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

   Décompresse les octets de *data*, renvoyant un objet *bytes*
   contenant les données décompressées. Le paramètre *wbits* dépend du
   format des données compressées, et est abordé plus loin. Si
   l'argument *bufsize* est défini, il est utilisé comme taille
   initiale du tampon de sortie. En cas d'erreur, l'exception "error"
   est levée.

   L'argument *wbits* contrôle la taille du tampon d'historique
   ("*window size*") utilisé lors de la compression, et si un en-tête
   et un bloc final sont attendus. Similaire au paramètre de
   "compressobj()", mais accepte une gamme plus large de valeurs :

   * De +8 à +15 : logarithme binaire pour la taille du tampon.
     L'entrée doit contenir un en-tête et un bloc *zlib*.

   * 0 : détermine automatiquement la taille du tampon à partir de l
     'en-tête *zlib*. Géré uniquement depuis *zlib* 1.2.3.5.

   * De "-8" à "-15" : utilise la valeur absolue de *wbits* comme
     logarithme binaire pour la taille du tampon. L'entrée doit être
     un flux brut, sans en-tête ni bloc final.

   * De +24 à +31 = 16 + (8 à 15) : utilise les 4 de poids faible
     comme logarithme binaire pour la taille du tampon. L'entrée doit
     contenir un en-tête *gzip* et son bloc final.

   * De +40 à +47 = 32 + (8 à 15) : utilise les 4 bits de poids faible
     comme logarithme binaire pour la taille du tampon, et accepte
     automatiquement les formats *zlib* ou *gzip*.

   Lors de la décompression d'un flux, la taille du tampon ne doit pas
   être inférieure à la taille initialement utilisée pour compresser
   le flux. L'utilisation d'une valeur trop petite peut déclencher une
   exception "error". La valeur par défaut *wbits* correspond à une
   taille élevée du tampon et nécessite d'y adjoindre un en-tête
   *zlib* et son bloc final.

   L'argument *bufsize* correspond à la taille initiale du tampon
   utilisé pour contenir les données décompressées. Si plus d'espace
   est nécessaire, la taille du tampon sera augmentée au besoin, donc
   vous n'avez pas besoin de deviner la valeur exacte. Un réglage
   précis n'économisera que quelques appels à "malloc()".

   Modifié dans la version 3.6: *wbits* et *bufsize* peuvent être
   utilisés comme arguments nommés.

zlib.decompressobj(wbits=MAX_WBITS[, zdict])

   Renvoie un objet "décompresseur", à utiliser pour décompresser des
   flux de données qui ne rentrent pas entièrement en mémoire.

   Le paramètre *wbits* contrôle la taille du tampon, et détermine
   quel format d'en-tête et de bloc sont prévus. Il a la même
   signification que décrit pour decompress().

   Le paramètre *zdict* définit un dictionnaire de compression
   prédéfini. S'il est fourni, il doit être identique au dictionnaire
   utilisé par le compresseur, à l'origine des données à décompresser.

   Note:

     Si *zdict* est un objet modifiable (tel qu'un "bytearray", par
     exemple), vous ne devez pas modifier son contenu entre l'appel à
     la fonction "decompressobj()" et le premier appel à la méthode
     "decompress()" du décompresseur.

   Modifié dans la version 3.3: Ajout du paramètre *zdict*.

Les objets de compression gèrent les méthodes suivantes :

Compress.compress(data)

   Compresse *data* et renvoie au moins une partie des données
   compressées sous forme d'objet *bytes*. Ces données doivent être
   concaténées à la suite des appels précédant à "compress()".
   Certaines entrées peuvent être conservées dans des tampons internes
   pour un traitement ultérieur.

Compress.flush([mode])

   Toutes les entrées mises en attente sont traitées et un objet
   *bytes* contenant la sortie des données compressées restantes est
   renvoyé. L'argument *mode* accepte l'une des constantes suivantes :
   "Z_NO_FLUSH", "Z_PARTIAL_FLUSH", "Z_SYNC_FLUSH", "Z_FULL_FLUSH",
   "Z_BLOCK" (*zlib* 1.2.3.4), et "Z_FINISH", par défaut "Z_FINISH".
   Sauf "Z_FINISH", toutes les constantes permettent de compresser
   d'autres chaînes d'octets, tandis que "Z_FINISH" finalise le flux
   compressé et bloque toute autre tentative de compression. Suite à
   l'appel de la méthode "flush()" avec l'argument *mode* défini à
   "Z_FINISH", la méthode "compress()" ne peut plus être rappelée. Il
   ne reste plus qu'à supprimer l'objet.

Compress.copy()

   Renvoie une copie de l'objet "compresseur". Utile pour compresser
   efficacement un ensemble de données qui partagent un préfixe
   initial commun.

Les objets décompresseurs prennent en charge les méthodes et attributs
suivants :

Decompress.unused_data

   Un objet *bytes* contenant tous les octets restants après les
   données compressées. Il vaut donc "b""" tant que des données
   compressées sont disponibles. Si toute la chaîne d'octets ne
   contient que des données compressées, il vaut toujours "b""", un
   objet *bytes* vide.

Decompress.unconsumed_tail

   Un objet *bytes* contenant toutes les données non-traitées par le
   dernier appel à la méthode "decompress()", à cause d'un dépassement
   de la limite du tampon de données décompressées. Ces données n'ont
   pas encore été traitées par la bibliothèque *zlib*, vous devez donc
   les envoyer (potentiellement en y concaténant encore des données)
   par un appel à la méthode "decompress()" pour obtenir une sortie
   correcte.

Decompress.eof

   Booléen qui signale si la fin du flux compressé est atteint.

   Ceci rend possible la distinction entre un flux correctement
   compressé et un flux incomplet.

   Nouveau dans la version 3.3.

Decompress.decompress(data, max_length=0)

   Décompresse *data*, renvoie un objet *bytes*, contenant au moins
   une partie des données décompressées. Ce résultat doit être
   concaténé aux résultats des appels précédents à "decompress()". Des
   données d'entrée peuvent être conservées dans les tampons internes
   pour un traitement ultérieur.

   Si le paramètre optionnel *max_length* est différent de zéro alors
   la valeur renvoyée n'est pas plus grande que *max_length*. Cela
   peut amener à une décompression partielle. Les données non-encore
   décompressées sont stockées dans l'attribut "unconsumed_tail".
   Cette chaîne d'octets doit être transmise à un appel ultérieur à
   "decompress()". Si *max_length* vaut zéro, la totalité de l'entrée
   est décompressée, et l'attribut "unconsumed_tail" reste vide.

   Modifié dans la version 3.6: *max_length* peut être utilisé comme
   un argument nommé.

Decompress.flush([length])

   Toutes les entrées en attente sont traitées, et un objet *bytes*
   est renvoyé, contenant le reste des données à décompresser. Après
   l'appel à "flush()", la méthode "decompress()" ne peut pas être
   rappelée. Il ne reste qu'à détruire l'objet.

   Le paramètre optionnel *length* définit la taille initiale du
   tampon de sortie.

Decompress.copy()

   Renvoie une copie du décompresseur. Vous pouvez l'utiliser pour
   sauvegarder l'état de la décompression en cours, afin de pouvoir
   revenir rapidement à cet endroit plus tard.

Des informations relatives à la version de la bibliothèque *zlib*
utilisée sont disponibles via les constantes suivantes :

zlib.ZLIB_VERSION

   Version de la bibliothèque *zlib* utilisée lors de la compilation
   du module. Elle peut être différente de la bibliothèque *zlib*
   actuellement utilisée par le système, qui est consultable par
   "ZLIB_RUNTIME_VERSION".

zlib.ZLIB_RUNTIME_VERSION

   Chaîne contenant la version de la bibliothèque *zlib* actuellement
   utilisée par l'interpréteur.

   Nouveau dans la version 3.3.

Voir aussi:

  Module "gzip"
     Lire et écrire des fichiers au format **gzip**.

  http://www.zlib.net
     Page officielle de la bibliothèque *zlib*.

  http://www.zlib.net/manual.html
     La documentation de *zlib* explique le sens et l'utilisation des
     nombreuses fonctions fournies par la bibliothèque.
