compression.zstd — Komprimering kompatibel med Zstandard-formatet

Tillagd i version 3.14.

Källkod: Lib/compression/zstd/__init__.py

Denna modul innehåller klasser och funktioner för komprimering och dekomprimering av data med hjälp av komprimeringsalgoritmen Zstandard (eller zstd). I zstd manual beskrivs Zstandard som ”en snabb förlustfri komprimeringsalgoritm, inriktad på realtidskomprimeringsscenarier på zlib-nivå och bättre komprimeringsförhållanden.” Dessutom ingår ett filgränssnitt som stöder läsning och skrivning av innehållet i .zst-filer som skapats av verktyget zstd, samt råa zstd-komprimerade strömmar.

Modulen compression.zstd innehåller:

Undantag

exception compression.zstd.ZstdError

Detta undantag aktiveras när ett fel inträffar under komprimering eller dekomprimering, eller när (de)kompressortillståndet initieras.

Läsa och skriva komprimerade filer

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

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

Argumentet file kan antingen vara ett 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.

Mode-argumentet kan vara antingen 'rb' för läsning (standard), 'wb' för överskrivning, 'ab' för tillägg eller 'xb' för exklusiv skapelse. Dessa kan på motsvarande sätt anges som 'r', 'w', 'a' respektive 'x'. Du kan också öppna i textläge med 'rt', 'wt', 'at' respektive 'xt'.

Vid läsning kan argumentet options vara en ordbok som innehåller avancerade dekomprimeringsparametrar; se DecompressionParameter för detaljerad information om parametrar som stöds. Argumentet zstd_dict är en instans av ZstdDict som ska användas under dekomprimeringen. Vid läsning, om argumentet level inte är None, kommer ett TypeError att uppstå.

Vid skrivning kan argumentet options vara en ordbok som innehåller avancerade dekomprimeringsparametrar; se CompressionParameter för detaljerad information om parametrar som stöds. Argumentet level är den komprimeringsnivå som ska användas vid skrivning av komprimerade data. Endast en av level eller options får vara icke-None. Argumentet zstd_dict är en ZstdDict-instans som ska användas under komprimeringen.

I binärt läge är denna funktion likvärdig med ZstdFile-konstruktören: ZstdFile(file, mode, ...). I detta fall får parametrarna encoding, errors och newline inte anges.

I textläge skapas ett ZstdFile-objekt och omsluts av en io.TextIOWrapper-instans med angiven kodning, felhanteringsbeteende och radavslut.

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

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

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

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

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

Vid läsning kan argumentet options vara en ordbok som innehåller avancerade dekomprimeringsparametrar; se DecompressionParameter för detaljerad information om parametrar som stöds. Argumentet zstd_dict är en instans av ZstdDict som ska användas under dekomprimeringen. Vid läsning, om argumentet level inte är None, kommer ett TypeError att uppstå.

Vid skrivning kan argumentet options vara en ordbok som innehåller avancerade dekomprimeringsparametrar; se CompressionParameter för detaljerad information om parametrar som stöds. Argumentet level är den komprimeringsnivå som ska användas vid skrivning av komprimerade data. Endast en av level eller options kan skickas. Argumentet zstd_dict är en ZstdDict-instans som ska användas under komprimeringen.

ZstdFile 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 ZstdFile, kan det ändra positionen för det underliggande filobjektet (till exempel om ZstdFile konstruerades genom att skicka ett filobjekt för file).

mode

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

name

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

Komprimering och dekomprimering av data i minnet

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

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

Argumentet level är ett heltal som styr komprimeringsnivån. level är ett alternativ till att ange CompressionParameter.compression_level i options. Använd bounds() på compression_level för att få fram de värden som kan anges för level. Om avancerade komprimeringsalternativ behövs måste argumentet level utelämnas och i ordlistan options ska parametern CompressionParameter.compression_level anges.

Argumentet options är en Python-dictionary som innehåller avancerade komprimeringsparametrar. Giltiga nycklar och värden för komprimeringsparametrar dokumenteras som en del av CompressionParameter-dokumentationen.

Argumentet zstd_dict är en instans av ZstdDict som innehåller tränade data för att förbättra komprimeringseffektiviteten. Funktionen train_dict() kan användas för att generera en Zstandard-ordbok.

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

