compression.zstd — Kompression kompatibel mit dem Zstandard-Format

Hinzugefügt in Version 3.14.

Quellcode: Lib/compression/zstd/__init__.py

Dieses Modul stellt Klassen und Funktionen zum Komprimieren und Dekomprimieren von Daten mit dem Zstandard (oder zstd) Kompressionsalgorithmus bereit. Das zstd-Handbuch beschreibt Zstandard als "einen schnellen verlustfreien Kompressionsalgorithmus, der auf Echtzeit-Komprimierungsszenarien mit Kompressionsraten auf zlib-Niveau oder besser abzielt". Ebenfalls enthalten ist eine Dateischnittstelle, die das Lesen und Schreiben von Inhalten von .zst-Dateien, die vom zstd-Dienstprogramm erstellt wurden, sowie von rohen zstd-komprimierten Streams unterstützt.

Das Modul compression.zstd enthält

Ausnahmen

exception compression.zstd.ZstdError

Diese Ausnahme wird ausgelöst, wenn während der Komprimierung oder Dekomprimierung oder bei der Initialisierung des (De-)Kompressor-Zustands ein Fehler auftritt.

Lesen und Schreiben komprimierter Dateien

compression.zstd.open(file, /, mode='rb', *, level=None, options=None, zstd_dict=None, encoding=None, errors=None, newline=None)

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

Das Argument file kann entweder ein Dateiname sein (als str, bytes oder pfadähnliches Objekt) oder ein vorhandenes Dateiobjekt zum Lesen oder Schreiben sein.

Das Argument mode kann entweder 'rb' zum Lesen (Standard), 'wb' zum Überschreiben, 'ab' zum Anhängen oder 'xb' zum exklusiven Erstellen sein. Diese können äquivalent als 'r', 'w', 'a' und 'x' angegeben werden. Sie können auch im Textmodus mit 'rt', 'wt', 'at' und 'xt' geöffnet werden.

Beim Lesen kann das Argument options ein Wörterbuch sein, das erweiterte Dekompressionsparameter bereitstellt; siehe DecompressionParameter für detaillierte Informationen zu unterstützten Parametern. Das Argument zstd_dict ist eine ZstdDict-Instanz, die während der Dekomprimierung verwendet werden soll. Beim Lesen, wenn das Argument level nicht None ist, wird ein TypeError ausgelöst.

Beim Schreiben kann das Argument options ein Wörterbuch sein, das erweiterte Dekompressionsparameter bereitstellt; siehe CompressionParameter für detaillierte Informationen zu unterstützten Parametern. Das Argument level ist die Kompressionsstufe, die beim Schreiben von komprimierten Daten verwendet werden soll. Nur eines von level oder options darf nicht None sein. Das Argument zstd_dict ist eine ZstdDict-Instanz, die während der Komprimierung verwendet werden soll.

Im Binärmodus ist diese Funktion äquivalent zum Konstruktor von ZstdFile: ZstdFile(file, mode, ...). In diesem Fall dürfen die Parameter encoding, errors und newline nicht angegeben werden.

Im Textmodus wird ein ZstdFile-Objekt erstellt und in eine io.TextIOWrapper-Instanz mit der angegebenen Kodierung, Fehlerbehandlung und Zeilenumbrüchen eingewickelt.

class compression.zstd.ZstdFile(file, /, mode='rb', *, level=None, options=None, zstd_dict=None)

Öffnet eine Zstandard-komprimierte Datei im Binärmodus.

Eine ZstdFile kann ein bereits geöffnetes Dateiobjekt umschließen oder direkt auf einer benannten Datei arbeiten. Das Argument file gibt entweder das zu umschließende Dateiobjekt oder den Namen der zu öffnenden Datei an (als str, bytes oder pfadähnliches Objekt). Wenn ein vorhandenes Dateiobjekt umschlossen wird, wird die umschlossene Datei beim Schließen der ZstdFile nicht geschlossen.

Das Argument mode kann entweder 'rb' zum Lesen (Standard), 'wb' zum Überschreiben, 'xb' zum exklusiven Erstellen oder 'ab' zum Anhängen sein. Diese können äquivalent als 'r', 'w', 'x' und 'a' angegeben werden.

Wenn file ein Dateiobjekt ist (statt eines tatsächlichen Dateinamens), kürzt ein Modus von 'w' die Datei nicht und ist stattdessen äquivalent zu 'a'.

Beim Lesen kann das Argument options ein Wörterbuch sein, das erweiterte Dekompressionsparameter bereitstellt; siehe DecompressionParameter für detaillierte Informationen zu unterstützten Parametern. Das Argument zstd_dict ist eine ZstdDict-Instanz, die während der Dekomprimierung verwendet werden soll. Beim Lesen, wenn das Argument level nicht None ist, wird ein TypeError ausgelöst.

