"gzip" — Support pour les fichiers **gzip**
*******************************************

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

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

Ce module fournit une interface simple pour compresser et décompresser
des fichiers tout comme le font les programmes GNU **gzip** et
**gunzip**.

La compression de données est fournie par le module "zlib".

Le module "gzip" fournit la classe "GzipFile" ainsi que les fonctions
pratiques "open()", "compress()" et "decompress()". La classe
"GzipFile" lit et écrit des fichiers au format **gzip**, compressant
et décompressant automatiquement les données pour qu'elles aient
l'apparence d'un objet *file object* ordinaire.

Notez que les formats de fichier supplémentaires qui peuvent être
décompressés par les programmes **gzip** et **gunzip**, comme ceux
produits par le programmes **compress** et **pack**, ne sont pas gérés
par ce module.

Le module définit les éléments suivants :

gzip.open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)

   Ouvre un fichier compressé en *gzip* en mode binaire ou texte,
   renvoie un objet *file object*.

   L'argument *filename* peut être un nom de fichier (un objet "str"
   ou "bytes") ou un objet fichier existant que l'on peut lire, ou où
   l'on peut écrire.

   L'argument *mode* peut-être "'r'", "'rb'", "'a'", "'ab'", "'w'",
   "'wb'", "'x'" ou "'xb'" pour le mode binaire ou "'rt'", "'at'",
   "'wt'", ou "'xt'" pour le mode texte. Le mode par défaut est
   "'rb'".

   L'argument *compresslevel* est un entier de 0 à 9, comme pour le
   constructeur de la classe "GzipFile".

   En mode binaire, cette fonction est équivalente au constructeur de
   la classe "GzipFile" : "GzipFile(filename, mode, compresslevel)".
   Dans ce cas, les arguments *encoding*, *errors* et *newline* ne
   doivent pas être fournis.

   En mode texte, un objet "GzipFile" est créé et empaqueté dans une
   instance de "io.TextIOWrapper" avec l'encodage, la gestion d'erreur
   et les fins de ligne spécifiés.

   Modifié dans la version 3.3: Ajout de la prise en charge de
   *filename* en tant qu'objet *file*, du mode texte et des arguments
   *encoding*, *errors* et *newline*.

   Modifié dans la version 3.4: Ajout de la prise en charge des modes
   "'x'", "'xb'" et "'xt'".

   Modifié dans la version 3.6: Accepte un *path-like object*.