Dekomprimerar data (ett bytesliknande objekt) och returnerar de okomprimerade data som ett bytes-objekt.

Argumentet options är en Python-dictionary som innehåller avancerade dekompressionsparametrar. De giltiga nycklarna och värdena för komprimeringsparametrar dokumenteras som en del av DecompressionParameter-dokumentationen.

Argumentet zstd_dict är en instans av ZstdDict som innehåller tränade data som används under komprimeringen. Detta måste vara samma Zstandard-ordbok som användes vid komprimeringen.

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

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

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

För ett mer praktiskt sätt att komprimera en enda datastump, se modulen compress().

Argumentet level är ett heltal som styr komprimeringsnivån. level är ett alternativ till att ange CompressionParameter.compression_level i options. Använd bounds() på compression_level för att få fram de värden som kan anges för level. Om avancerade komprimeringsalternativ behövs måste argumentet level utelämnas och i ordlistan options ska parametern CompressionParameter.compression_level anges.

Argumentet options är en Python-dictionary som innehåller avancerade komprimeringsparametrar. Giltiga nycklar och värden för komprimeringsparametrar dokumenteras som en del av CompressionParameter-dokumentationen.

Argumentet zstd_dict är en valfri instans av ZstdDict som innehåller tränade data för att förbättra komprimeringseffektiviteten. Funktionen train_dict() kan användas för att generera en Zstandard-ordbok.

compress(data, mode=ZstdCompressor.CONTINUE)

Komprimerar data (ett bytesliknande objekt), returnerar ett bytes-objekt med komprimerad data om möjligt, eller annars ett tomt bytes-objekt. En del av data kan buffras internt för att användas i senare anrop till compress() och flush(). De returnerade data bör sammankopplas med utdata från eventuella tidigare anrop till compress().

Argumentet mode är ett ZstdCompressor-attribut, antingen CONTINUE, FLUSH_BLOCK eller FLUSH_FRAME.

När alla data har levererats till kompressorn anropas metoden flush() för att avsluta komprimeringsprocessen. Om compress() anropas med mode satt till FLUSH_FRAME, ska flush() inte anropas, eftersom det skulle skriva ut en ny tom ram.

flush(mode=ZstdCompressor.FLUSH_FRAME)

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

Argumentet mode är ett ZstdCompressor-attribut, antingen FLUSH_BLOCK eller FLUSH_FRAME.

set_pledged_input_size(size)

Ange mängden okomprimerad data size som ska tillhandahållas för nästa bildruta. size kommer att skrivas in i bildhuvudet för nästa bild om inte CompressionParameter.content_size_flag är False eller 0. En storlek på 0 innebär att ramen är tom. Om size är None kommer ramhuvudet att utelämna ramstorleken. Ramar som innehåller den okomprimerade datastorleken kräver mindre minne för att dekomprimeras, särskilt vid högre komprimeringsnivåer.

Om last_mode inte är FLUSH_FRAME, uppstår ett ValueError eftersom kompressorn inte befinner sig i början av en frame. Om den utlovade storleken inte stämmer överens med den faktiska storleken på data som tillhandahålls till compress(), kan framtida anrop till compress() eller flush() ge upphov till ZstdError och den sista delen av data kan gå förlorad.

Efter att flush() eller compress() har anropats med läget FLUSH_FRAME, kommer nästa bildruta inte att inkludera bildrutans storlek i sidhuvudet om inte set_pledged_input_size() anropas igen.

CONTINUE

Samla in mer data för komprimering, som kanske eller kanske inte genererar utdata omedelbart. Detta läge optimerar komprimeringsgraden genom att maximera mängden data per block och bildruta.

FLUSH_BLOCK

Slutför och skriv ett block till dataströmmen. De data som hittills returnerats kan omedelbart dekomprimeras. Tidigare data kan fortfarande refereras till i framtida block som genereras genom anrop till compress(), vilket förbättrar komprimeringen.

FLUSH_FRAME

Komplettera och skriv ut en ram. Framtida data som tillhandahålls till compress() kommer att skrivas in i en ny ram och kan inte referera till tidigare data.

last_mode