Beim Schreiben kann das Argument options ein Wörterbuch sein, das erweiterte Dekompressionsparameter bereitstellt; siehe CompressionParameter für detaillierte Informationen zu unterstützten Parametern. Das Argument level ist die Kompressionsstufe, die beim Schreiben von komprimierten Daten verwendet werden soll. Nur eines von level oder options darf übergeben werden. Das Argument zstd_dict ist eine ZstdDict-Instanz, die während der Komprimierung verwendet werden soll.

ZstdFile unterstützt alle von io.BufferedIOBase spezifizierten Member, außer detach() und truncate(). Iteration und die with-Anweisung werden unterstützt.

Die folgenden Methoden und Attribute werden ebenfalls bereitgestellt

peek(size=-1)

Gibt gepufferte Daten zurück, ohne die Dateiposition zu ändern. Mindestens ein Byte Daten wird zurückgegeben, es sei denn, das Ende der Datei wurde erreicht. Die genaue Anzahl der zurückgegebenen Bytes ist nicht spezifiziert (das Argument size wird ignoriert).

Hinweis

Während ein Aufruf von peek() die Dateiposition der ZstdFile nicht ändert, kann sie die Position des zugrunde liegenden Dateiobjekts ändern (z. B. wenn die ZstdFile durch Übergabe eines Dateiobjekts für file konstruiert wurde).

mode

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

name

Der Name der Zstandard-Datei. Äquivalent zum Attribut name des zugrunde liegenden Dateiobjekts.

Daten im Speicher komprimieren und dekomprimieren

compression.zstd.compress(data, level=None, options=None, zstd_dict=None)

Komprimiert data (ein byteähnliches Objekt) und gibt die komprimierten Daten als bytes-Objekt zurück.

Das Argument level ist eine Ganzzahl, die die Kompressionsstufe steuert. level ist eine Alternative zum Setzen von CompressionParameter.compression_level in options. Verwenden Sie bounds() für compression_level, um die für level übergebenen Werte zu erhalten. Wenn erweiterte Kompressionsoptionen benötigt werden, muss das Argument level weggelassen und im options-Wörterbuch der Parameter CompressionParameter.compression_level gesetzt werden.

Das Argument options ist ein Python-Wörterbuch, das erweiterte Kompressionsparameter enthält. Die gültigen Schlüssel und Werte für Kompressionsparameter sind in der Dokumentation zu CompressionParameter dokumentiert.

Das Argument zstd_dict ist eine Instanz von ZstdDict, die trainierte Daten zur Verbesserung der Kompressionseffizienz enthält. Die Funktion train_dict() kann verwendet werden, um ein Zstandard-Wörterbuch zu generieren.

compression.zstd.decompress(data, zstd_dict=None, options=None)

Dekomprimiert data (ein byteähnliches Objekt) und gibt die unkomprimierten Daten als bytes-Objekt zurück.

Das Argument options ist ein Python-Wörterbuch, das erweiterte Dekompressionsparameter enthält. Die gültigen Schlüssel und Werte für Kompressionsparameter sind in der Dokumentation zu DecompressionParameter dokumentiert.

Das Argument zstd_dict ist eine Instanz von ZstdDict, die während der Komprimierung verwendete trainierte Daten enthält. Dies muss dasselbe Zstandard-Wörterbuch sein, das während der Komprimierung verwendet wurde.

Wenn data die Verkettung mehrerer separater komprimierter Frames ist, werden all diese Frames dekomprimiert und die Verkettung der Ergebnisse zurückgegeben.

class compression.zstd.ZstdCompressor(level=None, options=None, zstd_dict=None)

Erzeugt ein Kompressor-Objekt, das zur inkrementellen Komprimierung von Daten verwendet werden kann.

Für eine bequemere Komprimierung eines einzelnen Datenblocks siehe die Modulfunktion compress().

Das Argument level ist eine Ganzzahl, die die Kompressionsstufe steuert. level ist eine Alternative zum Setzen von CompressionParameter.compression_level in options. Verwenden Sie bounds() für compression_level, um die für level übergebenen Werte zu erhalten. Wenn erweiterte Kompressionsoptionen benötigt werden, muss das Argument level weggelassen und im options-Wörterbuch der Parameter CompressionParameter.compression_level gesetzt werden.

Das Argument options ist ein Python-Wörterbuch, das erweiterte Kompressionsparameter enthält. Die gültigen Schlüssel und Werte für Kompressionsparameter sind in der Dokumentation zu CompressionParameter dokumentiert.

