gzip — Unterstützung für gzip-Dateien

Quellcode: Lib/gzip.py

Dieses Modul bietet eine einfache Schnittstelle zum Komprimieren und Dekomprimieren von Dateien, genau wie die GNU-Programme gzip und gunzip.

Die Datenkomprimierung wird vom zlib-Modul bereitgestellt.

Das gzip-Modul stellt die Klasse GzipFile sowie die praktischen Funktionen open(), compress() und decompress() bereit. Die Klasse GzipFile liest und schreibt Dateien im gzip-Format und komprimiert oder dekomprimiert die Daten automatisch, sodass sie wie ein gewöhnliches Dateiobjekt aussehen.

Beachten Sie, dass zusätzliche Dateiformate, die von den Programmen gzip und gunzip dekomprimiert werden können, wie z. B. solche, die von compress und pack erzeugt werden, von diesem Modul nicht unterstützt werden.

Das Modul definiert die folgenden Elemente

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

Öffnet eine gzip-komprimierte Datei im Binär- oder Textmodus und gibt ein Dateiobjekt zurück.

Das Argument filename kann ein tatsächlicher Dateiname (ein str- oder bytes-Objekt) oder ein vorhandenes Dateiobjekt zum Lesen oder Schreiben sein.

Das Argument mode kann einer der Modi 'r', 'rb', 'a', 'ab', 'w', 'wb', 'x' oder 'xb' für den Binärmodus oder 'rt', 'at', 'wt' oder 'xt' für den Textmodus sein. Der Standardwert ist 'rb'.

Das Argument compresslevel ist eine Ganzzahl von 0 bis 9, wie beim Konstruktor GzipFile.

Für den Binärmodus ist diese Funktion äquivalent zum Konstruktor GzipFile: GzipFile(filename, mode, compresslevel). In diesem Fall dürfen die Argumente encoding, errors und newline nicht angegeben werden.

Für den Textmodus wird ein GzipFile-Objekt erstellt und mit einer io.TextIOWrapper-Instanz mit der angegebenen Codierung, Fehlerbehandlung und Zeilenumbrüchen umschlossen.

Geändert in Version 3.3: Unterstützung für filename als Dateiobjekt hinzugefügt, Unterstützung für den Textmodus und die Argumente encoding, errors und newline.

Geändert in Version 3.4: Unterstützung für die Modi 'x', 'xb' und 'xt' hinzugefügt.

Geändert in Version 3.6: Akzeptiert ein pfadähnliches Objekt.

Exception gzip.BadGzipFile

Eine Ausnahme, die für ungültige gzip-Dateien ausgelöst wird. Sie erbt von OSError. EOFError und zlib.error können ebenfalls für ungültige gzip-Dateien ausgelöst werden.

Hinzugefügt in Version 3.8.

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

Konstruktor für die Klasse GzipFile, die die meisten Methoden eines Dateiobjekts simuliert, mit Ausnahme der Methode truncate(). Mindestens eines der Argumente fileobj und filename muss einen nicht-trivialen Wert erhalten.

Die neue Klasseninstanz basiert auf fileobj, das eine reguläre Datei, ein io.BytesIO-Objekt oder ein anderes Objekt sein kann, das eine Datei simuliert. Es ist standardmäßig None, in diesem Fall wird filename geöffnet, um ein Dateiobjekt bereitzustellen.

Wenn fileobj nicht None ist, wird das Argument filename nur verwendet, um in den gzip-Dateiheader aufgenommen zu werden, der den ursprünglichen Dateinamen der unkomprimierten Datei enthalten kann. Er ist standardmäßig der Dateiname von fileobj, falls erkennbar; andernfalls ist er standardmäßig die leere Zeichenkette, und in diesem Fall wird der ursprüngliche Dateiname nicht in den Header aufgenommen.

