bz2 — Unterstützung für bzip2-Kompression

Quellcode: Lib/bz2.py

Dieses Modul bietet eine umfassende Schnittstelle zum Komprimieren und Dekomprimieren von Daten unter Verwendung des bzip2-Kompression-Algorithmus.

Das Modul bz2 enthält

(De-)Kompression von Dateien

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

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

Wie beim Konstruktor für BZ2File kann das Argument filename ein tatsächlicher Dateiname (ein str oder bytes Objekt) oder ein vorhandenes Dateiobjekt sein, aus dem gelesen oder in das geschrieben werden soll.

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

Das Argument compresslevel ist eine Ganzzahl von 1 bis 9, wie für den Konstruktor von BZ2File.

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

Für den Textmodus wird ein BZ2File-Objekt erstellt und in eine io.TextIOWrapper-Instanz mit der angegebenen Kodierung, Fehlerbehandlung und Zeilenende(n) eingewickelt.

Hinzugefügt in Version 3.3.

Geändert in Version 3.4: Der Modus 'x' (exklusives Erstellen) wurde hinzugefügt.

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

class bz2.BZ2File(filename, mode='r', *, compresslevel=9)

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

Wenn filename ein str oder bytes Objekt ist, wird die benannte Datei direkt geöffnet. Andernfalls muss filename ein Dateiobjekt sein, das zum Lesen oder Schreiben der komprimierten Daten verwendet wird.

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

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

Wenn mode 'w' oder 'a' ist, kann compresslevel eine Ganzzahl zwischen 1 und 9 sein, die den Kompressionsgrad angibt: 1 ergibt die geringste Kompression und 9 (Standard) die höchste Kompression.

Wenn mode 'r' ist, kann die Eingabedatei die Verkettung mehrerer komprimierter Streams sein.

BZ2File stellt alle von io.BufferedIOBase definierten Member bereit, mit Ausnahme von detach() und truncate(). Iteration und die with-Anweisung werden unterstützt.

BZ2File bietet außerdem die folgenden Methoden und Attribute

peek([n])

Gibt gepufferte Daten zurück, ohne die Dateiposition zu verändern. Es werden mindestens ein Byte Daten zurückgegeben (sofern nicht am EOF). Die genaue Anzahl der zurückgegebenen Bytes ist nicht spezifiziert.

Hinweis

Während der Aufruf von peek() die Dateiposition der BZ2File nicht verändert, kann sie die Position des zugrundeliegenden Dateiobjekts verändern (z. B. wenn die BZ2File durch Übergabe eines Dateiobjekts für filename konstruiert wurde).

Hinzugefügt in Version 3.3.

fileno()

Gibt den Dateideskriptor der zugrundeliegenden Datei zurück.

Hinzugefügt in Version 3.3.

readable()

Gibt zurück, ob die Datei zum Lesen geöffnet wurde.

Hinzugefügt in Version 3.3.

seekable()

Gibt zurück, ob die Datei das Suchen unterstützt.

Hinzugefügt in Version 3.3.

writable()

Gibt zurück, ob die Datei zum Schreiben geöffnet wurde.

Hinzugefügt in Version 3.3.

read1(size=-1)

Liest bis zu size unkomprimierte Bytes und versucht dabei, mehrere Lesevorgänge vom zugrundeliegenden Stream zu vermeiden. Liest bis zu einem Buffer-Wert an Daten, wenn size negativ ist.

Gibt b'' zurück, wenn die Datei EOF erreicht hat.

Hinzugefügt in Version 3.3.

readinto(b)

Liest Bytes in b.

Gibt die Anzahl der gelesenen Bytes zurück (0 für EOF).

Hinzugefügt in Version 3.3.

mode

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

Hinzugefügt in Version 3.13.

name

Der bzip2-Dateiname. Äquivalent zum Attribut name des zugrundeliegenden Dateiobjekts.

Hinzugefügt in Version 3.13.

Geändert in Version 3.1: Die Unterstützung für die with-Anweisung wurde hinzugefügt.

Geändert in Version 3.3: Die Unterstützung dafür, dass filename ein Dateiobjekt anstelle eines tatsächlichen Dateinamens ist, wurde hinzugefügt.

Der Modus 'a' (Anhängen) wurde zusammen mit der Unterstützung für das Lesen von Mehrstrom-Dateien hinzugefügt.

Geändert in Version 3.4: Der Modus 'x' (exklusives Erstellen) wurde hinzugefügt.

Geändert in Version 3.5: Die Methode read() akzeptiert jetzt ein Argument von None.

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

Geändert in Version 3.9: Der Parameter buffering wurde entfernt. Er wurde seit Python 3.0 ignoriert und als veraltet markiert. Übergeben Sie ein geöffnetes Dateiobjekt, um zu steuern, wie die Datei geöffnet wird.

Der Parameter compresslevel wurde zu „keyword-only“.

Geändert in Version 3.10: Diese Klasse ist im Hinblick auf mehrere gleichzeitige Leser oder Schreiber nicht threadsicher, genau wie ihre äquivalenten Klassen in gzip und lzma schon immer waren.

Inkrementelle (De-)Kompression

class bz2.BZ2Compressor(compresslevel=9)