Das Argument zstd_dict ist eine optionale Instanz von ZstdDict, die trainierte Daten zur Verbesserung der Kompressionseffizienz enthält. Die Funktion train_dict() kann verwendet werden, um ein Zstandard-Wörterbuch zu generieren.

compress(data, mode=ZstdCompressor.CONTINUE)

Komprimiert data (ein byteähnliches Objekt) und gibt ein bytes-Objekt mit komprimierten Daten zurück, falls möglich, andernfalls ein leeres bytes-Objekt. Einige von data können intern für spätere Aufrufe von compress() und flush() gepuffert werden. Die zurückgegebenen Daten sollten mit der Ausgabe früherer Aufrufe von compress() verkettet werden.

Das Argument mode ist ein Attribut von ZstdCompressor, entweder CONTINUE, FLUSH_BLOCK oder FLUSH_FRAME.

Wenn alle Daten an den Kompressor übergeben wurden, rufen Sie die Methode flush() auf, um den Komprimierungsvorgang abzuschließen. Wenn compress() mit mode auf FLUSH_FRAME gesetzt aufgerufen wird, sollte flush() nicht aufgerufen werden, da dies einen neuen leeren Frame ausgeben würde.

flush(mode=ZstdCompressor.FLUSH_FRAME)

Schließt den Komprimierungsvorgang ab und gibt ein bytes-Objekt zurück, das alle im internen Puffer des Kompressors gespeicherten Daten enthält.

Das Argument mode ist ein Attribut von ZstdCompressor, entweder FLUSH_BLOCK oder FLUSH_FRAME.

set_pledged_input_size(size)

Gibt die Menge der unkomprimierten Daten size an, die für den nächsten Frame bereitgestellt werden. size wird in den Frame-Header des nächsten Frames geschrieben, es sei denn, CompressionParameter.content_size_flag ist False oder 0. Eine Größe von 0 bedeutet, dass der Frame leer ist. Wenn size None ist, lässt der Frame-Header die Frame-Größe weg. Frames, die die Größe der unkomprimierten Daten enthalten, benötigen weniger Speicher zum Dekomprimieren, insbesondere bei höheren Kompressionsstufen.

Wenn last_mode nicht FLUSH_FRAME ist, wird ein ValueError ausgelöst, da der Kompressor nicht am Anfang eines Frames ist. Wenn die zugesicherte Größe nicht mit der tatsächlichen Größe der an compress() übergebenen Daten übereinstimmt, können zukünftige Aufrufe von compress() oder flush() ZstdError auslösen und der letzte Datenblock kann verloren gehen.

Nachdem flush() oder compress() mit dem Modus FLUSH_FRAME aufgerufen wurden, enthält der nächste Frame keine Frame-Größe im Header, es sei denn, set_pledged_input_size() wird erneut aufgerufen.

CONTINUE

Sammelt weitere Daten zur Komprimierung, was sofort oder verzögert zu Ausgabe führen kann. Dieser Modus optimiert die Kompressionsrate, indem die Datenmenge pro Block und Frame maximiert wird.

FLUSH_BLOCK

Schließt einen Block ab und schreibt ihn in den Datenstrom. Die bisher zurückgegebenen Daten können sofort dekomprimiert werden. Vergangene Daten können in zukünftigen Blöcken, die durch Aufrufe von compress() erzeugt werden, referenziert werden, was die Komprimierung verbessert.

FLUSH_FRAME

Schließt einen Frame ab und gibt ihn aus. Zukünftige Daten, die an compress() übergeben werden, werden in einen neuen Frame geschrieben und *können* keine vergangenen Daten referenzieren.

last_mode

Der letzte Modus, der an entweder compress() oder flush() übergeben wurde. Der Wert kann einer von CONTINUE, FLUSH_BLOCK oder FLUSH_FRAME sein. Der Anfangswert ist FLUSH_FRAME, was bedeutet, dass der Kompressor sich am Anfang eines neuen Frames befindet.

class compression.zstd.ZstdDecompressor(zstd_dict=None, options=None)

Erstellt ein Dekomprimierungsobjekt, das zur inkrementellen Dekomprimierung von Daten verwendet werden kann.

Für eine bequemere Methode, einen gesamten komprimierten Stream auf einmal zu dekomprimieren, siehe die Modulfunktion decompress().

Das Argument options ist ein Python-Wörterbuch, das erweiterte Dekompressionsparameter enthält. Die gültigen Schlüssel und Werte für Kompressionsparameter sind in der Dokumentation zu DecompressionParameter dokumentiert.

