zlib — Komprimering kompatibel med gzip

För applikationer som kräver datakomprimering möjliggör funktionerna i den här modulen komprimering och dekomprimering med hjälp av zlib-biblioteket. Biblioteket zlib har sin egen webbplats på https://www.zlib.net. Det finns kända inkompatibiliteter mellan Python-modulen och versioner av zlib-biblioteket tidigare än 1.1.3; 1.1.3 har en säkerhetsbrist, så vi rekommenderar att du använder 1.1.4 eller senare.

zlibs funktioner har många alternativ och måste ofta användas i en viss ordning. Denna dokumentation försöker inte täcka alla permutationer; se zlib-manualen på http://www.zlib.net/manual.html för auktoritativ information.

För läsning och skrivning av .gz-filer, se modulen gzip.

De undantag och funktioner som är tillgängliga i denna modul är:

exception zlib.error

Undantag vid fel i komprimering och dekomprimering.

zlib.adler32(data[, value])

Beräknar en Adler-32-kontrollsumma av data. (En Adler-32-kontrollsumma är nästan lika tillförlitlig som en CRC32 men kan beräknas mycket snabbare) Resultatet är ett osignerat 32-bitars heltal. Om value finns med används det som startvärde för kontrollsumman, annars används standardvärdet 1. Genom att ange value kan man beräkna en löpande kontrollsumma över sammankopplingen av flera indata. Algoritmen är inte kryptografiskt stark och bör inte användas för autentisering eller digitala signaturer. Eftersom algoritmen är utformad för att användas som en checksummealgoritm är den inte lämplig att använda som en allmän hashalgoritm.

Ändrad i version 3.0: Resultatet är alltid osignerat.

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