Det sista läget som skickades till antingen compress() eller flush(). Värdet kan vara ett av CONTINUE, FLUSH_BLOCK eller FLUSH_FRAME. Initialvärdet är FLUSH_FRAME, vilket betyder att kompressorn är i början av en ny bildruta.

class compression.zstd.ZstdDecompressor(zstd_dict=None, options=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 modulen decompress().

Argumentet options är en Python-dictionary som innehåller avancerade dekompressionsparametrar. De giltiga nycklarna och värdena för komprimeringsparametrar dokumenteras som en del av DecompressionParameter-dokumentationen.

Argumentet zstd_dict är en instans av ZstdDict som innehåller tränade data som används under komprimeringen. Detta måste vara samma Zstandard-ordbok som användes vid komprimeringen.

Anteckning

Till skillnad från decompress()-funktionen och ZstdFile-klassen hanterar den här klassen inte inmatningar som innehåller flera komprimerade bildrutor på ett transparent sätt. För att dekomprimera en inmatning med flera bildrutor bör du använda decompress(), ZstdFile om du arbetar med ett file object, eller flera ZstdDecompressor-instanser.

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 returnerar metoden högst max_length bytes 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 slutet av en bildruta kommer att ge upphov till ett ZstdError. Alla data som hittas efter ramens slut ignoreras och sparas i attributet unused_data.

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 komprimerad inmatning.

Zstandard-ordböcker

compression.zstd.train_dict(samples, dict_size)

Tränar en Zstandard-ordbok och returnerar en instans av ZstdDict. Zstandard-ordböcker möjliggör effektivare komprimering av mindre datastorlekar, som traditionellt är svåra att komprimera på grund av mindre upprepning. Om du komprimerar flera liknande datagrupper (t.ex. liknande filer) kan Zstandard-ordböcker förbättra komprimeringsgraden och hastigheten avsevärt.

Argumentet samples (en iterabel av bytes-objekt) är den population av prover som används för att träna Zstandard-ordboken.

Argumentet dict_size, ett heltal, är den maximala storleken (i byte) som Zstandard-ordboken ska ha. I Zstandard-dokumentationen föreslås en absolut maxstorlek på högst 100 KB, men maxstorleken kan ofta vara mindre beroende på data. Större ordböcker gör i allmänhet komprimeringen långsammare, men förbättrar komprimeringsgraden. Mindre ordlistor leder till snabbare komprimering, men minskar komprimeringsgraden.

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

En avancerad funktion för att konvertera en Zstandard-ordbok med ”rått innehåll” till en vanlig Zstandard-ordbok. ordböcker med ”obearbetat innehåll” är en sekvens av bytes som inte behöver följa strukturen för en vanlig Zstandard-ordbok.

Argumentet zstd_dict är en instans av ZstdDict med dict_content som innehåller det råa innehållet i ordboken.

Argumentet samples (en iterabel av bytes-objekt) innehåller exempeldata för generering av Zstandard-ordboken.

Argumentet dict_size, ett heltal, är den maximala storleken (i byte) som Zstandard-ordboken ska ha. Se train_dict() för förslag på den maximala ordboksstorleken.

Argumentet level (ett heltal) är den komprimeringsnivå som förväntas skickas till kompressorerna med hjälp av denna ordbok. Informationen i ordlistan varierar för varje komprimeringsnivå, så om du ställer in rätt komprimeringsnivå kan komprimeringen bli effektivare.

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

Ett omslag runt Zstandard-ordböcker. Ordböcker kan användas för att förbättra komprimeringen av många små bitar av data. Använd train_dict() om du behöver träna en ny ordbok från exempeldata.

Argumentet dict_content (ett bytesliknande objekt) är den redan utbildade ordboksinformationen.

Argumentet is_raw, ett boolean, är en avancerad parameter som styr betydelsen av dict_content. True betyder att dict_content är en ordbok med ”rått innehåll”, utan några formatbegränsningar. False betyder att dict_content är en vanlig Zstandard-ordbok, skapad från Zstandard-funktioner, till exempel train_dict() eller det externa zstd CLI.

När du skickar en ZstdDict till en funktion kan attributen as_digested_dict och as_undigested_dict styra hur ordboken laddas genom att skicka dem som argumentet zstd_dict, till exempel compress(data, zstd_dict=zd.as_digested_dict). Att smälta en ordbok är en kostsam operation som sker när en Zstandard-ordbok laddas. När du gör flera anrop till komprimering eller dekomprimering minskar omkostnaderna för att ladda ordboken genom att skicka en digererad ordbok.

Skillnad för komprimering

Digererad ordbok

Osmält ordbok

Avancerade parametrar för kompressorn som kan åsidosättas av ordbokens parametrar

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 och vissa icke-offentliga parametrar.

Ingen

ZstdDict cachelagrar ordboken internt

Ja, det går snabbare att läsa in en smält ordbok igen med samma komprimeringsnivå.

Nej. Om du vill ladda en obehandlad ordbok flera gånger kan du överväga att återanvända ett kompressorobjekt.

Om du skickar en ZstdDict utan något attribut, skickas en odigererad ordbok som standard vid komprimering och en digererad ordbok genereras vid behov och skickas som standard vid dekomprimering.

dict_content

Innehållet i Zstandard-ordlistan, ett bytes-objekt. Det är samma som argumentet dict_content i metoden __init__. Det kan användas med andra program, till exempel CLI-programmet zstd.

dict_id

Identifierare för Zstandard-ordlistan, ett icke-negativt int-värde.

Icke-noll betyder att ordlistan är vanlig, skapad av Zstandard-funktioner och följer Zstandard-formatet.

0 innebär en ordbok med ”obearbetat innehåll”, fri från formatbegränsningar, som används av avancerade användare.

Anteckning

Betydelsen av 0 för ZstdDict.dict_id skiljer sig från attributet dictionary_id för funktionen get_frame_info().

as_digested_dict

Ladda som en smält ordbok.

as_undigested_dict

Ladda som en osmält ordbok.

Avancerad parameterkontroll

class compression.zstd.CompressionParameter

En IntEnum som innehåller nycklar för avancerade komprimeringsparametrar som kan användas vid komprimering av data.

Metoden bounds() kan användas på vilket attribut som helst för att få fram giltiga värden för den parametern.

Parametrar är valfria; om någon parameter utelämnas kommer dess värde att väljas automatiskt.

Exempel på hur man får fram den nedre och övre gränsen för compression_level:

nedre, övre = Kompressionsparameter.kompressionsnivå.gränser()

Exempel på inställning av window_log till maximal storlek:

_lower, upper = Kompressionsparameter.window_log.bounds()
options = {Komprimeringsparameter.window_log: övre}
compress(b'venezuelansk bäverost', options=options)
bounds()

Returnerar en tupel av int-gränser, (lower, upper), för en komprimeringsparameter. Denna metod bör anropas på det attribut som du vill hämta gränserna för. För att få giltiga värden för compression_level kan man t.ex. kontrollera resultatet av CompressionParameter.compression_level.bounds().

Både den nedre och den övre gränsen är inkluderande.

compression_level

Ett sätt att på hög nivå ställa in andra komprimeringsparametrar som påverkar hastigheten och förhållandet för komprimering av data.

Vanliga komprimeringsnivåer är större än 0. Värden större än 20 anses vara ”ultra”-komprimering och kräver mer minne än andra nivåer. Negativa värden kan användas för att kompromissa mellan snabbare komprimering och sämre komprimeringsgrad.

Om nivån sätts till noll används COMPRESSION_LEVEL_DEFAULT.

window_log

Maximalt tillåtet back-reference-avstånd som kompressorn kan använda vid datakomprimering, uttryckt som en potens av två, 1 << window_log bytes. Denna parameter påverkar i hög grad minnesanvändningen vid komprimering. Högre värden kräver mer minne men ger bättre komprimeringsvärden.

Ett värde på noll gör att värdet väljs automatiskt.

hash_log

Storlek på den initiala probe-tabellen, som en potens av två. Den resulterande minnesanvändningen är 1 << (hash_log+2) byte. Större tabeller förbättrar komprimeringsgraden för strategier <= dfast, och förbättrar komprimeringshastigheten för strategier > dfast.

Ett värde på noll gör att värdet väljs automatiskt.

chain_log

Storlek på söktabellen för flera sonder, som en potens av två. Den resulterande minnesanvändningen är 1 << (chain_log+2) byte. Större tabeller resulterar i bättre och långsammare komprimering. Denna parameter har ingen effekt för strategin fast. Den är fortfarande användbar när du använder strategin dfast, i vilket fall den definierar en sekundär probetabell.

Ett värde på noll gör att värdet väljs automatiskt.

search_log

Antal sökförsök, som en potens av två. Fler försök resulterar i bättre och långsammare komprimering. Denna parameter är värdelös för strategierna fast och dfast.

Ett värde på noll gör att värdet väljs automatiskt.

min_match

Minsta storlek på sökta matchningar. Större värden ökar komprimerings- och dekomprimeringshastigheten, men minskar förhållandet. Observera att Zstandard fortfarande kan hitta matchningar av mindre storlek, den justerar bara sin sökalgoritm för att leta efter denna storlek och större. För alla strategier < btopt är det effektiva minimumet 4; för alla strategier > fast är det effektiva maximumet 6.

Ett värde på noll gör att värdet väljs automatiskt.

target_length

Effekten av detta fält beror på den valda Strategy.

För strategierna btopt, btultra och btultra2 är värdet längden på en matchning som anses vara ”tillräckligt bra” för att sluta söka. Större värden ger bättre komprimeringsgrad, men komprimerar långsammare.

För strategi fast är det avståndet mellan matchningssamplingarna. Större värden gör komprimeringen snabbare, men med ett sämre komprimeringsförhållande.

Ett värde på noll gör att värdet väljs automatiskt.

strategy

Ju högre värde på vald strategi, desto mer komplex är den komprimeringsteknik som används av zstd, vilket resulterar i högre komprimeringsgrad men långsammare komprimering.

Se även

Strategi

enable_long_distance_matching

Matchning på långa avstånd kan användas för att förbättra komprimeringen för stora indata genom att hitta stora matchningar på större avstånd. Det ökar minnesanvändningen och fönsterstorleken.

True eller 1 aktiverar långdistansmatchning medan False eller 0 inaktiverar den.

Om du aktiverar den här parametern ökar standardvärdet för window_log till 128 MiB, utom när det uttryckligen anges till ett annat värde. Den här inställningen är aktiverad som standard om window_log >= 128 MiB och komprimeringsstrategin >= btopt (komprimeringsnivå 16+).

ldm_hash_log

Storlek på tabellen för matchning på långt avstånd, som en potens av två. Större värden ökar minnesanvändningen och komprimeringsgraden, men minskar komprimeringshastigheten.

Ett värde på noll gör att värdet väljs automatiskt.

ldm_min_match

Minsta matchningsstorlek för långdistansmatchning. Större eller för små värden kan ofta minska komprimeringsgraden.

Ett värde på noll gör att värdet väljs automatiskt.

ldm_bucket_size_log

Loggar storleken på varje hink i hashtabellen för kollisionsupplösning i Long Distance Matcher. Större värden förbättrar kollisionsupplösningen men minskar komprimeringshastigheten.

Ett värde på noll gör att värdet väljs automatiskt.

ldm_hash_rate_log

Frekvens för infogning/uppslagning av poster i hashtabellen för långdistansmatchning. Större värden förbättrar komprimeringshastigheten. Om du avviker mycket från standardvärdet kommer det sannolikt att leda till en minskning av komprimeringsgraden.

Ett värde på noll gör att värdet väljs automatiskt.

content_size_flag

Skriv in storleken på de data som ska komprimeras i Zstandard-ramhuvudet när den är känd före komprimeringen.

Denna flagga träder endast i kraft i följande scenarier:

Alla andra komprimeringsanrop får inte skriva in storleksinformationen i ramhuvudet.

True eller 1 aktiverar innehållsstorleksflaggan medan False eller 0 inaktiverar den.

checksum_flag

En kontrollsumma på fyra byte som använder XXHash64 för det okomprimerade innehållet skrivs i slutet av varje bildruta. Zstandards dekomprimeringskod verifierar kontrollsumman. Om det finns en felmatchning uppstår ett ZstdError undantag.

True eller 1 aktiverar generering av checksumma medan False eller 0 inaktiverar den.

dict_id_flag

Vid komprimering med en ZstdDict skrivs ordbokens ID in i ramhuvudet.

True eller 1 aktiverar lagring av ordboks-ID medan False eller 0 inaktiverar det.

nb_workers

Välj hur många trådar som ska skapas för att komprimera parallellt. När nb_workers > 0, aktiveras komprimering med flera trådar, ett värde på 1 betyder ”en-tråds multitrådigt läge”. Fler arbetare förbättrar hastigheten, men ökar också minnesanvändningen och minskar komprimeringsgraden något.

Ett värde på noll inaktiverar multi-threading.

job_size

Storlek på ett komprimeringsjobb, i byte. Detta värde gäller endast när nb_workers >= 1. Varje komprimeringsjobb slutförs parallellt, så det här värdet kan indirekt påverka antalet aktiva trådar.

Ett värde på noll gör att värdet väljs automatiskt.

overlap_log

Ställer in hur mycket data som laddas om från tidigare jobb (trådar) för nya jobb som ska användas av look behind-fönstret under komprimeringen. Detta värde används endast när nb_workers >= 1. Godtagbara värden varierar från 0 till 9.

  • 0 innebär att överlappningsmängden ställs in dynamiskt

  • 1 betyder ingen överlappning

  • 9 innebär att man använder en hel fönsterstorlek från föregående jobb

Varje steg halverar/fördubblar överlappningsstorleken. ”8” innebär en överlappning av ”window_size/2”, ”7” innebär en överlappning av ”window_size/4”, etc.

class compression.zstd.DecompressionParameter

En IntEnum som innehåller nycklar till avancerade dekomprimeringsparametrar som kan användas vid dekomprimering av data. Parametrarna är valfria; om någon parameter utelämnas kommer dess värde att väljas automatiskt.

Metoden bounds() kan användas på vilket attribut som helst för att få fram giltiga värden för den parametern.

Exempel på inställning av window_log_max till maximal storlek:

data = compress(b'En mycket lång buffert med bytes...')

_lower, upper = Dekomprimeringsparameter.window_log_max.bounds()

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

Returnerar en tupel av int-gränser, (lower, upper), för en dekomprimeringsparameter. Denna metod bör anropas på det attribut som du vill hämta gränserna för.

Både den nedre och den övre gränsen är inkluderande.

window_log_max

Bas-två-logaritmen av den maximala storleken på det fönster som används vid dekomprimering. Detta kan vara användbart för att begränsa mängden minne som används vid dekomprimering av data. En större maximal fönsterstorlek leder till snabbare dekomprimering.

Ett värde på noll gör att värdet väljs automatiskt.

class compression.zstd.Strategy

En IntEnum som innehåller strategier för komprimering. Högre numrerade strategier motsvarar mer komplex och långsammare komprimering.

Anteckning

Värdena för attributen i Strategy är inte nödvändigtvis stabila i olika zstd-versioner. Endast attributens ordningsföljd kan åberopas. Attributen är listade nedan i ordning.

Följande strategier finns tillgängliga:

fast
dfast
greedy
lazy
lazy2
btlazy2
btopt
btultra
btultra2

Diverse

compression.zstd.get_frame_info(frame_buffer)

Hämtar ett FrameInfo-objekt som innehåller metadata om en Zstandard-ram. Ramar innehåller metadata som är relaterade till de komprimerade data de innehåller.

class compression.zstd.FrameInfo

Metadata relaterade till en Zstandard-ram.

decompressed_size

Storleken på det dekomprimerade innehållet i ramen.

dictionary_id

Ett heltal som representerar det Zstandard Dictionary ID som behövs för att dekomprimera ramen. 0 betyder att ordboks-ID:t inte registrerades i ramhuvudet. Detta kan betyda att en Zstandard-ordbok inte behövs, eller att ID för en nödvändig ordbok inte registrerades.

compression.zstd.COMPRESSION_LEVEL_DEFAULT

Standardkomprimeringsnivå för Zstandard: 3.

compression.zstd.zstd_version_info

Versionsnummer för runtime-biblioteket zstd som en tupel av heltal (major, minor, release).

Exempel

Läser in en komprimerad fil:

from compression import zstd

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

Skapa en komprimerad fil:

from compression import zstd

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

Komprimering av data i minnet:

from compression import zstd

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

Inkrementell komprimering:

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

Skriver komprimerad data till en redan öppen fil:

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

Skapa en komprimerad fil med hjälp av komprimeringsparametrar:

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?")