Das Argument zstd_dict ist eine Instanz von ZstdDict, die während der Komprimierung verwendete trainierte Daten enthält. Dies muss dasselbe Zstandard-Wörterbuch sein, das während der Komprimierung verwendet wurde.

Hinweis

Diese Klasse behandelt keine Eingaben, die mehrere komprimierte Frames enthalten, transparent, im Gegensatz zur Funktion decompress() und der Klasse ZstdFile. Um eine Eingabe mit mehreren Frames zu dekomprimieren, sollten Sie decompress(), ZstdFile verwenden, wenn Sie mit einem Dateiobjekt arbeiten, oder mehrere Instanzen von ZstdDecompressor.

decompress(data, max_length=-1)

Dekomprimiert data (ein bytes-ähnliches Objekt) und gibt unkomprimierte Daten als Bytes zurück. Ein Teil von data kann intern zwischengespeichert werden, um ihn in späteren Aufrufen von decompress() zu verwenden. Die zurückgegebenen Daten sollten mit der Ausgabe früherer Aufrufe von decompress() verkettet werden.

Wenn max_length nicht negativ ist, gibt die Methode höchstens max_length Bytes dekomprimierte Daten zurück. Wenn dieses Limit erreicht ist und weitere Ausgaben erzeugt werden können, wird das Attribut needs_input auf False gesetzt. In diesem Fall kann der nächste Aufruf von decompress() data als b'' bereitstellen, um mehr von der Ausgabe zu erhalten.

Wenn alle Eingabedaten dekomprimiert und zurückgegeben wurden (entweder weil dies weniger als max_length Bytes waren oder weil max_length negativ war), wird das Attribut needs_input auf True gesetzt.

Der Versuch, Daten nach dem Ende eines Frames zu dekomprimieren, löst eine ZstdError aus. Alle nach dem Ende des Frames gefundenen Daten werden ignoriert und im Attribut unused_data gespeichert.

eof

True, wenn die End-of-Stream-Markierung erreicht wurde.

unused_data

Daten, die nach dem Ende des komprimierten Streams gefunden wurden.

Vor Erreichen des Stream-Endes ist dies b''.

needs_input

False, wenn die Methode decompress() weitere dekomprimierte Daten bereitstellen kann, bevor neue komprimierte Eingaben erforderlich sind.

Zstandard-Wörterbücher

compression.zstd.train_dict(samples, dict_size)

Trainiert ein Zstandard-Wörterbuch und gibt eine Instanz von ZstdDict zurück. Zstandard-Wörterbücher ermöglichen eine effizientere Komprimierung kleinerer Datenmengen, die traditionell schwer zu komprimieren sind, da weniger Wiederholungen vorkommen. Wenn Sie mehrere ähnliche Datengruppen komprimieren (z. B. ähnliche Dateien), können Zstandard-Wörterbücher die Komprimierungsverhältnisse und die Geschwindigkeit erheblich verbessern.

Das Argument samples (ein Iterable von bytes-Objekten) ist die Population von Stichproben, die zum Trainieren des Zstandard-Wörterbuchs verwendet wird.

Das Argument dict_size, eine Ganzzahl, ist die maximale Größe (in Bytes), die das Zstandard-Wörterbuch haben soll. Die Zstandard-Dokumentation schlägt ein absolutes Maximum von nicht mehr als 100 KB vor, aber das Maximum kann je nach Daten oft kleiner sein. Größere Wörterbücher verlangsamen in der Regel die Komprimierung, verbessern aber die Komprimierungsverhältnisse. Kleinere Wörterbücher führen zu schnellerer Komprimierung, reduzieren aber das Komprimierungsverhältnis.

compression.zstd.finalize_dict(zstd_dict, /, samples, dict_size, level)

Eine erweiterte Funktion zur Konvertierung eines Zstandard-Wörterbuchs mit „rohem Inhalt“ in ein reguläres Zstandard-Wörterbuch. „Rohinhalt“-Wörterbücher sind eine Byte-Sequenz, die nicht der Struktur eines normalen Zstandard-Wörterbuchs folgen muss.

Das Argument zstd_dict ist eine Instanz von ZstdDict, wobei dict_content den rohen Wörterbuchinhalt enthält.

Das Argument samples (ein Iterable von bytes-Objekten) enthält Stichprobendaten zur Generierung des Zstandard-Wörterbuchs.

Das Argument dict_size, eine Ganzzahl, ist die maximale Größe (in Bytes), die das Zstandard-Wörterbuch haben soll. Siehe train_dict() für Vorschläge zur maximalen Wörterbuchgröße.

