gzip — Stöd för gzip-filer

Källkod: Lib/gzip.py

Den här modulen ger ett enkelt gränssnitt för att komprimera och dekomprimera filer precis som GNU-programmen gzip och gunzip skulle göra.

Datakomprimeringen tillhandahålls av modulen zlib.

Modulen gzip tillhandahåller klassen GzipFile samt bekvämlighetsfunktionerna open(), compress() och decompress(). Klassen GzipFile läser och skriver filer i formatet gzip och komprimerar eller dekomprimerar automatiskt data så att det ser ut som ett vanligt file object.

Observera att ytterligare filformat som kan dekomprimeras med programmen gzip och gunzip, t.ex. de som produceras av compress och pack, inte stöds av denna modul.

Modulen definierar följande punkter:

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

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

Argumentet filnamn kan 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', 'a', 'ab', 'w', 'wb', 'x' eller 'xb' för binärt läge, eller 'rt', 'at', 'wt' eller 'xt' för textläge. Standardvärdet är 'rb'.

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

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

För textläge skapas ett GzipFile-objekt och omsluts av en io.TextIOWrapper-instans med angiven kodning, felhanteringsbeteende och radavslut.

Ändrad i version 3.3: Lagt till stöd för att filename är ett filobjekt, stöd för textläge och argumenten encoding, errors och newline.

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

exception gzip.BadGzipFile

Ett undantag som uppstår för ogiltiga gzip-filer. Den ärver från OSError. EOFError och zlib.error kan också användas för ogiltiga gzip-filer.

Tillagd i version 3.8.

class gzip.GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)

Konstruktör för klassen GzipFile, som simulerar de flesta metoderna för ett file object, med undantag för metoden truncate(). Minst en av fileobj och filename måste ges ett icke-trivialt värde.

Den nya klassinstansen är baserad på fileobj, som kan vara en vanlig fil, ett io.BytesIO-objekt eller något annat objekt som simulerar en fil. Standardvärdet är None, i vilket fall filnamn öppnas för att tillhandahålla ett filobjekt.

När fileobj inte är None används argumentet filnamn endast för att inkluderas i filhuvudet för gzip, som kan innehålla det ursprungliga filnamnet för den okomprimerade filen. Standardvärdet är filnamnet för fileobj, om det kan urskiljas; annars är standardvärdet den tomma strängen, och i detta fall inkluderas inte det ursprungliga filnamnet i sidhuvudet.

Argumentet mode kan vara något av 'r', 'rb', 'a', 'ab', 'w', 'wb', 'x' eller 'xb', beroende på om filen ska läsas eller skrivas. Standardvärdet är läget för fileobj om det går att urskilja; annars är standardvärdet 'rb'. I framtida Python-utgåvor kommer läget för fileobj inte att användas. Det är bättre att alltid ange mode för skrivning.

Observera att filen alltid öppnas i binärt läge. För att öppna en komprimerad fil i textläge, använd open() (eller linda in din GzipFile med en io.TextIOWrapper).

Argumentet compresslevel är ett heltal från 0 till 9 som styr komprimeringsnivån; 1 är snabbast och ger minst komprimering, och 9 är långsammast och ger mest komprimering. 0 innebär ingen komprimering. Standardvärdet är 9.

Det valfria argumentet mtime är den tidsstämpel som gzip begär. Tiden är i Unix-format, dvs. sekunder sedan 00:00:00 UTC, den 1 januari 1970. Om mtime utelämnas eller None används den aktuella tiden. Använd mtime = 0 för att generera en komprimerad ström som inte är beroende av skapelsetiden.

Se nedan för attributet mtime som ställs in vid dekomprimering.

Anrop av ett GzipFile-objekts close()-metod stänger inte fileobj, eftersom du kanske vill lägga till mer material efter de komprimerade data. Detta gör det också möjligt att skicka ett io.BytesIO-objekt som öppnats för skrivning som fileobj och hämta den resulterande minnesbufferten med hjälp av io.BytesIO-objektets getvalue()-metod.

GzipFile stöder io.BufferedIOBase-gränssnittet, inklusive iteration och with-satsen. Det är bara metoden truncate() som inte är implementerad.

GzipFile tillhandahåller även följande metod och attribut:

peek(n)

Läs n okomprimerade byte utan att flytta fram filpositionen. Antalet bytes som returneras kan vara fler eller färre än vad som begärts.

Anteckning

Även om anrop av peek() inte ändrar filpositionen för GzipFile, kan det ändra positionen för det underliggande filobjektet (t.ex. om GzipFile konstruerades med parametern fileobj).

Tillagd i version 3.2.

