bz2 — Stöd för bzip2-komprimering

Källkod: Lib/bz2.py

Denna modul ger ett omfattande gränssnitt för komprimering och dekomprimering av data med hjälp av komprimeringsalgoritmen bzip2.

Modulen bz2 innehåller:

(De)komprimering av filer

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

Öppna en bzip2-komprimerad fil i binär- eller textläge och returnera ett file object.

Precis som i konstruktören för BZ2File kan argumentet filnamn vara ett faktiskt filnamn (ett str- eller bytes-objekt) eller ett befintligt filobjekt att läsa från eller skriva till.

Argumentet mode kan vara något av 'r', 'rb', 'w', 'wb', 'x', 'xb', 'a' eller 'ab' för binärt läge, eller 'rt', 'wt', 'xt' eller 'at' för textläge. Standardvärdet är 'rb'.

Argumentet compresslevel är ett heltal från 1 till 9, som för konstruktören BZ2File.

För binärt läge är denna funktion likvärdig med BZ2File-konstruktören: BZ2File(filnamn, läge, komprimeringsnivå=komprimeringsnivå). I detta fall får argumenten encoding, errors och newline inte anges.

För textläge skapas ett BZ2File-objekt och omsluts av en io.TextIOWrapper-instans med angiven kodning, felhanteringsbeteende och radavslutning(ar).

Tillagd i version 3.3.

Ändrad i version 3.4: Läget 'x' (exklusivt skapande) lades till.

Ändrad i version 3.6: Accepterar en path-like object.

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

Öppna en bzip2-komprimerad fil i binärt läge.

Om filnamn är ett str- eller bytes-objekt öppnas den namngivna filen direkt. Annars bör filnamn vara ett file object, som kommer att användas för att läsa eller skriva komprimerade data.

Argumentet mode kan vara antingen 'r' för läsning (standard), 'w' för överskrivning, 'x' för exklusivt skapande eller 'a' för tillägg. Dessa kan på motsvarande sätt anges som 'rb', 'wb', 'xb' respektive 'ab'.

Om filnamn är ett filobjekt (snarare än ett faktiskt filnamn), trunkeras inte filen i ett läge med 'w', utan det motsvarar istället 'a'.

Om mode är 'w' eller 'a' kan compresslevel vara ett heltal mellan 1 och 9 som anger komprimeringsnivån: 1 ger den minsta komprimeringen och 9 (standard) ger den största komprimeringen.

Om mode är 'r' kan indatafilen vara en sammankoppling av flera komprimerade strömmar.

BZ2File tillhandahåller alla medlemmar som specificeras av io.BufferedIOBase, förutom detach() och truncate(). Iteration och with-satsen stöds.

BZ2File tillhandahåller även följande metoder och attribut:

peek([n])

Returnerar buffrade data utan att flytta fram filpositionen. Minst en byte data kommer att returneras (om inte vid EOF). Det exakta antalet byte som returneras är ospecificerat.

Anteckning

Även om anrop av peek() inte ändrar filpositionen för BZ2File, kan det ändra positionen för det underliggande filobjektet (t.ex. om BZ2File konstruerades genom att skicka ett filobjekt för filnamn).

Tillagd i version 3.3.

fileno()

Returnerar fildeskriptorn för den underliggande filen.

Tillagd i version 3.3.

readable()

Returnerar om filen har öppnats för läsning.

Tillagd i version 3.3.

seekable()

Returnerar om filen stöder sökning.

Tillagd i version 3.3.

writable()

Returnerar om filen har öppnats för skrivning.

Tillagd i version 3.3.

read1(size=-1)

Läser upp till storlek okomprimerade byte, samtidigt som den försöker undvika att göra flera läsningar från den underliggande strömmen. Läser upp till en bufferts värde av data om storlek är negativ.

Returnerar b'' om filen är vid EOF.

Tillagd i version 3.3.

readinto(b)

Läs in bytes i b.

Returnerar antalet lästa byte (0 för EOF).

Tillagd i version 3.3.

mode

'rb' för läsning och 'wb' för skrivning.

Tillagd i version 3.13.

name

Namnet på bzip2-filen. Motsvarar attributet name för det underliggande file object.

Tillagd i version 3.13.

Ändrad i version 3.1: Stöd för with statement har lagts till.

Ändrad i version 3.3: Stöd har lagts till för filnamn som är ett filobjekt istället för ett faktiskt filnamn.

Läget 'a (append) har lagts till, liksom stöd för läsning av filer med flera strömmar.

Ändrad i version 3.4: Läget 'x' (exklusivt skapande) lades till.