Erzeugt ein neues Kompressorobjekt. Dieses Objekt kann zur inkrementellen Kompression von Daten verwendet werden. Für einmalige Kompression verwenden Sie stattdessen die Funktion compress().

compresslevel muss, falls angegeben, eine Ganzzahl zwischen 1 und 9 sein. Der Standardwert ist 9.

compress(data)

Übergibt Daten an das Kompressorobjekt. Gibt einen Block komprimierter Daten zurück, wenn möglich, oder eine leere Bytezeichenkette andernfalls.

Wenn Sie die Übergabe von Daten an den Kompressor abgeschlossen haben, rufen Sie die Methode flush() auf, um den Kompressionsvorgang abzuschließen.

flush()

Schließt den Kompressionsvorgang ab. Gibt die noch in den internen Puffern verbleibenden komprimierten Daten zurück.

Das Kompressorobjekt darf nach dem Aufruf dieser Methode nicht mehr verwendet werden.

class bz2.BZ2Decompressor

Erzeugt ein neues Dekompressorobjekt. Dieses Objekt kann zur inkrementellen Dekompression von Daten verwendet werden. Für einmalige Dekompression verwenden Sie stattdessen die Funktion decompress().

Hinweis

Diese Klasse behandelt Eingaben, die mehrere komprimierte Streams enthalten, nicht transparent wie decompress() und BZ2File. Wenn Sie eine Mehrstrom-Eingabe mit BZ2Decompressor dekomprimieren müssen, müssen Sie für jeden Stream einen neuen Dekompressor verwenden.

decompress(data, max_length=-1)

Dekomprimiert data (ein byteähnliches Objekt) und gibt unkomprimierte Daten als Bytes zurück. Einige von data können intern gepuffert werden, für spätere Aufrufe von decompress(). Die zurückgegebenen Daten sollten mit der Ausgabe früherer Aufrufe von decompress() verkettet werden.

Wenn max_length nicht negativ ist, werden maximal max_length Bytes dekomprimierter Daten zurückgegeben. 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 diese weniger als max_length Bytes waren oder weil max_length negativ war), wird das Attribut needs_input auf True gesetzt.

Der Versuch, Daten nach Erreichen des Endes des Streams zu dekomprimieren, löst einen EOFError aus. Alle nach dem Ende des Streams gefundenen Daten werden ignoriert und im Attribut unused_data gespeichert.

Geändert in Version 3.5: Der Parameter max_length wurde hinzugefügt.

eof

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

Hinzugefügt in Version 3.3.

unused_data

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

Wenn auf dieses Attribut zugegriffen wird, bevor das Ende des Streams erreicht wurde, ist sein Wert b''.

needs_input

False, wenn die Methode decompress() weitere dekomprimierte Daten bereitstellen kann, bevor sie neuen unkomprimierten Input benötigt.

Hinzugefügt in Version 3.5.

Einmalige (De-)Kompression

bz2.compress(data, compresslevel=9)

Komprimiert data, ein byteähnliches Objekt.

compresslevel muss, falls angegeben, eine Ganzzahl zwischen 1 und 9 sein. Der Standardwert ist 9.

Für inkrementelle Kompression verwenden Sie stattdessen eine BZ2Compressor.

bz2.decompress(data)

Dekomprimiert data, ein byteähnliches Objekt.

Wenn data die Verkettung mehrerer komprimierter Streams ist, werden alle Streams dekomprimiert.

Für inkrementelle Dekompression verwenden Sie stattdessen eine BZ2Decompressor.

Geändert in Version 3.3: Unterstützung für Mehrstrom-Eingaben wurde hinzugefügt.

Anwendungsbeispiele

Unten finden Sie einige Beispiele für die typische Verwendung des Moduls bz2.

Verwendung von compress() und decompress() zur Demonstration einer Rundum-Kompression

>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> c = bz2.compress(data)
>>> len(data) / len(c)  # Data compression ratio
1.513595166163142
>>> d = bz2.decompress(c)
>>> data == d  # Check equality to original object after round-trip
True

Verwendung von BZ2Compressor für inkrementelle Kompression

>>> import bz2
>>> def gen_data(chunks=10, chunksize=1000):
...     """Yield incremental blocks of chunksize bytes."""
...     for _ in range(chunks):
...         yield b"z" * chunksize
...
>>> comp = bz2.BZ2Compressor()
>>> out = b""
>>> for chunk in gen_data():
...     # Provide data to the compressor object
...     out = out + comp.compress(chunk)
...
>>> # Finish the compression process.  Call this once you have
>>> # finished providing data to the compressor.
>>> out = out + comp.flush()

Das obige Beispiel verwendet einen sehr „nicht-zufälligen“ Datenstrom (einen Strom von b"z"-Chunks). Zufällige Daten komprimieren sich schlecht, während geordnete, repetitive Daten normalerweise ein hohes Kompressionsverhältnis ergeben.

Schreiben und Lesen einer bzip2-komprimierten Datei im Binärmodus

>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> with bz2.open("myfile.bz2", "wb") as f:
...     # Write compressed data to file
...     unused = f.write(data)
...
>>> with bz2.open("myfile.bz2", "rb") as f:
...     # Decompress data from file
...     content = f.read()
...
>>> content == data  # Check equality to original object after round-trip
True