"zlib" --- Compression compatible with **gzip**
***********************************************

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

For applications that require data compression, the functions in this
module allow compression and decompression, using the zlib library.

This is an *optional module*. If it is missing from your copy of
CPython, look for documentation from your distributor (that is,
whoever provided Python to you). If you are the distributor, see
Requirements for optional modules.

zlib's functions have many options and often need to be used in a
particular order.  This documentation doesn't attempt to cover all of
the permutations; consult the zlib manual for authoritative
information.

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.

zlib.compress(data, /, level=Z_DEFAULT_COMPRESSION, wbits=MAX_WBITS)

   Compresses the bytes in *data*, returning a bytes object containing
   compressed data. *level* is an integer from "0" to "9" or "-1"
   controlling the level of compression; See "Z_BEST_SPEED" ("1"),
   "Z_BEST_COMPRESSION" ("9"), "Z_NO_COMPRESSION" ("0"), and the
   default, "Z_DEFAULT_COMPRESSION" ("-1") for more information about
   these values.

   The *wbits* argument controls the size of the history buffer (or
   the "window size") used when compressing data, and whether a header
   and trailer is included in the output.  It can take several ranges
   of values, defaulting to "15" ("MAX_WBITS"):

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

   Raises the "error" exception if any error occurs.

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

   Modifié dans la version 3.11: The *wbits* parameter is now
   available to set window bits and compression type.

zlib.compressobj(level=Z_DEFAULT_COMPRESSION, 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* is the compression level -- an integer from "0" to "9" or
   "-1". See "Z_BEST_SPEED" ("1"), "Z_BEST_COMPRESSION" ("9"),
   "Z_NO_COMPRESSION" ("0"), and the default, "Z_DEFAULT_COMPRESSION"
   ("-1") for more information about these values.

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

   The *wbits* parameter controls the size of the history buffer (or
   the "window size"), and what header and trailer format will be
   used. It has the same meaning as described for compress().

   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* is used to tune the compression algorithm. Possible
   values are "Z_DEFAULT_STRATEGY", "Z_FILTERED", "Z_HUFFMAN_ONLY",
   "Z_RLE" and "Z_FIXED".

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

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])

   All pending input is processed, and a bytes object containing the
   remaining compressed output is returned.  *mode* can be selected
   from the constants "Z_NO_FLUSH", "Z_PARTIAL_FLUSH", "Z_SYNC_FLUSH",
   "Z_FULL_FLUSH", "Z_BLOCK", or "Z_FINISH", defaulting to "Z_FINISH".
   Except "Z_FINISH", all constants allow compressing further
   bytestrings of data, while "Z_FINISH" finishes the compressed
   stream and prevents compressing any more data.  After calling
   "flush()" with *mode* set to "Z_FINISH", the "compress()" method
   cannot be called again; the only realistic action is to delete the
   object.

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.

Modifié dans la version 3.8: Les objets compresseurs gère maintenant
"copy.copy()" et "copy.deepcopy()".

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.

   This makes it possible to distinguish between a properly formed
   compressed stream, and an incomplete or truncated one.

   Ajouté 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.

Modifié dans la version 3.8: Ajout de "copy.copy()" et de
"copy.deepcopy()" au support de décompression d'objets.

The following constants are available to configure compression and
decompression behavior:

zlib.DEFLATED

   The deflate compression method.

zlib.MAX_WBITS

   The maximum window size, expressed as a power of 2. For example, if
   "MAX_WBITS" is "15" it results in a window size of "32 KiB".

zlib.DEF_MEM_LEVEL

   The default memory level for compression objects.

zlib.DEF_BUF_SIZE

   The default buffer size for decompression operations.

zlib.Z_NO_COMPRESSION

   Compression level "0"; no compression.

   Ajouté dans la version 3.6.

zlib.Z_BEST_SPEED

   Compression level "1"; fastest and produces the least compression.

zlib.Z_BEST_COMPRESSION

   Compression level "9"; slowest and produces the most compression.

zlib.Z_DEFAULT_COMPRESSION

   Default compression level ("-1"); a compromise between speed and
   compression. Currently equivalent to compression level "6".

zlib.Z_DEFAULT_STRATEGY

   Default compression strategy, for normal data.

zlib.Z_FILTERED

   Compression strategy for data produced by a filter (or predictor).

zlib.Z_HUFFMAN_ONLY

   Compression strategy that forces Huffman coding only.

zlib.Z_RLE

   Compression strategy that limits match distances to one (run-length
   encoding).

   This constant is only available if Python was compiled with zlib
   1.2.0.1 or greater.

   Ajouté dans la version 3.6.

zlib.Z_FIXED

   Compression strategy that prevents the use of dynamic Huffman
   codes.

   This constant is only available if Python was compiled with zlib
   1.2.2.2 or greater.

   Ajouté dans la version 3.6.

zlib.Z_NO_FLUSH

   Flush mode "0". No special flushing behavior.

   Ajouté dans la version 3.6.

zlib.Z_PARTIAL_FLUSH

   Flush mode "1". Flush as much output as possible.

zlib.Z_SYNC_FLUSH

   Flush mode "2". All output is flushed and the output is aligned to
   a byte boundary.

zlib.Z_FULL_FLUSH

   Flush mode "3". All output is flushed and the compression state is
   reset.

zlib.Z_FINISH

   Flush mode "4". All pending input is processed, no more input is
   expected.

zlib.Z_BLOCK

   Flush mode "5". A deflate block is completed and emitted.

   This constant is only available if Python was compiled with zlib
   1.2.2.2 or greater.

   Ajouté dans la version 3.6.

zlib.Z_TREES

   Flush mode "6", for inflate operations. Instructs inflate to return
   when it gets to the next deflate block boundary.

   This constant is only available if Python was compiled with zlib
   1.2.3.4 or greater.

   Ajouté dans la version 3.6.

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.

   Ajouté dans la version 3.3.

zlib.ZLIBNG_VERSION

   The version string of the zlib-ng library that was used for
   building the module if zlib-ng was used. When present, the
   "ZLIB_VERSION" and "ZLIB_RUNTIME_VERSION" constants reflect the
   version of the zlib API provided by zlib-ng.

   If zlib-ng was not used to build the module, this constant will be
   absent.

   Ajouté dans la version 3.14.

Voir aussi:

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

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

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

  In case gzip (de)compression is a bottleneck, the python-isal
  package speeds up (de)compression with a mostly compatible API.
