lzma — Komprimering med hjälp av LZMA-algoritmen

Tillagd i version 3.3.

Källkod: Lib/lzma.py


Denna modul innehåller klasser och bekvämlighetsfunktioner för komprimering och dekomprimering av data med hjälp av LZMA-komprimeringsalgoritmen. Dessutom ingår ett filgränssnitt som stöder filformaten .xz och .lzma som används av verktyget xz, samt råkomprimerade strömmar.

Gränssnittet som tillhandahålls av denna modul är mycket likt det i modulen bz2. Observera att LZMAFile och bz2.BZ2File är inte trådsäkra, så om du behöver använda en enda LZMAFile-instans från flera trådar, är det nödvändigt att skydda den med ett lås.

exception lzma.LZMAError

Detta undantag uppstår när ett fel inträffar under komprimering eller dekomprimering, eller under initiering av kompressor/dekompressortillståndet.

Läsa och skriva komprimerade filer

lzma.open(filename, mode='rb', *, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)

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

Argumentet filnamn kan antingen vara ett faktiskt filnamn (givet som ett str, bytes eller path-like-objekt), i vilket fall den namngivna filen öppnas, 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".

När en fil öppnas för läsning har argumenten format och filters samma innebörd som för LZMADecompressor. I det här fallet ska argumenten check och preset inte användas.

När en fil öppnas för skrivning har argumenten format, check, preset och filters samma innebörd som för LZMACompressor.

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

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

Ändrad i version 3.4: Lagt till stöd för lägena "x", "xb" och "xt".

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

class lzma.LZMAFile(filename=None, mode='r', *, format=None, check=-1, preset=None, filters=None)

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

En LZMAFile kan omsluta ett redan öppet file object, eller arbeta direkt på en namngiven fil. Argumentet filnamn anger antingen filobjektet som ska omslutas eller namnet på filen som ska öppnas (som ett str, bytes eller path-like-objekt). När ett befintligt filobjekt paketeras kommer den paketerade filen inte att stängas när LZMAFile stängs.

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 läget "w", utan motsvarar i stället "a".

När du öppnar en fil för läsning kan inmatningsfilen vara en sammankoppling av flera separata komprimerade strömmar. Dessa avkodas på ett transparent sätt som en enda logisk ström.

När en fil öppnas för läsning har argumenten format och filters samma innebörd som för LZMADecompressor. I det här fallet ska argumenten check och preset inte användas.

När en fil öppnas för skrivning har argumenten format, check, preset och filters samma innebörd som för LZMACompressor.

LZMAFile stöder alla medlemmar som specificeras av io.BufferedIOBase, förutom detach() och truncate(). Iteration och with-satsen stöds.

Följande metod och attribut tillhandahålls också:

peek(size=-1)

Returnerar buffrade data utan att flytta fram filpositionen. Minst en byte data kommer att returneras, såvida inte EOF har uppnåtts. Det exakta antalet bytes som returneras är ospecificerat (argumentet size ignoreras).

Anteckning

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

mode

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

Tillagd i version 3.13.

name

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

Tillagd i version 3.13.

Ändrad i version 3.4: Lagt till stöd för lägena "x" och "xb".

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

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

Komprimering och dekomprimering av data i minnet

class lzma.LZMACompressor(format=FORMAT_XZ, check=-1, preset=None, filters=None)

Skapa ett kompressorobjekt som kan användas för att komprimera data stegvis.

För ett bekvämare sätt att komprimera en enda bit data, se compress().

Argumentet format anger vilket containerformat som ska användas. Möjliga värden är:

  • FORMAT_XZ: Containerformatet .xz.

    Detta är standardformatet.

  • FORMAT_ALONE: Det äldre containerformatet .lzma.

    Detta format är mer begränsat än .xz - det stöder inte integritetskontroller eller flera filter.

  • FORMAT_RAW: En rå dataström som inte använder något containerformat.

    Den här formatspecificeraren stöder inte integritetskontroller och kräver att du alltid anger en anpassad filterkedja (för både komprimering och dekomprimering). Dessutom kan data som komprimerats på detta sätt inte dekomprimeras med FORMAT_AUTO (se LZMADecompressor).