mode

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

Ändrad i version 3.13: I tidigare versioner var det ett heltal 1 eller 2.

mtime

Vid dekomprimering sätts detta attribut till den senaste tidsstämpeln i det senast lästa sidhuvudet. Det är ett heltal som innehåller antalet sekunder sedan Unix-epoken (00:00:00 UTC, 1 januari 1970). Det initiala värdet innan några rubriker läses är None.

name

Sökvägen till gzip-filen på disken, som en str eller bytes. Motsvarar utdata från os.fspath() på den ursprungliga indatasökvägen, utan någon annan normalisering, upplösning eller expansion.

Ändrad i version 3.1: Stöd för with statement har lagts till, liksom konstruktörsargumentet mtime och attributet mtime.

Ändrad i version 3.2: Stöd för zero-padded och unseekable-filer har lagts till.

Ändrad i version 3.3: Metoden io.BufferedIOBase.read1() är nu implementerad.

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

Ändrad i version 3.5: Lagt till stöd för att skriva godtyckliga bytesliknande objekt. Metoden read() accepterar nu ett argument av None.

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

Föråldrad sedan version 3.9: Att öppna GzipFile för skrivning utan att ange mode-argumentet är föråldrat.

Ändrad i version 3.12: Ta bort attributet filnamn, använd istället attributet name.

gzip.compress(data, compresslevel=9, *, mtime=0)

Komprimerar data och returnerar ett bytes-objekt som innehåller den komprimerade datan. compresslevel och mtime har samma betydelse som i GzipFile-konstruktören ovan, men mtime har standardvärdet 0 för reproducerbar utdata.

Tillagd i version 3.2.

Ändrad i version 3.8: Lagt till parametern mtime för reproducerbar utdata.

Ändrad i version 3.11: Hastigheten förbättras genom att all data komprimeras på en gång istället för i en ström. Anrop med mtime satt till 0 delegeras till zlib.compress() för bättre hastighet. I den här situationen kan utdata innehålla ett annat bytevärde för gzip-headerns ”OS” än 255 ”unknown” som tillhandahålls av den underliggande zlib-implementeringen.

Ändrad i version 3.13: OS-byten i gzip-headern är garanterat satt till 255 när den här funktionen används, vilket var fallet i 3.10 och tidigare.

Ändrad i version 3.14: Parametern mtime är nu 0 som standard för reproducerbara utdata. För det tidigare beteendet att använda aktuell tid, skicka None till mtime.

gzip.decompress(data)

Dekomprimerar data och returnerar ett bytes-objekt som innehåller de okomprimerade data. Den här funktionen kan dekomprimera gzip-data med flera medlemmar (flera gzip-block som sammanfogats). När det är säkert att data endast innehåller en medlem är funktionen zlib.decompress() med wbits satt till 31 snabbare.

Tillagd i version 3.2.

Ändrad i version 3.11: Hastigheten förbättras genom att medlemmar dekomprimeras på en gång i minnet istället för i en ström.

Exempel på användning

Exempel på hur man läser en komprimerad fil:

import gzip
with gzip.open('/home/joe/file.txt.gz', 'rb') as f:
    file_content = f.read()

Exempel på hur man skapar en komprimerad GZIP-fil:

import gzip
content = b"Lots of content here"
with gzip.open('/home/joe/file.txt.gz', 'wb') as f:
    f.write(content)

Exempel på hur man GZIP-komprimerar en befintlig fil:

import gzip
import shutil
with open('/home/joe/file.txt', 'rb') as f_in:
    with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:
        shutil.copyfileobj(f_in, f_out)

Exempel på hur man GZIP-komprimerar en binär sträng:

import gzip
s_in = b"Lots of content here"
s_out = gzip.compress(s_in)

Se även

Modul zlib

Den grundläggande datakomprimeringsmodulen som behövs för att stödja filformatet gzip.

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

Kommandoradsgränssnitt

Modulen gzip tillhandahåller ett enkelt kommandoradsgränssnitt för att komprimera eller dekomprimera filer.

När modulen gzip har körts behåller den inmatade filen/filerna.

Ändrad i version 3.8: Lägg till ett nytt kommandoradsgränssnitt med en användning. När du kör CLI är komprimeringsnivån som standard 6.

Alternativ för kommandoraden

file

Om file inte anges, läs från sys.stdin.

--fast

Anger den snabbaste komprimeringsmetoden (mindre komprimering).

--best

Anger den långsammaste komprimeringsmetoden (bästa komprimering).

-d, --decompress

Dekomprimerar den angivna filen.

-h, --help

Visa hjälpmeddelandet.