Das Argument level (eine Ganzzahl) ist die Komprimierungsstufe, die den Kompressoren übergeben werden soll, die dieses Wörterbuch verwenden. Die Wörterbuchinformationen variieren für jede Komprimierungsstufe, daher kann die Abstimmung auf die richtige Komprimierungsstufe die Komprimierung effizienter machen.

class compression.zstd.ZstdDict(dict_content, /, *, is_raw=False)

Ein Wrapper um Zstandard-Wörterbücher. Wörterbücher können verwendet werden, um die Komprimierung vieler kleiner Datenblöcke zu verbessern. Verwenden Sie train_dict(), wenn Sie ein neues Wörterbuch aus Stichprobendaten trainieren müssen.

Das Argument dict_content (ein bytes-ähnliches Objekt) sind die bereits trainierten Wörterbuchinformationen.

Das Argument is_raw, ein boolescher Wert, ist ein fortgeschrittener Parameter, der die Bedeutung von dict_content steuert. True bedeutet, dass dict_content ein Wörterbuch mit „rohem Inhalt“ ist, ohne Einschränkungen im Format. False bedeutet, dass dict_content ein gewöhnliches Zstandard-Wörterbuch ist, das aus Zstandard-Funktionen erstellt wurde, z. B. train_dict() oder das externe zstd CLI.

Beim Übergeben eines ZstdDict an eine Funktion können die Attribute as_digested_dict und as_undigested_dict steuern, wie das Wörterbuch geladen wird, indem sie als Argument zstd_dict übergeben werden, z. B. compress(data, zstd_dict=zd.as_digested_dict). Das Verdauen eines Wörterbuchs ist ein aufwendiger Vorgang, der beim Laden eines Zstandard-Wörterbuchs stattfindet. Wenn mehrere Komprimierungs- oder Dekomprimierungsaufrufe erfolgen, reduziert die Übergabe eines verdauten Wörterbuchs den Overhead beim Laden des Wörterbuchs.

Unterschied für Komprimierung

Verdautes Wörterbuch

Unverdautes Wörterbuch

Erweiterte Parameter des Kompressors, die durch die Parameter des Wörterbuchs überschrieben werden können

window_log, hash_log, chain_log, search_log, min_match, target_length, strategy, enable_long_distance_matching, ldm_hash_log, ldm_min_match, ldm_bucket_size_log, ldm_hash_rate_log und einige nicht öffentliche Parameter.

None

ZstdDict speichert das Wörterbuch intern im Cache

Ja. Es ist schneller, wenn ein verdautes Wörterbuch mit derselben Komprimierungsstufe erneut geladen wird.

Nein. Wenn Sie ein unverdautes Wörterbuch mehrmals laden möchten, sollten Sie ein Komprimierungsobjekt wiederverwenden.

Wenn ein ZstdDict ohne Attribut übergeben wird, wird standardmäßig ein unverdautes Wörterbuch beim Komprimieren und ein verdautes Wörterbuch übergeben, wenn es notwendig ist und standardmäßig beim Dekomprimieren übergeben wird.

dict_content

Der Inhalt des Zstandard-Wörterbuchs, ein bytes-Objekt. Es ist dasselbe wie das Argument dict_content in der Methode __init__. Es kann mit anderen Programmen verwendet werden, wie z. B. dem Befehlszeilenprogramm zstd.

dict_id

Bezeichner des Zstandard-Wörterbuchs, ein nicht negativer Ganzzahlwert.

Ungleich Null bedeutet, dass das Wörterbuch gewöhnlich ist, von Zstandard-Funktionen erstellt wurde und dem Zstandard-Format folgt.

0 bedeutet ein „Rohinhalt“-Wörterbuch, frei von Formatbeschränkungen, für fortgeschrittene Benutzer.

Hinweis

Die Bedeutung von 0 für ZstdDict.dict_id unterscheidet sich vom Attribut dictionary_id der Funktion get_frame_info().

as_digested_dict

Als verdautes Wörterbuch laden.

as_undigested_dict

Als unverdautes Wörterbuch laden.

Erweiterte Parametersteuerung

class compression.zstd.CompressionParameter

Ein IntEnum, das die erweiterten Komprimierungsparameterschlüssel enthält, die beim Komprimieren von Daten verwendet werden können.

Die Methode bounds() kann für jedes Attribut verwendet werden, um die gültigen Werte für diesen Parameter zu ermitteln.

Parameter sind optional; für jeden ausgelassenen Parameter wird sein Wert automatisch ausgewählt.

Beispiel für das Abrufen der unteren und oberen Grenze von compression_level

lower, upper = CompressionParameter.compression_level.bounds()

Beispiel für das Einstellen von window_log auf die maximale Größe

_lower, upper = CompressionParameter.window_log.bounds()
options = {CompressionParameter.window_log: upper}
compress(b'venezuelan beaver cheese', options=options)
bounds()