Argumentet check anger vilken typ av integritetskontroll som ska inkluderas i de komprimerade data. Denna kontroll används vid dekomprimering för att säkerställa att data inte har korrumperats. Möjliga värden är:

  • CHECK_NONE: Ingen integritetskontroll. Detta är standardvärdet (och det enda godtagbara värdet) för FORMAT_ALONE och FORMAT_RAW.

  • CHECK_CRC32: 32-bitars kontroll av cyklisk redundans.

  • CHECK_CRC64: 64-bitars kontroll av cyklisk redundans. Detta är standardinställningen för FORMAT_XZ.

  • CHECK_SHA256: 256-bitars säker hashalgoritm.

Om den angivna kontrollen inte stöds, genereras ett LZMAError.

Komprimeringsinställningarna kan anges antingen som en förinställd komprimeringsnivå (med argumentet preset) eller i detalj som en anpassad filterkedja (med argumentet filters).

Argumentet preset (om det anges) bör vara ett heltal mellan 0 och 9 (inklusive), eventuellt OR-at med konstanten PRESET_EXTREME. Om varken preset eller filters anges är standardbeteendet att använda PRESET_DEFAULT (förinställningsnivå 6). Högre förinställningar ger mindre utdata, men gör komprimeringsprocessen långsammare.

Anteckning

Förutom att vara mer CPU-intensiv kräver komprimering med högre förinställningar också mycket mer minne (och producerar utdata som behöver mer minne för att dekomprimeras). Med förinställningen 9 till exempel, kan overhead för ett LZMACompressor-objekt vara så högt som 800 MiB. Av denna anledning är det i allmänhet bäst att hålla sig till standardinställningen.

Argumentet filters (om det anges) bör vara en specifikation av en filterkedja. Se Ange anpassade filterkedjor för detaljer.

compress(data)

Komprimerar data (ett bytes-objekt) och returnerar ett bytes-objekt som innehåller komprimerade data för åtminstone en del av indata. En del av data kan buffras internt, för användning i senare anrop till compress() och flush(). De returnerade data bör sammankopplas med utdata från eventuella tidigare anrop till compress().

flush()

Avslutar komprimeringsprocessen och returnerar ett bytes-objekt som innehåller all data som lagrats i kompressorns interna buffertar.

Kompressorn kan inte användas efter att denna metod har anropats.

class lzma.LZMADecompressor(format=FORMAT_AUTO, memlimit=None, filters=None)

Skapa ett dekompressorobjekt som kan användas för att dekomprimera data stegvis.

För ett mer bekvämt sätt att dekomprimera en hel komprimerad ström på en gång, se decompress().

Argumentet format anger vilket containerformat som ska användas. Standardvärdet är FORMAT_AUTO, som kan dekomprimera både .xz och .lzma-filer. Andra möjliga värden är FORMAT_XZ, FORMAT_ALONE och FORMAT_RAW.

Argumentet memlimit anger en gräns (i byte) för hur mycket minne som dekomprimeraren kan använda. När detta argument används kommer dekomprimeringen att misslyckas med ett LZMAError om det inte är möjligt att dekomprimera indata inom den angivna minnesgränsen.

Argumentet filters anger den filterkedja som användes för att skapa den ström som dekomprimeras. Detta argument krävs om format är FORMAT_RAW, men ska inte användas för andra format. Se Ange anpassade filterkedjor för mer information om filterkedjor.

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 LZMAFile. För att dekomprimera en inmatning med flera strömmar med LZMADecompressor måste du skapa 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.

check

ID för den integritetskontroll som används av indataströmmen. Detta kan vara CHECK_UNKNOWN tills tillräckligt mycket av inmatningen har avkodats för att avgöra vilken integritetskontroll som används.

eof

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

unused_data

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

Innan slutet av strömmen nås kommer detta 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.

lzma.compress(data, format=FORMAT_XZ, check=-1, preset=None, filters=None)

Komprimera data (ett bytes-objekt) och returnera den komprimerade datan som ett bytes-objekt.

Se LZMACompressor ovan för en beskrivning av argumenten format, check, preset och filters.

lzma.decompress(data, format=FORMAT_AUTO, memlimit=None, filters=None)

Dekomprimera data (ett bytes-objekt) och returnera okomprimerad data som ett bytes-objekt.

Om data är en sammankoppling av flera olika komprimerade flöden, dekomprimera alla dessa flöden och returnera sammankopplingen av resultaten.

