# `gzip` --- Support for gzip files

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.

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.

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.

exception gzip.BadGzipFile

  An exception raised for invalid gzip files. It inherits from `OSError`. `EOFError` and `zlib.error` can also be raised for invalid gzip files.

  Ajouté dans la version 3.8.

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

  Constructor for the `GzipFile` class, which simulates most of the methods of a file object, with the exception of the `truncate()` method. At least one of fileobj and filename must be given a non-trivial value.

  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.

  The mode argument can be any of `'r'`, `'rb'`, `'a'`, `'ab'`, `'w'`, `'wb'`, `'x'`, or `'xb'`, depending on whether the file will be read or written. The default is the mode of fileobj if discernible; otherwise, the default is `'rb'`. In future Python releases the mode of fileobj will not be used. It is better to always specify mode for writing.

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

  The optional mtime argument is the timestamp requested by gzip. The time is in Unix format, i.e., seconds since 00:00:00 UTC, January 1, 1970. If mtime is omitted or `None`, the current time is used. Use mtime = 0 to generate a compressed stream that does not depend on creation time.

  See below for the `mtime` attribute that is set when decompressing.

  Calling a `GzipFile` object's `close()` method does not close fileobj, since you might wish to append more material after the compressed data. This also allows you to pass an `io.BytesIO` object opened for writing as fileobj, and retrieve the resulting memory buffer using the `io.BytesIO` object's `getvalue()` method.

  `GzipFile` supports the `io.BufferedIOBase` interface, including iteration and the `with` statement. Only the `truncate()` method isn't implemented.

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

  peek(n)

    Read n uncompressed bytes without advancing the file position. The number of bytes returned may be more or less than requested.

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

    Ajouté dans la version 3.2.

  mode

    `'rb'` for reading and `'wb'` for writing.

    Modifié dans la version 3.13: In previous versions it was an integer `1` or `2`.

  mtime

    When decompressing, this attribute is set to the last timestamp in the most recently read header. It is an integer, holding the number of seconds since the Unix epoch (00:00:00 UTC, January 1, 1970). The initial value before reading any headers is `None`.

  name

    The path to the gzip file on disk, as a `str` or `bytes`. Equivalent to the output of `os.fspath()` on the original input path, with no other normalization, resolution or expansion.

  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.

  Obsolète depuis la version 3.9: Opening `GzipFile` for writing without specifying the mode argument is deprecated.

  Modifié dans la version 3.12: Remove the `filename` attribute, use the `name` attribute instead.

gzip.compress(data, compresslevel=9, *, mtime=0)

  Compress the data, returning a `bytes` object containing the compressed data. compresslevel and mtime have the same meaning as in the `GzipFile` constructor above, but mtime defaults to 0 for reproducible output.

  Ajouté dans la version 3.2.

  Modifié dans la version 3.8: Added the mtime parameter for reproducible output.

  Modifié dans la version 3.11: Speed is improved by compressing all data at once instead of in a streamed fashion. Calls with mtime set to `0` are delegated to `zlib.compress()` for better speed. In this situation the output may contain a gzip header "OS" byte value other than 255 "unknown" as supplied by the underlying zlib implementation.

  Modifié dans la version 3.13: The gzip header OS byte is guaranteed to be set to 255 when this function is used as was the case in 3.10 and earlier.

  Modifié dans la version 3.14: The mtime parameter now defaults to 0 for reproducible output. For the previous behaviour of using the current time, pass `None` to mtime.

gzip.decompress(data)

  Decompress the data, returning a `bytes` object containing the uncompressed data. This function is capable of decompressing multi-member gzip data (multiple gzip blocks concatenated together). When the data is certain to contain only one member the `zlib.decompress()` function with wbits set to 31 is faster.

  Ajouté dans la version 3.2.

  Modifié dans la version 3.11: Speed is improved by decompressing members at once in memory instead of in a streamed fashion.

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

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

## Command-line interface

The `gzip` module provides a simple command line interface to compress or decompress files.

Once executed the `gzip` module keeps the input file(s).

Modifié dans la version 3.8: Add a new command line interface with a usage. By default, when you will execute the CLI, the default compression level is 6.

### Command-line options

file

  If file is not specified, read from `sys.stdin`.

--fast

  Indicates the fastest compression method (less compression).

--best

  Indicates the slowest compression method (best compression).

-d, --decompress

  Decompress the given file.

-h, --help

  Affiche le message d'aide.