Das Argument mode kann einer der Modi 'r', 'rb', 'a', 'ab', 'w', 'wb', 'x' oder 'xb' sein, je nachdem, ob die Datei gelesen oder geschrieben wird. Der Standardwert ist der Modus von fileobj, falls erkennbar; andernfalls ist der Standardwert 'rb'. In zukünftigen Python-Versionen wird der Modus von fileobj nicht mehr verwendet. Es ist besser, mode immer zum Schreiben anzugeben.

Beachten Sie, dass die Datei immer im Binärmodus geöffnet wird. Um eine komprimierte Datei im Textmodus zu öffnen, verwenden Sie open() (oder umschließen Sie Ihre GzipFile mit einem io.TextIOWrapper).

Das Argument compresslevel ist eine Ganzzahl von 0 bis 9, die den Komprimierungsgrad steuert; 1 ist am schnellsten und erzeugt die geringste Komprimierung, und 9 ist am langsamsten und erzeugt die höchste Komprimierung. 0 bedeutet keine Komprimierung. Der Standardwert ist 9.

Das optionale Argument mtime ist der Zeitstempel, der von gzip angefordert wird. Die Zeit liegt im Unix-Format vor, d. h. Sekunden seit 00:00:00 UTC, 1. Januar 1970. Wenn mtime weggelassen wird oder None ist, wird die aktuelle Zeit verwendet. Verwenden Sie mtime = 0, um einen komprimierten Stream zu erzeugen, der nicht vom Erstellungszeitpunkt abhängt.

Siehe unten für das Attribut mtime, das beim Dekomprimieren gesetzt wird.

Das Aufrufen der Methode close() einer GzipFile-Instanz schließt fileobj nicht, da Sie möglicherweise weiteres Material nach den komprimierten Daten anhängen möchten. Dies ermöglicht Ihnen auch, ein für das Schreiben geöffnetes io.BytesIO-Objekt als fileobj zu übergeben und den resultierenden Speicherpuffer mit der Methode getvalue() des io.BytesIO-Objekts abzurufen.

GzipFile unterstützt die Schnittstelle io.BufferedIOBase, einschließlich Iteration und die with-Anweisung. Nur die Methode truncate() ist nicht implementiert.

GzipFile stellt außerdem die folgende Methode und das folgende Attribut bereit

peek(n)

Liest n unkomprimierte Bytes, ohne die Dateiposition zu verändern. Die Anzahl der zurückgegebenen Bytes kann mehr oder weniger als angefordert sein.

Hinweis

Während der Aufruf von peek() die Dateiposition der GzipFile nicht verändert, kann er die Position des zugrunde liegenden Dateiobjekts verändern (z. B. wenn die GzipFile mit dem Parameter fileobj konstruiert wurde).

Hinzugefügt in Version 3.2.

mode

'rb' zum Lesen und 'wb' zum Schreiben.

Geändert in Version 3.13: In früheren Versionen war es eine Ganzzahl 1 oder 2.

mtime

Beim Dekomprimieren wird dieses Attribut auf den letzten Zeitstempel im zuletzt gelesenen Header gesetzt. Es ist eine Ganzzahl, die die Anzahl der Sekunden seit dem Unix-Epochenbeginn (00:00:00 UTC, 1. Januar 1970) enthält. Der Anfangswert vor dem Lesen von Headern ist None.

name

Der Pfad zur gzip-Datei auf der Festplatte, als str oder bytes. Entspricht der Ausgabe von os.fspath() auf dem ursprünglichen Eingabepfad, ohne weitere Normalisierung, Auflösung oder Expansion.

Geändert in Version 3.1: Unterstützung für die with-Anweisung wurde hinzugefügt, zusammen mit dem Konstruktorargument mtime und dem Attribut mtime.

Geändert in Version 3.2: Unterstützung für null-gepolsterte und nicht-suchbare Dateien wurde hinzugefügt.

Geändert in Version 3.3: Die Methode io.BufferedIOBase.read1() wird jetzt implementiert.

Geändert in Version 3.4: Unterstützung für die Modi 'x' und 'xb' hinzugefügt.

Geändert in Version 3.5: Unterstützung für das Schreiben beliebiger bytesähnlicher Objekte hinzugefügt. Die Methode read() akzeptiert jetzt ein Argument von None.