Gibt das Tupel von Ganzzahlgrenzen (lower, upper) eines Komprimierungsparameters zurück. Diese Methode sollte auf dem Attribut aufgerufen werden, dessen Grenzen Sie ermitteln möchten. Um beispielsweise die gültigen Werte für compression_level zu erhalten, kann man das Ergebnis von CompressionParameter.compression_level.bounds() prüfen.

Sowohl die untere als auch die obere Grenze sind einschließend.

compression_level

Eine High-Level-Methode zur Einstellung anderer Komprimierungsparameter, die die Geschwindigkeit und das Verhältnis der Datenkomprimierung beeinflussen.

Reguläre Komprimierungsstufen sind größer als 0. Werte größer als 20 gelten als „Ultra“-Komprimierung und erfordern mehr Speicher als andere Stufen. Negative Werte können verwendet werden, um eine schnellere Komprimierung gegen schlechtere Komprimierungsverhältnisse einzutauschen.

Wenn die Stufe auf Null gesetzt wird, wird COMPRESSION_LEVEL_DEFAULT verwendet.

window_log

Maximale zulässige Rückverweisdistanz, die der Kompressor beim Komprimieren von Daten verwenden kann, ausgedrückt als Zweierpotenz, 1 << window_log Bytes. Dieser Parameter beeinflusst stark den Speicherverbrauch der Komprimierung. Höhere Werte erfordern mehr Speicher, erzielen aber bessere Komprimierungswerte.

Ein Wert von Null bewirkt, dass der Wert automatisch ausgewählt wird.

hash_log

Größe der initialen Sondentabelle, als Zweierpotenz. Der resultierende Speicherverbrauch beträgt 1 << (hash_log+2) Bytes. Größere Tabellen verbessern das Komprimierungsverhältnis von Strategien <= dfast und verbessern die Komprimierungsgeschwindigkeit von Strategien > dfast.

Ein Wert von Null bewirkt, dass der Wert automatisch ausgewählt wird.

chain_log

Größe der Mehrfachsondentabelle, als Zweierpotenz. Der resultierende Speicherverbrauch beträgt 1 << (chain_log+2) Bytes. Größere Tabellen führen zu besserer und langsamerer Komprimierung. Dieser Parameter hat keine Auswirkung auf die Strategie fast. Er ist dennoch nützlich bei der Verwendung der Strategie dfast, in diesem Fall definiert er eine sekundäre Sondentabelle.

Ein Wert von Null bewirkt, dass der Wert automatisch ausgewählt wird.

search_log

Anzahl der Suchversuche, als Zweierpotenz. Mehr Versuche führen zu besserer und langsamerer Komprimierung. Dieser Parameter ist für die Strategien fast und dfast nutzlos.

Ein Wert von Null bewirkt, dass der Wert automatisch ausgewählt wird.

min_match

Minimale Größe der gesuchten Übereinstimmungen. Größere Werte erhöhen die Komprimierungs- und Dekomprimierungsgeschwindigkeit, verringern aber das Verhältnis. Beachten Sie, dass Zstandard immer noch Übereinstimmungen kleinerer Größe finden kann, es passt lediglich seinen Suchalgorithmus an, um nach dieser Größe und größer zu suchen. Für alle Strategien < btopt ist das effektive Minimum 4; für alle Strategien > fast ist das effektive Maximum 6.

Ein Wert von Null bewirkt, dass der Wert automatisch ausgewählt wird.

target_length

Der Einfluss dieses Feldes hängt von der ausgewählten Strategy ab.

Für die Strategien btopt, btultra und btultra2 ist der Wert die Länge einer Übereinstimmung, die als „gut genug“ betrachtet wird, um die Suche zu beenden. Größere Werte verbessern die Komprimierungsverhältnisse, verlangsamen aber die Komprimierung.

Für die Strategie fast ist dies der Abstand zwischen den Stichproben von Übereinstimmungen. Größere Werte machen die Komprimierung schneller, aber mit einem schlechteren Komprimierungsverhältnis.

Ein Wert von Null bewirkt, dass der Wert automatisch ausgewählt wird.

strategy

Je höher der Wert der ausgewählten Strategie, desto komplexer ist die von zstd verwendete Komprimierungstechnik, was zu höheren Komprimierungsverhältnissen, aber langsamerer Komprimierung führt.

Siehe auch

Strategie

enable_long_distance_matching

Langdistanzabgleich kann verwendet werden, um die Komprimierung großer Eingaben zu verbessern, indem große Übereinstimmungen in größeren Entfernungen gefunden werden. Dies erhöht den Speicherverbrauch und die Fenstergröße.