Se LZMADecompressor ovan för en beskrivning av argumenten format, memlimit och filters.

Diverse

lzma.is_check_supported(check)

Returnerar True om den angivna integritetskontrollen stöds på detta system.

CHECK_NONE och CHECK_CRC32 stöds alltid. CHECK_CRC64 och CHECK_SHA256 kanske inte är tillgängliga om du använder en version av liblzma som kompilerades med en begränsad funktionsuppsättning.

Ange anpassade filterkedjor

En filterkedjespecifikation är en sekvens av ordböcker, där varje ordbok innehåller ID och alternativ för ett enda filter. Varje ordbok måste innehålla nyckeln "id" och kan innehålla ytterligare nycklar för att ange filterberoende alternativ. Giltiga filter-ID är följande:

  • Kompressionsfilter:

    • FILTER_LZMA1 (för användning med FORMAT_ALONE)

    • FILTER_LZMA2 (för användning med FORMAT_XZ och FORMAT_RAW)

  • Delta-filter:

    • FILTER_DELTA

  • BCJ-filter (Branch-Call-Jump):

    • FILTER_X86

    • FILTER_IA64

    • FILTER_ARM

    • FILTER_ARMTHUMB

    • FILTER_POWERPC

    • FILTER_SPARC

En filterkedja kan bestå av upp till 4 filter och kan inte vara tom. Det sista filtret i kedjan måste vara ett kompressionsfilter och alla andra filter måste vara delta- eller BCJ-filter.

Komprimeringsfilter har stöd för följande alternativ (anges som ytterligare poster i den ordbok som representerar filtret):

  • preset: En förinställning för komprimering som ska användas som källa för standardvärden för alternativ som inte anges explicit.

  • dict_size: Ordbokens storlek i byte. Den bör ligga mellan 4 KiB och 1,5 GiB (inklusive).

  • lc: Antal bitar för bokstavskontext.

  • lp: Antal bitar för bokstavsposition. Summan lc + lp måste vara högst 4.

  • pb: Antal positionsbitar; får vara högst 4.

  • mode: MODE_FAST eller MODE_NORMAL.

  • nice_len: Vad som ska anses vara en ”fin längd” för en match. Detta bör vara 273 eller mindre.

  • mf: Vilken matchningssökare som ska användas – MF_HC3, MF_HC4, MF_BT2, MF_BT3, eller MF_BT4.

  • depth: Maximalt sökdjup som används av matchningshittaren. 0 (standard) innebär att du väljer automatiskt baserat på andra filteralternativ.

Deltafiltret lagrar skillnaderna mellan byte, vilket under vissa omständigheter ger mer repetitiv indata till kompressorn. Det har stöd för ett alternativ, dist. Detta anger avståndet mellan byte som ska subtraheras. Standardvärdet är 1, d.v.s. skillnaden mellan intilliggande bytes tas med.

BCJ-filtren är avsedda att tillämpas på maskinkod. De konverterar relativa grenar, anrop och hopp i koden så att absolut adressering används, i syfte att öka den redundans som kan utnyttjas av kompressorn. Dessa filter har stöd för ett alternativ, start_offset. Detta anger vilken adress som ska mappas till början av indata. Standardvärdet är 0.

Exempel

Läsa in en komprimerad fil:

import lzma
with lzma.open("file.xz") as f:
    file_content = f.read()

Skapa en komprimerad fil:

import lzma
data = b"Insert Data Here"
with lzma.open("file.xz", "w") as f:
    f.write(data)

Komprimering av data i minnet:

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

Inkrementell komprimering:

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

Skriva komprimerad data till en redan öppen fil:

import lzma
with open("file.xz", "wb") as f:
    f.write(b"This data will not be compressed\n")
    with lzma.open(f, "w") as lzf:
        lzf.write(b"This *will* be compressed\n")
    f.write(b"Not compressed\n")

Skapa en komprimerad fil med hjälp av en anpassad filterkedja:

import lzma
my_filters = [
    {"id": lzma.FILTER_DELTA, "dist": 5},
    {"id": lzma.FILTER_LZMA2, "preset": 7 | lzma.PRESET_EXTREME},
]
with lzma.open("file.xz", "w", filters=my_filters) as f:
    f.write(b"blah blah blah")