Geändert in Version 3.6: Akzeptiert ein pfadähnliches Objekt.

Veraltet seit Version 3.9: Das Öffnen von GzipFile zum Schreiben ohne Angabe des Arguments mode ist veraltet.

Geändert in Version 3.12: Entfernen Sie das Attribut filename, verwenden Sie stattdessen das Attribut name.

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

Komprimiert die data und gibt ein bytes-Objekt mit den komprimierten Daten zurück. compresslevel und mtime haben die gleiche Bedeutung wie im obigen Konstruktor GzipFile, aber mtime ist standardmäßig 0 für reproduzierbare Ausgaben.

Hinzugefügt in Version 3.2.

Geändert in Version 3.8: Der Parameter mtime wurde für reproduzierbare Ausgaben hinzugefügt.

Geändert in Version 3.11: Die Geschwindigkeit wird verbessert, indem alle Daten auf einmal statt gestreamt komprimiert werden. Aufrufe mit mtime auf 0 gesetzt, werden an zlib.compress() delegiert, um die Geschwindigkeit zu verbessern. In dieser Situation kann die Ausgabe einen gzip-Header mit dem "OS"-Byte-Wert 255 ("unbekannt") enthalten, wie von der zugrunde liegenden zlib-Implementierung bereitgestellt.

Geändert in Version 3.13: Das gzip-Header-OS-Byte wird garantiert auf 255 gesetzt, wenn diese Funktion verwendet wird, wie es auch in Version 3.10 und früher der Fall war.

Geändert in Version 3.14: Der Parameter mtime ist jetzt standardmäßig 0 für reproduzierbare Ausgaben. Für das vorherige Verhalten, die aktuelle Zeit zu verwenden, übergeben Sie None an mtime.

gzip.decompress(data)

Dekomprimiert die data und gibt ein bytes-Objekt mit den unkomprimierten Daten zurück. Diese Funktion kann Multi-Member-gzip-Daten (mehrere aneinandergereihte gzip-Blöcke) dekomprimieren. Wenn die Daten sicher nur aus einem Mitglied bestehen, ist die Funktion zlib.decompress() mit wbits auf 31 gesetzt schneller.

Hinzugefügt in Version 3.2.

Geändert in Version 3.11: Die Geschwindigkeit wird verbessert, indem Mitglieder auf einmal im Speicher statt gestreamt dekomprimiert werden.

Anwendungsbeispiele

Beispiel für das Lesen einer komprimierten Datei

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

Beispiel für das Erstellen einer komprimierten GZIP-Datei

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

Beispiel für das Komprimieren einer vorhandenen Datei mit GZIP

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)

Beispiel für das Komprimieren eines Binärstrings mit GZIP

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

Siehe auch

Modul zlib

Das grundlegende Datenkomprimierungsmodul, das zur Unterstützung des gzip-Dateiformats erforderlich ist.

Wenn die (De-)Kompression von gzip zum Flaschenhals wird, beschleunigt das Paket python-isal die (De-)Kompression mit einer weitgehend kompatiblen API.

Kommandozeilenschnittstelle

Das Modul gzip bietet eine einfache Befehlszeilenschnittstelle zum Komprimieren oder Dekomprimieren von Dateien.

Nach der Ausführung behält das Modul gzip die Eingabedateien.

Geändert in Version 3.8: Eine neue Befehlszeilenschnittstelle mit einer Nutzung wurde hinzugefügt. Standardmäßig ist die Komprimierungsstufe 6, wenn die CLI ausgeführt wird.

Befehlszeilenoptionen

file

Wenn file nicht angegeben ist, wird von sys.stdin gelesen.

--fast

Gibt die schnellste Komprimierungsmethode an (geringere Komprimierung).

--best

Gibt die langsamste Komprimierungsmethode an (beste Komprimierung).

-d, --decompress

Dekompimiert die angegebene Datei.

-h, --help

Zeigt die Hilfenachricht an.