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.