class gzip.GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)

   Constructeur de la classe "GzipFile" qui simule la plupart des
   méthodes d'un objet *file object* à l'exception de la méthode
   "truncate()". Au moins un des arguments *fileobj* et *filename*
   doit avoir une valeur non triviale.

   La nouvelle instance de classe est basée sur *fileobj* qui peut
   être un fichier usuel, un objet "io.BytesIO" ou tout autre objet
   qui simule un fichier. *fileobj* est par défaut à *None*, dans ce
   cas *filename* est ouvert afin de fournir un objet fichier.

   Quand *fileobj* n'est pas à "None", l'argument *filename* est
   uniquement utilisé pour être inclus dans l'entête  du fichier
   **gzip**, qui peut inclure le nom original du fichier décompressé.
   Il est par défaut défini avec le nom de fichier de *fileobj* s'il
   est discernable, sinon il est par défaut défini à une chaîne de
   caractères vide et dans ce cas le nom du fichier orignal n'est pas
   inclus dans l'entête.

   L'argument *mode* peut-être "'r'", "'rb'", "'a'", "'ab'", "'w'",
   "'wb'", "'x'", ou "'xb'", selon que le fichier va être lu ou écrit.
   Par défaut prend la valeur du mode de *fileobj* si discernable ;
   sinon, la valeur par défaut est "'rb'".

   Notez que le fichier est toujours ouvert en mode binaire. Pour
   ouvrir un fichier compressé en mode texte, utilisez la fonction
   "open()" (ou empaquetez votre classe "GzipFile" avec un
   "io.TextIOWrapper").

   L'argument *compresslevel* est un entier de "0" à "9" contrôlant le
   niveau de compression,``1`` est le plus rapide et produit la
   compression la plus faible et "9" est le plus rapide et produit la
   compression la plus élevée. "0" désactive la compression. Par
   défaut à "9".

   L'argument *mtime* est un *timestamp* numérique optionnel à écrire
   dans le champ de date de dernière modification du flux durant la
   compression.  Il ne doit être défini qu'en mode compression.  S'il
   est omis ou "None", la date courante est utilisée.  Voir l'attribut
   "mtime" pour plus de détails.

   Appeler la méthode "close()" d'un objet "GzipFile" ne ferme pas
   *fileobj*, puisque vous pourriez avoir besoin d'ajouter des
   informations après les données compressées. Cela vous permet aussi
   de passer un objet "io.BytesIO" ouvert en écriture en tant que
   *fileobj* et récupérer le tampon mémoire final en utilisant la
   méthode "getvalue()" de l'objet "io.BytesIO".

   :La classe "GzipFile" implémente l'interface  "io.BufferedIOBase",
   incluant l'itération, la déclaration "with".  La méthode
   "truncate()" est la seule non implémentée.

   La classe "GzipFile" fournit aussi la méthode et l'attribut suivant
   :

   peek(n)

      Lit *n* octets non compressés sans avancer la position dans le
      fichier. Au plus une seule lecture sur le flux compressé est
      faite pour satisfaire l'appel. Le nombre d'octets retournés peut
      être supérieur ou inférieur au nombre demandé.

      Note:

        Bien que l'appel à "peek()" ne change pas la position dans le
        fichier de l'objet "GzipFile", il peut changer la position de
        l'objet de fichier sous-jacent (par exemple, si l'instance de
        "GzipFile" a été construite avec le paramètre *fileobj*).

      Nouveau dans la version 3.2.

   mtime

      Lors de la décompression, la valeur du champ de date de dernière
      modification dans le dernier en-tête lu peut être lue à partir
      de cet attribut, comme un entier. La valeur initiale avant
      lecture d'un en-tête est "None".

      Tous les flux compressés en **gzip** doivent contenir ce champ
      *timestamp*. Certains programmes, comme **gunzip**, utilisent ce
      *timestamp*. Ce format est le même que la valeur retour de
      "time.time()" et l'attribut "st_mtime" de l'objet retourné par
      "os.stat()".

   Modifié dans la version 3.1: Ajout de la prise en charge du mot-
   clef "with", ainsi que de l'argument *mtime* du constructeur et de
   l'attribut "mtime".

   Modifié dans la version 3.2: Ajout de la prise en charge des
   fichiers non navigables ou commençant par des octets nuls.

   Modifié dans la version 3.3: La méthode "io.BufferedIOBase.read1()"
   est désormais implémentée.

   Modifié dans la version 3.4: Ajout de la prise en charge des modes
   "'x'" et "'xb'".

   Modifié dans la version 3.5: Ajout de la prise en charge de
   l'écriture d'objets *bytes-like objects* arbitraires. La méthode
   "read()" accepte désormais un argument de valeur "None".

   Modifié dans la version 3.6: Accepte un *path-like object*.

gzip.compress(data, compresslevel=9)

   Compresse les données *data*, renvoie un objet "bytes" contenant
   les données compressées. L'argument *compresslevel* a la même
   signification que dans le constructeur de la classe "GzipFile" ci-
   dessus.

   Nouveau dans la version 3.2.

gzip.decompress(data)

   Décompresse les données *data*, retourne un objet "bytes" contenant
   les données décompressées.

   Nouveau dans la version 3.2.


Exemples d'utilisation
======================

Exemple montrant comment lire un fichier compressé :

   import gzip
   with gzip.open('/home/joe/file.txt.gz', 'rb') as f:
       file_content = f.read()

Exemple montrant comment créer un fichier GZIP :

   import gzip
   content = b"Lots of content here"
   with gzip.open('/home/joe/file.txt.gz', 'wb') as f:
       f.write(content)

Exemple montrant comment compresser dans un GZIP un fichier existant :

   import gzip
   import shutil
   with open('/home/joe/file.txt', 'rb') as f_in:
       with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:
           shutil.copyfileobj(f_in, f_out)

Exemple montrant comment compresser dans un GZIP un binaire dans une
chaîne :

   import gzip
   s_in = b"Lots of content here"
   s_out = gzip.compress(s_in)

Voir aussi:

  Module "zlib"
     Le module de compression de données de base nécessaire pour gérer
     le format de fichier **gzip**.
