zlib — Mit gzip kompatible Komprimierung

Für Anwendungen, die Datenkomprimierung erfordern, ermöglichen die Funktionen in diesem Modul die Komprimierung und Dekomprimierung unter Verwendung der zlib-Bibliothek. Die zlib-Bibliothek hat ihre eigene Homepage unter https://www.zlib.net. Es gibt bekannte Inkompatibilitäten zwischen dem Python-Modul und Versionen der zlib-Bibliothek vor 1.1.3; 1.1.3 hat eine Sicherheitslücke, daher empfehlen wir die Verwendung von 1.1.4 oder neuer.

Die Funktionen von zlib haben viele Optionen und müssen oft in einer bestimmten Reihenfolge verwendet werden. Diese Dokumentation versucht nicht, alle Permutationen abzudecken; konsultieren Sie das zlib-Handbuch für maßgebliche Informationen.

Zum Lesen und Schreiben von .gz-Dateien siehe das Modul gzip.

Die in diesem Modul verfügbare Ausnahme und Funktionen sind

Ausnahme zlib.error

Ausnahme, die bei Komprimierungs- und Dekomprimierungsfehlern ausgelöst wird.

zlib.adler32(data[, value])

Berechnet eine Adler-32-Prüfsumme von data. (Eine Adler-32-Prüfsumme ist fast so zuverlässig wie eine CRC32, kann aber viel schneller berechnet werden.) Das Ergebnis ist eine vorzeichenlose 32-Bit-Ganzzahl. Wenn value vorhanden ist, wird es als Startwert der Prüfsumme verwendet; andernfalls wird ein Standardwert von 1 verwendet. Die Übergabe von value ermöglicht die Berechnung einer laufenden Prüfsumme über die Verkettung mehrerer Eingaben. Der Algorithmus ist nicht kryptografisch stark und sollte nicht für Authentifizierung oder digitale Signaturen verwendet werden. Da der Algorithmus für die Verwendung als Prüfsummen-Algorithmus konzipiert ist, ist er nicht für die Verwendung als allgemeiner Hash-Algorithmus geeignet.

Geändert in Version 3.0: Das Ergebnis ist immer vorzeichenlos.

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