Ändrad i version 3.5: Metoden read() accepterar nu ett argument på None.

Ändrad i version 3.6: Accepterar en path-like object.

Ändrad i version 3.9: Parametern buffering har tagits bort. Den ignorerades och föråldrades sedan Python 3.0. Skicka ett open file object för att styra hur filen öppnas.

Parametern compresslevel blev nyckelordsbaserad.

Ändrad i version 3.10: Den här klassen är trådosäker när flera läsare eller skrivare är aktiva samtidigt, precis som motsvarande klasser i gzip och lzma alltid har varit.

Inkrementell (de)komprimering

class bz2.BZ2Compressor(compresslevel=9)

Skapa ett nytt kompressorobjekt. Detta objekt kan användas för att komprimera data stegvis. För komprimering i ett svep, använd funktionen compress() istället.

compresslevel, om det anges, måste vara ett heltal mellan 1 och 9. Standardvärdet är 9.

compress(data)

Tillhandahåller data till kompressorobjektet. Returnerar en bit komprimerad data om möjligt, eller en tom byte-sträng annars.

När du är klar med att leverera data till kompressorn anropar du metoden flush() för att avsluta komprimeringsprocessen.

flush()

Avslutar komprimeringsprocessen. Returnerar de komprimerade data som finns kvar i de interna buffertarna.

Kompressorobjektet får inte användas efter att denna metod har anropats.

class bz2.BZ2Decompressor

Skapa ett nytt dekomprimeringsobjekt. Detta objekt kan användas för att dekomprimera data stegvis. För komprimering på en gång, använd funktionen decompress() istället.

Anteckning

Den här klassen hanterar inte på ett transparent sätt indata som innehåller flera komprimerade strömmar, till skillnad från decompress() och BZ2File. Om du behöver dekomprimera en inmatning med flera strömmar med BZ2Decompressor, måste du använda en ny dekompressor för varje ström.

decompress(data, max_length=-1)

Dekomprimerar data (ett bytesliknande objekt) och returnerar okomprimerad data som bytes. En del av data kan buffras internt, för användning i senare anrop till decompress(). Den returnerade datan bör sammanfogas med resultatet från eventuella tidigare anrop till decompress().

Om max_length är icke-negativ, returneras högst max_length byte av dekomprimerade data. Om denna gräns nås och ytterligare utdata kan produceras, kommer attributet needs_input att sättas till False. I detta fall kan nästa anrop till decompress() ge data som b'' för att få mer av utdata.

Om alla indata dekomprimerades och returnerades (antingen för att de var mindre än max_length bytes eller för att max_length var negativ), kommer attributet needs_input att sättas till True.

Försök att dekomprimera data efter att slutet på strömmen har nåtts ger upphov till ett EOFError. Alla data som hittas efter slutet av strömmen ignoreras och sparas i attributet unused_data.

Ändrad i version 3.5: Parametern max_length har lagts till.

eof

True om markören för slutet av flödet har nåtts.

Tillagd i version 3.3.

unused_data

Data som hittas efter slutet av den komprimerade strömmen.

Om detta attribut används innan slutet av flödet har nåtts, kommer dess värde att vara b''.

needs_input

False om metoden decompress`() kan tillhandahålla mer dekomprimerad data innan den kräver ny okomprimerad inmatning.

Tillagd i version 3.5.

One-shot (de)komprimering

bz2.compress(data, compresslevel=9)

Komprimera data, ett bytesliknande objekt.

compresslevel, om det anges, måste vara ett heltal mellan 1 och 9. Standardvärdet är 9.

För inkrementell komprimering, använd istället en BZ2Compressor.

bz2.decompress(data)

Dekomprimera data, ett bytesliknande objekt.

Om data är en sammankoppling av flera komprimerade strömmar, dekomprimera alla strömmar.

För inkrementell dekomprimering, använd istället en BZ2Decompressor.

Ändrad i version 3.3: Stöd för inmatning av flera strömmar har lagts till.

Exempel på användning

Nedan följer några exempel på typisk användning av modulen bz2.

Använda compress() och decompress() för att demonstrera round-trip-komprimering:

>>> 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

Använder BZ2Compressor för stegvis komprimering:

>>> 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()

I exemplet ovan används en mycket ”icke-slumpmässig” dataström (en ström av ”b”z”-bitar). Slumpmässiga data tenderar att komprimeras dåligt, medan ordnade, repetitiva data vanligtvis ger ett högt komprimeringsförhållande.

Skriva och läsa en bzip2-komprimerad fil i binärt läge:

>>> 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