Komprimerar bytena i data och returnerar ett bytes-objekt som innehåller komprimerade data. level är ett heltal från 0 till 9 eller -1 som styr komprimeringsnivån; 1 (Z_BEST_SPEED) är snabbast och ger minst komprimering, 9 (Z_BEST_COMPRESSION) är långsammast och ger mest. 0 (Z_NO_COMPRESSION) är ingen komprimering. Standardvärdet är -1 (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION representerar en standardkompromiss mellan hastighet och komprimering (motsvarar för närvarande nivå 6).

Argumentet wbits styr storleken på historikbufferten (eller ”fönsterstorleken”) som används vid komprimering av data och om en header och trailer ska inkluderas i utdata. Det kan anta flera olika värden, men standardvärdet är 15 (MAX_WBITS):

  • +9 till +15: Bas-två-logaritmen av fönsterstorleken, som därför varierar mellan 512 och 32768. Större värden ger bättre komprimering på bekostnad av större minnesanvändning. Den resulterande utdata kommer att innehålla en zlib-specifik header och trailer.

  • -9 till -15: Använder det absoluta värdet av wbits som logaritm för fönsterstorleken, samtidigt som en rå utdataström produceras utan rubrik eller efterföljande kontrollsumma.

  • +25 till +31 = 16 + (9 till 15): Använder de 4 lägsta bitarna av värdet som logaritm för fönsterstorleken, samtidigt som en grundläggande gzip-header och en efterföljande kontrollsumma inkluderas i utdata.

Om något fel inträffar visas undantaget error.

Ändrad i version 3.6: level kan nu användas som nyckelordsparameter.

Ändrad i version 3.11: Parametern wbits är nu tillgänglig för att ställa in fönsterbitar och komprimeringstyp.

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

Returnerar ett komprimeringsobjekt som kan användas för att komprimera dataströmmar som inte ryms i minnet på en gång.

level är komprimeringsnivån - ett heltal från 0 till 9 eller -1. Ett värde på 1 (Z_BEST_SPEED) är snabbast och ger minst komprimering, medan ett värde på 9 (Z_BEST_COMPRESSION) är långsammast och ger mest. 0 (Z_NO_COMPRESSION) innebär ingen komprimering. Standardvärdet är -1 (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION representerar en standardkompromiss mellan hastighet och komprimering (motsvarar för närvarande nivå 6).

method är komprimeringsalgoritmen. För närvarande är det enda värdet som stöds DEFLATED.

Parametern wbits styr storleken på historikbufferten (eller ”fönsterstorleken”) och vilket header- och trailerformat som ska användas. Den har samma betydelse som beskrivs för compress().

Argumentet memLevel styr hur mycket minne som används för det interna komprimeringstillståndet. Giltiga värden sträcker sig från 1 till 9. Högre värden använder mer minne, men är snabbare och ger mindre utdata.

strategy används för att ställa in komprimeringsalgoritmen. Möjliga värden är Z_DEFAULT_STRATEGY, Z_FILTERED, Z_HUFFMAN_ONLY, Z_RLE (zlib 1.2.0.1) och Z_FIXED (zlib 1.2.2.2).

zdict är en fördefinierad komprimeringsordbok. Detta är en sekvens av bytes (t.ex. ett bytes-objekt) som innehåller undersekvenser som förväntas förekomma ofta i de data som ska komprimeras. De undersekvenser som förväntas vara vanligast bör komma i slutet av ordlistan.

Ändrad i version 3.3: Lagt till parametern zdict och stöd för nyckelordsargument.

zlib.crc32(data[, value])

Beräknar en CRC-kontrollsumma (Cyclic Redundancy Check) för data. Resultatet är ett osignerat 32-bitars heltal. Om value finns med används det som startvärde för kontrollsumman, annars används standardvärdet 0. Genom att skicka in value kan man beräkna en löpande kontrollsumma över sammankopplingen av flera inmatningar. Algoritmen är inte kryptografiskt stark och bör inte användas för autentisering eller digitala signaturer. Eftersom algoritmen är utformad för att användas som en checksummealgoritm är den inte lämplig att använda som en allmän hashalgoritm.

Ändrad i version 3.0: Resultatet är alltid osignerat.

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

Dekomprimerar byte i data och returnerar ett bytes-objekt som innehåller okomprimerad data. Parametern wbits beror på formatet för data och beskrivs närmare nedan. Om bufsize anges, används den som initial storlek på utmatningsbufferten. Om något fel inträffar genereras undantaget error.

Parametern wbits styr storleken på historiebufferten (eller ”fönsterstorleken”) och vilket header- och trailerformat som förväntas. Den liknar parametern för compressobj(), men accepterar fler värdeintervall:

  • +8 till +15: Bas-två logaritmen av fönsterstorleken. Inmatningen måste innehålla en zlib-header och trailer.

  • 0: Bestäm automatiskt fönsterstorleken från zlib-headern. Stöds endast sedan zlib 1.2.3.5.

  • -8 till -15: Använder det absoluta värdet av wbits som logaritm för fönsterstorleken. Indata måste vara en rå ström utan header eller trailer.

  • +24 till +31 = 16 + (8 till 15): Använder de 4 lägsta bitarna av värdet som logaritm för fönsterstorleken. Indata måste innehålla en gzip-header och -trailer.

  • +40 till +47 = 32 + (8 till 15): Använder de 4 lägsta bitarna av värdet som logaritm för fönsterstorleken och accepterar automatiskt antingen zlib- eller gzip-format.

Vid dekomprimering av en ström får fönsterstorleken inte vara mindre än den storlek som ursprungligen användes för att komprimera strömmen; om du använder ett för litet värde kan det resultera i ett error-undantag. Standardvärdet wbits motsvarar den största fönsterstorleken och kräver att en zlib-header och -trailer inkluderas.

bufsize är den initiala storleken på den buffert som används för att lagra dekomprimerad data. Om mer utrymme krävs kommer buffertstorleken att ökas efter behov, så du behöver inte få det här värdet exakt rätt; att ställa in det sparar bara några anrop till malloc().

Ändrad i version 3.6: wbits och bufsize kan användas som nyckelordsargument.

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

Returnerar ett dekomprimeringsobjekt som ska användas för att dekomprimera dataströmmar som inte ryms i minnet på en gång.

Parametern wbits styr storleken på historikbufferten (eller ”fönsterstorleken”) och vilket header- och trailerformat som förväntas. Den har samma betydelse som beskrivs för decompress().

Parametern zdict anger en fördefinierad komprimeringsordlista. Om den anges måste det vara samma ordlista som användes av den kompressor som producerade de data som ska dekomprimeras.

Anteckning

Om zdict är ett föränderligt objekt (t.ex. en bytearray) får du inte ändra dess innehåll mellan anropet till decompressobj() och det första anropet till dekompressorns metod decompress().

Ändrad i version 3.3: Parametern zdict har lagts till.

Komprimeringsobjekt stöder följande metoder:

Compress.compress(data)

Komprimerar data och returnerar ett bytesobjekt som innehåller komprimerade data för åtminstone en del av data i data. Dessa data bör sammankopplas med den utdata som producerats genom föregående anrop till metoden compress(). Viss indata kan sparas i interna buffertar för senare bearbetning.

Compress.flush([mode])

All väntande indata bearbetas och ett bytes-objekt som innehåller den återstående komprimerade utdata returneras. mode kan väljas från konstanterna Z_NO_FLUSH, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH, Z_FULL_FLUSH, Z_BLOCK (zlib 1.2.3.4), eller Z_FINISH, med Z_FINISH som standard. Förutom Z_FINISH tillåter alla konstanter komprimering av ytterligare bytestrings av data, medan Z_FINISH avslutar den komprimerade strömmen och förhindrar komprimering av mer data. Efter anrop av flush() med mode satt till Z_FINISH kan metoden compress() inte anropas igen; den enda realistiska åtgärden är att radera objektet.

Compress.copy()

Returnerar en kopia av komprimeringsobjektet. Detta kan användas för att effektivt komprimera en uppsättning data som delar ett gemensamt initialt prefix.

Ändrad i version 3.8: Lagt till copy.copy() och copy.deepcopy() stöd för komprimeringsobjekt.

Dekomprimeringsobjekt har stöd för följande metoder och attribut:

Decompress.unused_data

Ett bytesobjekt som innehåller alla byte efter slutet av den komprimerade datan. Det vill säga, detta förblir b"" tills den sista byten som innehåller komprimeringsdata är tillgänglig. Om hela bytesträngen visade sig innehålla komprimerad data är detta b"", ett tomt bytesobjekt.

Decompress.unconsumed_tail

Ett bytesobjekt som innehåller alla data som inte förbrukades av det senaste decompress()-anropet eftersom det överskred gränsen för den okomprimerade databufferten. Dessa data har ännu inte setts av zlib-maskineriet, så du måste mata tillbaka dem (eventuellt med ytterligare data sammanlänkade med dem) till ett efterföljande decompress()-anrop för att få korrekt utdata.

Decompress.eof

En boolean som anger om slutet på den komprimerade dataströmmen har nåtts.

Detta gör det möjligt att skilja mellan en korrekt formad komprimerad ström och en ofullständig eller avkortad.

Tillagd i version 3.3.

Decompress.decompress(data, max_length=0)

Dekomprimerar data och returnerar ett bytesobjekt som innehåller okomprimerade data som motsvarar åtminstone en del av data i string. Dessa data bör sammankopplas med den utdata som producerats genom föregående anrop till metoden decompress(). En del av indata kan bevaras i interna buffertar för senare bearbetning.

Om den valfria parametern max_length inte är noll kommer returvärdet inte att vara längre än max_length. Detta kan innebära att inte all komprimerad indata kan bearbetas, och data som inte förbrukats lagras i attributet unconsumed_tail. Denna bytestring måste skickas till ett efterföljande anrop till decompress() om dekomprimeringen ska fortsätta. Om max_length är noll dekomprimeras hela indata och unconsumed_tail är tom.

Ändrad i version 3.6: max_length kan användas som ett nyckelordsargument.

Decompress.flush([length])

All väntande indata bearbetas och ett bytes-objekt som innehåller den återstående okomprimerade utdata returneras. Efter anrop av flush() kan metoden decompress() inte anropas igen; den enda realistiska åtgärden är att radera objektet.

Den valfria parametern length anger den initiala storleken på utmatningsbufferten.

Decompress.copy()

Returnerar en kopia av dekompressionsobjektet. Detta kan användas för att spara dekompressorns tillstånd halvvägs genom dataströmmen för att påskynda slumpmässiga sökningar i strömmen vid en framtida tidpunkt.

Ändrad i version 3.8: Lagt till copy.copy() och copy.deepcopy() stöd för dekompressionsobjekt.

Information om vilken version av zlib-biblioteket som används finns tillgänglig via följande konstanter:

zlib.ZLIB_VERSION

Versionssträngen för det zlib-bibliotek som användes för att bygga modulen. Detta kan skilja sig från det zlib-bibliotek som faktiskt används vid körning, vilket är tillgängligt som ZLIB_RUNTIME_VERSION.

zlib.ZLIB_RUNTIME_VERSION

Versionssträngen för zlib-biblioteket som faktiskt laddats av tolken.

Tillagd i version 3.3.

zlib.ZLIBNG_VERSION

Versionssträngen för zlib-ng-biblioteket som användes för att bygga modulen om zlib-ng användes. När de finns, återspeglar konstanterna ZLIB_VERSION och ZLIB_RUNTIME_VERSION den version av zlib API som tillhandahålls av zlib-ng.

Om zlib-ng inte användes för att bygga modulen, kommer denna konstant att saknas.

Tillagd i version 3.14.

Se även

Modul gzip

Läsa och skriva gzip -formatfiler.

http://www.zlib.net

Webbplatsen för zlib-biblioteket.

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

I zlib-manualen förklaras semantiken och användningen av bibliotekets många funktioner.

Om gzip (de)komprimering är en flaskhals, påskyndar paketet python-isal (de)komprimering med ett mestadels kompatibelt API.