Komprimiert die Bytes in data und gibt ein Bytes-Objekt mit komprimierten Daten zurück. level ist eine Ganzzahl von 0 bis 9 oder -1, die die Komprimierungsstufe steuert; 1 (Z_BEST_SPEED) ist am schnellsten und erzeugt die geringste Komprimierung, 9 (Z_BEST_COMPRESSION) ist am langsamsten und erzeugt die höchste Komprimierung. 0 (Z_NO_COMPRESSION) bedeutet keine Komprimierung. Der Standardwert ist -1 (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION stellt einen Standardkompromiss zwischen Geschwindigkeit und Komprimierung dar (derzeit äquivalent zu Stufe 6).

Das Argument wbits steuert die Größe des Verlaufs-Puffers (oder der "Fenstergröße"), der zur Komprimierung von Daten verwendet wird, und ob ein Header und ein Trailer in der Ausgabe enthalten sind. Es kann mehrere Wertebereiche annehmen, wobei der Standardwert 15 (MAX_WBITS) ist.

  • +9 bis +15: Der Logarithmus zur Basis zwei der Fenstergröße, die somit zwischen 512 und 32768 liegt. Größere Werte ergeben eine bessere Komprimierung auf Kosten eines höheren Speicherverbrauchs. Die resultierende Ausgabe enthält einen zlib-spezifischen Header und Trailer.

  • −9 bis −15: Verwendet den Absolutwert von wbits als Logarithmus der Fenstergröße, während ein roher Ausgabestrom ohne Header oder nachfolgende Prüfsumme erzeugt wird.

  • +25 bis +31 = 16 + (9 bis 15): Verwendet die unteren 4 Bits des Wertes als Logarithmus der Fenstergröße, während ein grundlegender gzip-Header und eine nachfolgende Prüfsumme in der Ausgabe enthalten sind.

Löst die Ausnahme error aus, wenn ein Fehler auftritt.

Geändert in Version 3.6: level kann jetzt als Schlüsselwortparameter verwendet werden.

Geändert in Version 3.11: Der Parameter wbits ist jetzt verfügbar, um Fensterbits und Komprimierungstyp festzulegen.

zlib.compressobj(level=-1, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

Gibt ein Komprimierungsobjekt zurück, das zur Komprimierung von Datenströmen verwendet werden soll, die nicht vollständig in den Speicher passen.

level ist die Komprimierungsstufe – eine Ganzzahl von 0 bis 9 oder -1. Ein Wert von 1 (Z_BEST_SPEED) ist am schnellsten und erzeugt die geringste Komprimierung, während ein Wert von 9 (Z_BEST_COMPRESSION) am langsamsten ist und die höchste Komprimierung erzeugt. 0 (Z_NO_COMPRESSION) bedeutet keine Komprimierung. Der Standardwert ist -1 (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION stellt einen Standardkompromiss zwischen Geschwindigkeit und Komprimierung dar (derzeit äquivalent zu Stufe 6).

method ist der Komprimierungsalgorithmus. Derzeit ist der einzige unterstützte Wert DEFLATED.

Der Parameter wbits steuert die Größe des Verlaufs-Puffers (oder der „Fenstergröße“) und welches Header- und Trailer-Format verwendet wird. Er hat die gleiche Bedeutung wie in compress() beschrieben.

Das Argument memLevel steuert die Menge des Speichers, der für den internen Komprimierungszustand verwendet wird. Gültige Werte reichen von 1 bis 9. Höhere Werte verbrauchen mehr Speicher, sind aber schneller und erzeugen kleinere Ausgaben.

strategy wird zur Feinabstimmung des Komprimierungsalgorithmus verwendet. Mögliche Werte sind Z_DEFAULT_STRATEGY, Z_FILTERED, Z_HUFFMAN_ONLY, Z_RLE (zlib 1.2.0.1) und Z_FIXED (zlib 1.2.2.2).

zdict ist ein vordefiniertes Komprimierungsdictionary. Dies ist eine Sequenz von Bytes (wie z. B. ein bytes-Objekt), die Teilsequenzen enthält, die voraussichtlich häufig in den zu komprimierenden Daten vorkommen. Die am häufigsten erwarteten Teilsequenzen sollten am Ende des Dictionaries stehen.

Geändert in Version 3.3: Parameter zdict und Unterstützung für Schlüsselwortargumente hinzugefügt.

zlib.crc32(data[, value])

Berechnet eine CRC-Prüfsumme (Cyclic Redundancy Check) von data. Das Ergebnis ist eine vorzeichenlose 32-Bit-Ganzzahl. Wenn value vorhanden ist, wird es als Startwert der Prüfsumme verwendet; andernfalls wird ein Standardwert von 0 verwendet. Die Übergabe von value ermöglicht die Berechnung einer laufenden Prüfsumme über die Verkettung mehrerer Eingaben. Der Algorithmus ist nicht kryptografisch stark und sollte nicht für Authentifizierung oder digitale Signaturen verwendet werden. Da der Algorithmus für die Verwendung als Prüfsummen-Algorithmus konzipiert ist, ist er nicht für die Verwendung als allgemeiner Hash-Algorithmus geeignet.

Geändert in Version 3.0: Das Ergebnis ist immer vorzeichenlos.

zlib.decompress(data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

Dekomprimiert die Bytes in data und gibt ein Bytes-Objekt mit den unkomprimierten Daten zurück. Der Parameter wbits hängt vom Format von data ab und wird weiter unten erläutert. Wenn bufsize angegeben ist, wird es als Anfangsgröße des Ausgabepuffers verwendet. Löst die Ausnahme error aus, wenn ein Fehler auftritt.

Der Parameter wbits steuert die Größe des Verlaufs-Puffers (oder der "Fenstergröße") und welches Header- und Trailer-Format erwartet wird. Er ähnelt dem Parameter für compressobj(), akzeptiert jedoch mehr Wertebereiche

  • +8 bis +15: Der Logarithmus zur Basis zwei der Fenstergröße. Die Eingabe muss einen zlib-Header und -Trailer enthalten.

  • 0: Die Fenstergröße wird automatisch aus dem zlib-Header ermittelt. Nur unterstützt seit zlib 1.2.3.5.

  • −8 bis −15: Verwendet den Absolutwert von wbits als Logarithmus der Fenstergröße. Die Eingabe muss ein roher Stream ohne Header oder Trailer sein.

  • +24 bis +31 = 16 + (8 bis 15): Verwendet die unteren 4 Bits des Wertes als Logarithmus der Fenstergröße. Die Eingabe muss einen gzip-Header und -Trailer enthalten.

  • +40 bis +47 = 32 + (8 bis 15): Verwendet die unteren 4 Bits des Wertes als Logarithmus der Fenstergröße und akzeptiert automatisch entweder das zlib- oder das gzip-Format.

Beim Dekomprimieren eines Streams darf die Fenstergröße nicht kleiner sein als die ursprünglich zum Komprimieren des Streams verwendete Größe; die Verwendung eines zu kleinen Wertes kann zu einer Ausnahme error führen. Der Standardwert für wbits entspricht der größten Fenstergröße und erfordert die Einbeziehung eines zlib-Headers und -Trailers.

bufsize ist die Anfangsgröße des Puffers, der zur Speicherung der dekomprimierten Daten verwendet wird. Wenn mehr Speicher benötigt wird, wird die Puffergröße bei Bedarf erhöht, sodass Sie diesen Wert nicht exakt richtig angeben müssen; die Optimierung spart nur einige Aufrufe von malloc().

Geändert in Version 3.6: wbits und bufsize können als Schlüsselwortargumente verwendet werden.

zlib.decompressobj(wbits=MAX_WBITS[, zdict])

Gibt ein Dekomprimierungsobjekt zurück, das zur Dekomprimierung von Datenströmen verwendet werden soll, die nicht vollständig in den Speicher passen.

Der Parameter wbits steuert die Größe des Verlaufs-Puffers (oder der "Fenstergröße") und welches Header- und Trailer-Format erwartet wird. Er hat die gleiche Bedeutung wie in decompress() beschrieben.

Der Parameter zdict gibt ein vordefiniertes Komprimierungsdictionary an. Wenn dies angegeben wird, muss es dasselbe Dictionary sein, das vom Komprimierer verwendet wurde, der die zu dekomprimierenden Daten erzeugt hat.

Hinweis

Wenn zdict ein veränderbares Objekt ist (wie z. B. ein bytearray), dürfen Sie dessen Inhalt nicht zwischen dem Aufruf von decompressobj() und dem ersten Aufruf der decompress()-Methode des Dekomprimierers ändern.

Geändert in Version 3.3: Parameter zdict hinzugefügt.

Dekompressionsobjekte unterstützen die folgenden Methoden

Compress.compress(data)

Komprimiert data und gibt ein Bytes-Objekt mit komprimierten Daten für mindestens einen Teil der Daten in data zurück. Diese Daten sollten an die Ausgabe angehängt werden, die durch vorherige Aufrufe der Methode compress() erzeugt wurde. Einige Eingaben können zur späteren Verarbeitung in internen Puffern gespeichert werden.

Compress.flush([mode])

Alle ausstehenden Eingaben werden verarbeitet, und ein Bytes-Objekt mit den verbleibenden komprimierten Ausgaben wird zurückgegeben. mode kann aus den Konstanten Z_NO_FLUSH, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH, Z_FULL_FLUSH, Z_BLOCK (zlib 1.2.3.4) oder Z_FINISH ausgewählt werden, standardmäßig Z_FINISH. Mit Ausnahme von Z_FINISH erlauben alle Konstanten die Komprimierung weiterer Byte-Strings, während Z_FINISH den komprimierten Stream beendet und keine weitere Komprimierung zulässt. Nach dem Aufruf von flush() mit mode auf Z_FINISH gesetzt, kann die Methode compress() nicht mehr aufgerufen werden; die einzig sinnvolle Aktion ist das Löschen des Objekts.

Compress.copy()

Gibt eine Kopie des Komprimierungsobjekts zurück. Dies kann verwendet werden, um effizient eine Reihe von Daten zu komprimieren, die ein gemeinsames Anfangspräfix teilen.

Geändert in Version 3.8: Unterstützung für copy.copy() und copy.deepcopy() für Komprimierungsobjekte hinzugefügt.

Dekompressionsobjekte unterstützen die folgenden Methoden und Attribute

Decompress.unused_data

Ein Bytes-Objekt, das alle Bytes nach dem Ende der komprimierten Daten enthält. Das heißt, dies bleibt b"", bis das letzte Byte, das Komprimierungsdaten enthält, verfügbar ist. Wenn der gesamte Bytestring komprimierte Daten enthielt, ist dies b"", ein leeres Bytes-Objekt.

Decompress.unconsumed_tail

Ein Bytes-Objekt, das alle Daten enthält, die vom letzten Aufruf von decompress() nicht verbraucht wurden, da sie das Limit für den Puffer unkomprimierter Daten überschritten haben. Diese Daten wurden von der zlib-Maschinerie noch nicht verarbeitet, daher müssen Sie sie (möglicherweise mit weiteren angehängten Daten) an einen nachfolgenden Aufruf der Methode decompress() übergeben, um korrekte Ausgaben zu erhalten.

Decompress.eof

Ein boolescher Wert, der angibt, ob das Ende des komprimierten Datenstroms erreicht wurde.

Dies ermöglicht die Unterscheidung zwischen einem korrekt formatierten komprimierten Stream und einem unvollständigen oder abgeschnittenen Stream.

Hinzugefügt in Version 3.3.

Decompress.decompress(data, max_length=0)

Dekomprimiert data und gibt ein Bytes-Objekt mit den unkomprimierten Daten zurück, die mindestens einem Teil der Daten in string entsprechen. Diese Daten sollten an die Ausgabe angehängt werden, die durch vorherige Aufrufe der Methode decompress() erzeugt wurde. Einige der Eingabedaten können zur späteren Verarbeitung in internen Puffern gespeichert werden.

Wenn der optionale Parameter max_length ungleich Null ist, ist die Rückgabe nicht länger als max_length. Dies kann bedeuten, dass nicht alle komprimierten Eingaben verarbeitet werden können; und nicht verbrauchte Daten werden im Attribut unconsumed_tail gespeichert. Dieser Bytestring muss an einen nachfolgenden Aufruf von decompress() übergeben werden, damit die Dekomprimierung fortgesetzt werden kann. Wenn max_length Null ist, werden alle Eingaben dekomprimiert und unconsumed_tail ist leer.

Geändert in Version 3.6: max_length kann als Schlüsselwortargument verwendet werden.

Decompress.flush([length])

Alle ausstehenden Eingaben werden verarbeitet, und ein Bytes-Objekt mit den verbleibenden unkomprimierten Ausgaben wird zurückgegeben. Nach dem Aufruf von flush() kann die Methode decompress() nicht mehr aufgerufen werden; die einzig sinnvolle Aktion ist das Löschen des Objekts.

Der optionale Parameter length legt die Anfangsgröße des Ausgabepuffers fest.

Decompress.copy()

Gibt eine Kopie des Dekomprimierungsobjekts zurück. Dies kann verwendet werden, um den Zustand des Dekomprimierers auf halbem Weg durch den Datenstrom zu speichern, um zufällige Sprünge in den Strom zu einem späteren Zeitpunkt zu beschleunigen.

Geändert in Version 3.8: Unterstützung für copy.copy() und copy.deepcopy() für Dekomprimierungsobjekte hinzugefügt.

Die folgenden Konstanten sind verfügbar, um das Komprimierungs- und Dekomprimierungsverhalten zu konfigurieren

zlib.DEFLATED

Die Deflate-Komprimierungsmethode.

zlib.MAX_WBITS

Die maximale Fenstergröße, ausgedrückt als Potenz von 2. Wenn z. B. MAX_WBITS 15 ist, ergibt sich eine Fenstergröße von 32 KiB.

zlib.DEF_MEM_LEVEL

Die Standard-Speicherebene für Komprimierungsobjekte.

zlib.DEF_BUF_SIZE

Die Standard-Puffergröße für Dekomprimierungsoperationen.

zlib.Z_NO_COMPRESSION

Komprimierungsstufe 0.

Hinzugefügt in Version 3.6.

zlib.Z_BEST_SPEED

Komprimierungsstufe 1.

zlib.Z_BEST_COMPRESSION

Komprimierungsstufe 9.

zlib.Z_DEFAULT_COMPRESSION

Standard-Komprimierungsstufe (-1).

zlib.Z_DEFAULT_STRATEGY

Standard-Komprimierungsstrategie für normale Daten.

zlib.Z_FILTERED

Komprimierungsstrategie für Daten, die von einem Filter (oder Prädiktor) erzeugt wurden.

zlib.Z_HUFFMAN_ONLY

Komprimierungsstrategie, die nur Huffman-Kodierung erzwingt.

zlib.Z_RLE

Komprimierungsstrategie, die die Übereinstimmungsabstände auf eins beschränkt (Run-Length-Encoding).

Diese Konstante ist nur verfügbar, wenn Python mit zlib 1.2.0.1 oder neuer kompiliert wurde.

Hinzugefügt in Version 3.6.

zlib.Z_FIXED

Komprimierungsstrategie, die die Verwendung dynamischer Huffman-Codes verhindert.

Diese Konstante ist nur verfügbar, wenn Python mit zlib 1.2.2.2 oder neuer kompiliert wurde.

Hinzugefügt in Version 3.6.

zlib.Z_NO_FLUSH

Flush-Modus 0. Kein spezielles Flush-Verhalten.

Hinzugefügt in Version 3.6.

zlib.Z_PARTIAL_FLUSH

Flush-Modus 1. Gibt so viel Ausgabe wie möglich aus.

zlib.Z_SYNC_FLUSH

Flush-Modus 2. Alle Ausgaben werden geflusht und die Ausgabe wird an eine Bytegrenze ausgerichtet.

zlib.Z_FULL_FLUSH

Flush-Modus 3. Alle Ausgaben werden geflusht und der Komprimierungszustand wird zurückgesetzt.

zlib.Z_FINISH

Flush-Modus 4. Alle ausstehenden Eingaben werden verarbeitet, es werden keine weiteren Eingaben erwartet.

zlib.Z_BLOCK

Flush-Modus 5. Ein Deflate-Block wird abgeschlossen und ausgegeben.

Diese Konstante ist nur verfügbar, wenn Python mit zlib 1.2.2.2 oder neuer kompiliert wurde.

Hinzugefügt in Version 3.6.

zlib.Z_TREES

Flush-Modus 6, für Inflate-Operationen. Weist Inflate an, zurückzukehren, wenn es zum nächsten Deflate-Block-Boundary gelangt.

Diese Konstante ist nur verfügbar, wenn Python mit zlib 1.2.3.4 oder neuer kompiliert wurde.

Hinzugefügt in Version 3.6.

Informationen über die verwendete Version der zlib-Bibliothek sind über die folgenden Konstanten verfügbar

zlib.ZLIB_VERSION

Die Versionszeichenfolge der zlib-Bibliothek, die zum Erstellen des Moduls verwendet wurde. Dies kann von der tatsächlich zur Laufzeit verwendeten zlib-Bibliothek abweichen, die als ZLIB_RUNTIME_VERSION verfügbar ist.

zlib.ZLIB_RUNTIME_VERSION

Die Versionszeichenfolge der zlib-Bibliothek, die tatsächlich vom Interpreter geladen wurde.

Hinzugefügt in Version 3.3.

zlib.ZLIBNG_VERSION

Die Versionszeichenkette der zlib-ng-Bibliothek, die zum Erstellen des Moduls verwendet wurde, falls zlib-ng verwendet wurde. Wenn vorhanden, spiegeln die Konstanten ZLIB_VERSION und ZLIB_RUNTIME_VERSION die Version der von zlib-ng bereitgestellten zlib-API wider.

Wenn zlib-ng nicht zum Erstellen des Moduls verwendet wurde, ist diese Konstante nicht vorhanden.

Hinzugefügt in Version 3.14.

Siehe auch

Modul gzip

Lesen und Schreiben von Dateien im gzip-Format.

https://www.zlib.net

Die Homepage der zlib-Bibliothek.

https://www.zlib.net/manual.html

Das zlib-Handbuch erklärt die Semantik und die Verwendung der vielen Funktionen der Bibliothek.

Falls die gzip-(De-)Kompression ein Engpass ist, beschleunigt das Paket python-isal die (De-)Kompression mit einer weitgehend kompatiblen API.