True oder 1 aktivieren den Langdistanzabgleich, während False oder 0 ihn deaktivieren.

Die Aktivierung dieses Parameters erhöht den Standardwert von window_log auf 128 MiB, es sei denn, er ist ausdrücklich auf einen anderen Wert gesetzt. Diese Einstellung ist standardmäßig aktiviert, wenn window_log >= 128 MiB ist und die Komprimierungsstrategie >= btopt (Komprimierungsstufe 16+) ist.

ldm_hash_log

Größe der Tabelle für den Langdistanzabgleich, als Zweierpotenz. Größere Werte erhöhen den Speicherverbrauch und das Komprimierungsverhältnis, verringern aber die Komprimierungsgeschwindigkeit.

Ein Wert von Null bewirkt, dass der Wert automatisch ausgewählt wird.

ldm_min_match

Minimale Übereinstimmungsgröße für den Langdistanzabgleicher. Größere oder zu kleine Werte können oft das Komprimierungsverhältnis verringern.

Ein Wert von Null bewirkt, dass der Wert automatisch ausgewählt wird.

ldm_bucket_size_log

Logarithmische Größe jedes Buckets in der Hash-Tabelle des Langdistanzabgleichers zur Kollisionsauflösung. Größere Werte verbessern die Kollisionsauflösung, verringern aber die Komprimierungsgeschwindigkeit.

Ein Wert von Null bewirkt, dass der Wert automatisch ausgewählt wird.

ldm_hash_rate_log

Häufigkeit des Einfügens/Abfragens von Einträgen in die Hash-Tabelle des Langdistanzabgleichers. Größere Werte verbessern die Komprimierungsgeschwindigkeit. Eine starke Abweichung vom Standardwert führt wahrscheinlich zu einer Verringerung des Komprimierungsverhältnisses.

Ein Wert von Null bewirkt, dass der Wert automatisch ausgewählt wird.

content_size_flag

Schreibt die Größe der zu komprimierenden Daten in den Zstandard-Frame-Header, wenn diese vor der Komprimierung bekannt ist.

Dieses Flag wird nur unter den folgenden Bedingungen wirksam

Alle anderen Komprimierungsaufrufe schreiben die Größeninformationen möglicherweise nicht in den Frame-Header.

True oder 1 aktivieren das Content-Size-Flag, während False oder 0 es deaktivieren.

checksum_flag

Eine Vier-Byte-Prüfsumme mit XXHash64 des unkomprimierten Inhalts wird am Ende jedes Frames geschrieben. Der Dekomprimierungscode von Zstandard überprüft die Prüfsumme. Bei einer Nichtübereinstimmung wird eine Ausnahme vom Typ ZstdError ausgelöst.

True oder 1 aktivieren die Generierung von Prüfsummen, während False oder 0 sie deaktivieren.

dict_id_flag

Beim Komprimieren mit einem ZstdDict wird die ID des Wörterbuchs in den Frame-Header geschrieben.

True oder 1 aktivieren das Speichern der Wörterbuch-ID, während False oder 0 es deaktivieren.

nb_workers

Wählt aus, wie viele Threads parallel zur Komprimierung gestartet werden. Wenn nb_workers > 0 ist, wird die Multithread-Komprimierung aktiviert; ein Wert von 1 bedeutet „Ein-Thread-Multithread-Modus“. Mehr Worker verbessern die Geschwindigkeit, erhöhen aber auch den Speicherverbrauch und verringern leicht das Komprimierungsverhältnis.

Ein Wert von Null deaktiviert Multithreading.

job_size

Größe eines Komprimierungsjobs in Bytes. Dieser Wert wird nur erzwungen, wenn nb_workers >= 1 ist. Jeder Komprimierungsjob wird parallel abgeschlossen, daher kann dieser Wert indirekt die Anzahl der aktiven Threads beeinflussen.

Ein Wert von Null bewirkt, dass der Wert automatisch ausgewählt wird.

overlap_log

Legt fest, wie viele Daten aus früheren Jobs (Threads) für neue Jobs geladen werden, um vom Look-Behind-Fenster während der Komprimierung verwendet zu werden. Dieser Wert wird nur verwendet, wenn nb_workers >= 1 ist. Akzeptable Werte reichen von 0 bis 9.

  • 0 bedeutet dynamische Einstellung der Überlappungsmenge

  • 1 bedeutet keine Überlappung

  • 9 bedeutet Verwendung eines vollständigen Fenstergrößenbereichs aus dem vorherigen Job

Jeder Schritt halbiert/verdoppelt die Überlappungsgröße. „8“ bedeutet eine Überlappung von window_size/2, „7“ bedeutet eine Überlappung von window_size/4 usw.

class compression.zstd.DecompressionParameter

Ein IntEnum, das die erweiterten Dekomprimierungsparameterschlüssel enthält, die beim Dekomprimieren von Daten verwendet werden können. Parameter sind optional; für jeden ausgelassenen Parameter wird sein Wert automatisch ausgewählt.

Die Methode bounds() kann für jedes Attribut verwendet werden, um die gültigen Werte für diesen Parameter zu ermitteln.

Beispiel für das Einstellen von window_log_max auf die maximale Größe

data = compress(b'Some very long buffer of bytes...')

_lower, upper = DecompressionParameter.window_log_max.bounds()

options = {DecompressionParameter.window_log_max: upper}
decompress(data, options=options)
bounds()

Gibt das Tupel von Ganzzahlgrenzen (lower, upper) eines Dekomprimierungsparameters zurück. Diese Methode sollte auf dem Attribut aufgerufen werden, dessen Grenzen Sie ermitteln möchten.

Sowohl die untere als auch die obere Grenze sind einschließend.

window_log_max

Der Zweierlogarithmus der maximalen Fenstergröße, die während der Dekompression verwendet wird. Dies kann nützlich sein, um den Speicherverbrauch bei der Dekompression von Daten zu begrenzen. Eine größere maximale Fenstergröße führt zu einer schnelleren Dekompression.

Ein Wert von Null bewirkt, dass der Wert automatisch ausgewählt wird.

class compression.zstd.Strategy

Ein IntEnum, das Komprimierungsstrategien enthält. Höher nummerierte Strategien entsprechen einer komplexeren und langsameren Komprimierung.

Hinweis

Die Werte der Attribute von Strategy sind nicht notwendigerweise über zstd-Versionen hinweg stabil. Nur die Reihenfolge der Attribute kann herangezogen werden. Die Attribute sind unten in Reihenfolge aufgelistet.

Die folgenden Strategien sind verfügbar

fast
dfast
greedy
lazy
lazy2
btlazy2
btopt
btultra
btultra2

Sonstiges

compression.zstd.get_frame_info(frame_buffer)

Ruft ein FrameInfo-Objekt ab, das Metadaten über einen Zstandard-Frame enthält. Frames enthalten Metadaten, die sich auf die von ihnen gehaltenen komprimierten Daten beziehen.

class compression.zstd.FrameInfo

Metadaten zu einem Zstandard-Frame.

decompressed_size

Die Größe des dekomprimierten Inhalts des Frames.

dictionary_id

Eine Ganzzahl, die die Zstandard-Dictionary-ID darstellt, die für die Dekompression des Frames benötigt wird. 0 bedeutet, dass die Dictionary-ID nicht im Frame-Header aufgezeichnet wurde. Dies kann bedeuten, dass kein Zstandard-Dictionary benötigt wird oder dass die ID eines erforderlichen Dictionaries nicht aufgezeichnet wurde.

compression.zstd.COMPRESSION_LEVEL_DEFAULT

Die Standardkomprimierungsstufe für Zstandard: 3.

compression.zstd.zstd_version_info

Versionsnummer der Laufzeit-zstd-Bibliothek als Tupel von Ganzzahlen (major, minor, release).

Beispiele

Lesen einer komprimierten Datei

from compression import zstd

with zstd.open("file.zst") as f:
    file_content = f.read()

Erstellen einer komprimierten Datei

from compression import zstd

data = b"Insert Data Here"
with zstd.open("file.zst", "w") as f:
    f.write(data)

Daten im Speicher komprimieren

from compression import zstd

data_in = b"Insert Data Here"
data_out = zstd.compress(data_in)

Inkrementelle Komprimierung

from compression import zstd

comp = zstd.ZstdCompressor()
out1 = comp.compress(b"Some data\n")
out2 = comp.compress(b"Another piece of data\n")
out3 = comp.compress(b"Even more data\n")
out4 = comp.flush()
# Concatenate all the partial results:
result = b"".join([out1, out2, out3, out4])

Schreiben komprimierter Daten in eine bereits geöffnete Datei

from compression import zstd

with open("myfile", "wb") as f:
    f.write(b"This data will not be compressed\n")
    with zstd.open(f, "w") as zstf:
        zstf.write(b"This *will* be compressed\n")
    f.write(b"Not compressed\n")

Erstellen einer komprimierten Datei mit Komprimierungsparametern

from compression import zstd

options = {
   zstd.CompressionParameter.checksum_flag: 1
}
with zstd.open("file.zst", "w", options=options) as f:
    f.write(b"Mind if I squeeze in?")