tarfile — Läsa och skriva tar-arkivfiler

Källkod: Lib/tarfile.py


Modulen tarfile gör det möjligt att läsa och skriva tar-arkiv, inklusive de som använder gzip-, bz2- och lzma-komprimering. Använd modulen zipfile för att läsa eller skriva .zip-filer, eller funktionerna på högre nivå i shutil.

Några fakta och siffror:

  • läser och skriver gzip, bz2, compression.zstd och lzma komprimerade arkiv om respektive modul är tillgänglig.

  • stöd för läsning/skrivning av formatet POSIX.1-1988 (ustar).

  • läs- och skrivstöd för GNU Tar-format inklusive tillägg longname och longlink, skrivskyddat stöd för alla varianter av tillägget sparse inklusive återställning av sparse-filer.

  • stöd för läsning/skrivning i formatet POSIX.1-2001 (pax).

  • hanterar kataloger, vanliga filer, hårda länkar, symboliska länkar, fifos, teckenenheter och blockenheter och kan hämta och återställa filinformation som tidsstämpel, åtkomstbehörighet och ägare.

Ändrad i version 3.3: Lagt till stöd för lzma-komprimering.

Ändrad i version 3.12: Arkiv extraheras med hjälp av ett filter, vilket gör det möjligt att antingen begränsa överraskande/farliga funktioner eller att bekräfta att de är förväntade och att arkivet är helt pålitligt.

Ändrad i version 3.14: Ställ in standardfiltret för extraktion till data, vilket inte tillåter vissa farliga funktioner som länkar till absoluta sökvägar eller sökvägar utanför destinationen. Tidigare var filterstrategin likvärdig med fully_trusted.

Ändrad i version 3.14: Lagt till stöd för Zstandard-komprimering med compression.zstd.

tarfile.open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)

Returnerar ett TarFile-objekt för sökvägen namn. För detaljerad information om TarFile-objekt och de nyckelordsargument som är tillåtna, se TarFile-objekt.

mode måste vara en sträng av formen 'filemode[:compression]', standardvärdet är 'r'. Här är en fullständig lista över lägeskombinationer:

läge

åtgärd

'r' eller 'r:*'

Öppna för läsning med transparent komprimering (rekommenderas).

'r:'

Öppet för läsning exklusivt utan komprimering.

'r:gz'

Öppna för läsning med gzip-komprimering.

'r:bz2'

Öppna för läsning med bzip2-komprimering.

'r:xz'

Öppet för läsning med lzma-komprimering.

'r:zst'

Öppna för läsning med Zstandard-komprimering.

'x' eller 'x:'

Skapa en tarfile uteslutande utan komprimering. Utlös ett FileExistsError undantag om den redan existerar.

'x:gz'

Skapa en tarfile med gzip-komprimering. Utlös ett FileExistsError undantag om den redan existerar.

'x:bz2'

Skapa en tarfile med bzip2-komprimering. Utlös ett FileExistsError undantag om den redan existerar.

'x:xz'

Skapa en tarfile med lzma-komprimering. Utlös ett FileExistsError undantag om den redan existerar.

'x:zst'

Skapa en tarfile med Zstandard-komprimering. Utlös ett FileExistsError undantag om den redan existerar.

'a' eller 'a:'

Öppna för att lägga till utan komprimering. Filen skapas om den inte redan finns.

'w' eller 'w:'

Öppet för okomprimerad skrivning.

'w:gz'

Öppet för gzip-komprimerad skrivning.

'w:bz2'

Öppet för bzip2-komprimerad skrivning.

'w:xz'

Öppet för lzma-komprimerad skrivning.

'w:zst'

Öppet för komprimerad skrivning enligt Zstandard.

Observera att 'a:gz', 'a:bz2' eller 'a:xz' inte är möjligt. Om mode inte är lämpligt för att öppna en viss (komprimerad) fil för läsning, ReadError. Använd mode 'r' för att undvika detta. Om en komprimeringsmetod inte stöds, visas CompressionError.

Om fileobj anges används det som ett alternativ till ett filobjekt som öppnats i binärt läge för namn. Det är tänkt att vara på position 0.

För lägena 'w:gz', 'x:gz', 'w|gz', 'w:bz2', 'x:bz2', 'w|bz2' accepterar tarfile.open() nyckelordsargumentet compresslevel (standard 9) för att ange filens komprimeringsnivå.

För lägena 'w:xz', 'x:xz' och 'w|xz' accepterar tarfile.open() nyckelordsargumentet preset för att ange filens komprimeringsnivå.

För lägena 'w:zst', 'x:zst' och 'w|zst' accepterar tarfile.open() nyckelordsargumentet level för att ange filens komprimeringsnivå. Nyckelordsargumentet options kan också skickas, vilket ger avancerade Zstandard-komprimeringsparametrar som beskrivs av CompressionParameter. Nyckelordsargumentet zstd_dict kan skickas för att tillhandahålla en ZstdDict, en Zstandard-ordbok som används för att förbättra komprimeringen av mindre datamängder.

För speciella ändamål finns det ett andra format för mode: 'filemode|[compression]'. tarfile.open() returnerar ett TarFile-objekt som behandlar sina data som en ström av block. Ingen slumpmässig sökning kommer att göras på filen. Om den anges kan fileobj vara vilket objekt som helst som har en read()- eller write()-metod (beroende på mode) som arbetar med bytes. bufsize anger blockstorleken och standardvärdet är 20 * 512 byte. Använd denna variant i kombination med t.ex. sys.stdin.buffer, en socket file object eller en bandenhet. Ett sådant TarFile-objekt är dock begränsat genom att det inte tillåter slumpmässig åtkomst, se Exempel. De för närvarande möjliga lägena:

Läge

Åtgärd

'r|*'

Öppna en ström av tar-block för läsning med transparent komprimering.

'r|'

Öppna en ström av okomprimerade tar-block för läsning.

'r|gz'

Öppna en gzip-komprimerad ström för läsning.

'r|bz2'

Öppna en bzip2-komprimerad ström för läsning.

'r|xz'

Öppna en lzma-komprimerad ström för läsning.

'r|zst'

Öppna en Zstandard-komprimerad ström för läsning.

'w|'

Öppna en okomprimerad ström för skrivning.

'w|gz'

Öppna en gzip-komprimerad ström för skrivning.

'w|bz2'

Öppna en bzip2-komprimerad ström för skrivning.

'w|xz'

Öppna en lzma-komprimerad ström för skrivning.

'w|zst'

Öppna en Zstandard-komprimerad ström för skrivning.

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

Ändrad i version 3.6: Parametern name accepterar en path-like object.

Ändrad i version 3.12: Nyckelordsargumentet compresslevel fungerar också för strömmar.

Ändrad i version 3.14: Nyckelordsargumentet preset fungerar också för strömmar.

class tarfile.TarFile

Klass för att läsa och skriva tar-arkiv. Använd inte denna klass direkt: använd tarfile.open() istället. Se TarFile-objekt.

tarfile.is_tarfile(name)

Returnerar True om namn är en tar-arkivfil som modulen tarfile kan läsa. name kan vara en str, en fil eller ett filliknande objekt.

Ändrad i version 3.9: Stöd för filer och filliknande objekt.

Modulen tarfile definierar följande undantag:

exception tarfile.TarError

Basklass för alla tarfile-undantag.

exception tarfile.ReadError

Uppstår när ett tar-arkiv öppnas, som antingen inte kan hanteras av modulen tarfile eller som på något sätt är ogiltigt.

exception tarfile.CompressionError

Visas när en komprimeringsmetod inte stöds eller när data inte kan avkodas på rätt sätt.

exception tarfile.StreamError

Uppstår på grund av de begränsningar som är typiska för strömliknande TarFile-objekt.

exception tarfile.ExtractError

Utlöses för icke-dödliga fel när du använder TarFile.extract(), men bara om TarFile.errorlevel== 2.

exception tarfile.HeaderError

Utlöses av TarInfo.frombuf() om bufferten den hämtar är ogiltig.

exception tarfile.FilterError

Basklass för medlemmar refused genom filter.

tarinfo

Information om den medlem som filtret vägrade att extrahera, som TarInfo.

exception tarfile.AbsolutePathError

Upphävd för att vägra extrahera en medlem med en absolut sökväg.

exception tarfile.OutsideDestinationError

Höjd för att vägra utdragning av en medlem utanför destinationskatalogen.

exception tarfile.SpecialFileError

Utlöses för att vägra extrahera en speciell fil (t.ex. en enhet eller ett rör).

exception tarfile.AbsoluteLinkError

Upphävdes för att vägra extrahera en symbolisk länk med en absolut sökväg.

exception tarfile.LinkOutsideDestinationError

Höjd för att vägra extrahera en symbolisk länk som pekar utanför destinationskatalogen.

exception tarfile.LinkFallbackError

Utlöstes för att vägra emulera en länk (hård eller symbolisk) genom att extrahera en annan arkivmedlem, när den medlemmen skulle avvisas av filterplatsen. Undantaget som utlöstes för att avvisa den ersättande medlemmen finns tillgängligt som BaseException.__context__.

Tillagd i version 3.14.

Följande konstanter är tillgängliga på modulnivå:

tarfile.ENCODING

Standardkodningen för tecken: 'utf-8' på Windows, annars det värde som returneras av sys.getfilesystemencoding().

tarfile.REGTYPE
tarfile.AREGTYPE

En vanlig fil type.

tarfile.LNKTYPE

En länk (inuti tarfile) type.

tarfile.SYMTYPE

En symbolisk länk type.

tarfile.CHRTYPE

En specialenhet för tecken type.

tarfile.BLKTYPE

En blockspecialenhet type.

tarfile.DIRTYPE

En katalog type.

tarfile.FIFOTYPE

En FIFO-specialenhet type.

tarfile.CONTTYPE

En sammanhängande fil type.

tarfile.GNUTYPE_LONGNAME

Ett GNU tar-långnamn type.

En GNU tar longlink type.

tarfile.GNUTYPE_SPARSE

En GNU tar sparse-fil type.

Var och en av följande konstanter definierar ett tar-arkivformat som modulen tarfile kan skapa. Se avsnitt Tar-format som stöds för mer information.

tarfile.USTAR_FORMAT

POSIX.1-1988 (ustar)-format.

tarfile.GNU_FORMAT

GNU tar-format.

tarfile.PAX_FORMAT

POSIX.1-2001 (pax)-format.

tarfile.DEFAULT_FORMAT

Standardformatet för att skapa arkiv. Detta är för närvarande PAX_FORMAT.

Ändrad i version 3.8: Standardformatet för nya arkiv ändrades till PAX_FORMAT från GNU_FORMAT.

Se även

Modul zipfile

Dokumentation av standardmodulen zipfile.

Arkiveringsverksamhet

Dokumentation av de arkiveringsmöjligheter på högre nivå som tillhandahålls av standardmodulen shutil.

GNU tar manual, Grundläggande Tar-format

Dokumentation för tar-arkivfiler, inklusive GNU tar-tillägg.

TarFile-objekt

Objektet TarFile tillhandahåller ett gränssnitt till ett tar-arkiv. Ett tar-arkiv är en sekvens av block. En arkivdel (en lagrad fil) består av ett header-block följt av datablock. Det är möjligt att lagra en fil i ett tar-arkiv flera gånger. Varje arkivmedlem representeras av ett TarInfo-objekt, se TarInfo-objekt för detaljer.

Ett TarFile-objekt kan användas som en kontexthanterare i en with-sats. Det kommer automatiskt att stängas när blocket är avslutat. Observera att i händelse av ett undantag kommer ett arkiv som öppnats för skrivning inte att slutföras; endast det internt använda filobjektet kommer att stängas. Se avsnittet Exempel för ett användningsfall.

Tillagd i version 3.2: Stöd för protokollet för kontexthantering har lagts till.

class tarfile.TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors='surrogateescape', pax_headers=None, debug=0, errorlevel=1, stream=False)

Alla följande argument är valfria och kan även användas som instansattribut.

name är sökvägsnamnet till arkivet. name kan vara en path-like object. Det kan utelämnas om fileobj anges. I så fall används filobjektets attribut name om det finns.

mode är antingen 'r' för att läsa från ett befintligt arkiv, 'a' för att lägga till data till en befintlig fil, 'w' för att skapa en ny fil som skriver över en befintlig, eller 'x' för att skapa en ny fil endast om den inte redan finns.

Om fileobj anges används den för att läsa eller skriva data. Om det kan fastställas åsidosätts mode av fileobj:s mode. fileobj kommer att användas från position 0.

Anteckning

fileobj är inte stängd, när TarFile är stängd.

format styr arkivformatet för skrivning. Det måste vara en av konstanterna USTAR_FORMAT, GNU_FORMAT eller PAX_FORMAT som definieras på modulnivå. Vid läsning kommer formatet att upptäckas automatiskt, även om olika format finns i ett och samma arkiv.

Argumentet tarinfo kan användas för att ersätta standardklassen TarInfo med en annan.

Om dereference är False, lägg till symboliska och hårda länkar i arkivet. Om det är True, lägg till innehållet i målfilerna i arkivet. Detta har ingen effekt på system som inte stöder symboliska länkar.

Om ignore_zeros är False, behandlas ett tomt block som slutet på arkivet. Om det är True, hoppa över tomma (och ogiltiga) block och försök att få med så många medlemmar som möjligt. Detta är endast användbart för att läsa sammanlänkade eller skadade arkiv.

debug kan ställas in från 0 (inga debug-meddelanden) upp till 3 (alla debug-meddelanden). Meddelandena skrivs till sys.stderr.

errorlevel styr hur extraktionsfel ska hanteras, se motsvarande attribut.

Argumenten encoding och errors definierar den teckenkodning som ska användas för att läsa eller skriva arkivet och hur konverteringsfel ska hanteras. Standardinställningarna fungerar för de flesta användare. Se avsnitt Unicode-problem för mer ingående information.

Argumentet pax_headers är en valfri ordlista med strängar som kommer att läggas till som en global pax-header om format är PAX_FORMAT.

Om stream är inställd på True så cachelagras inte information om filer i arkivet när arkivet läses, vilket sparar minne.

Ändrad i version 3.2: Använd 'surrogateescape' som standard för errors-argumentet.

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

Ändrad i version 3.6: Parametern name accepterar en path-like object.

Ändrad i version 3.13: Lägg till parametern stream.

classmethod TarFile.open(...)

Alternativ konstruktör. Funktionen tarfile.open() är egentligen en genväg till denna klassmetod.

TarFile.getmember(name)

Returnerar ett TarInfo-objekt för medlemmen namn. Om namn inte kan hittas i arkivet, KeyError tas upp.

Anteckning

Om en medlem förekommer mer än en gång i arkivet, antas den senaste förekomsten vara den mest aktuella versionen.

TarFile.getmembers()

Returnerar medlemmarna i arkivet som en lista av TarInfo-objekt. Listan har samma ordning som medlemmarna i arkivet.

TarFile.getnames()

Returnerar medlemmarna som en lista med deras namn. Den har samma ordning som den lista som returneras av getmembers().

TarFile.list(verbose=True, *, members=None)

Skriver ut en innehållsförteckning till sys.stdout. Om verbose är False skrivs endast namnen på medlemmarna ut. Om det är True, skrivs ut liknande det som görs av ls -l. Om members anges måste det vara en delmängd av den lista som returneras av getmembers().

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

TarFile.next()

Returnerar nästa medlem i arkivet som ett TarInfo-objekt, när TarFile öppnas för läsning. Returnerar None om det inte finns mer tillgängligt.

TarFile.extractall(path='.', members=None, *, numeric_owner=False, filter=None)

Extraherar alla medlemmar från arkivet till den aktuella arbetskatalogen eller katalogen path. Om members anges som tillval måste det vara en delmängd av listan som returneras av getmembers(). Kataloginformation som ägare, ändringstid och behörigheter anges efter att alla medlemmar har extraherats. Detta görs för att komma runt två problem: En katalogs modifieringstid nollställs varje gång en fil skapas i den. Och om en katalogs behörigheter inte tillåter skrivning kommer det att misslyckas att extrahera filer till den.

Om numeric_owner är True används uid- och gid-numren från tarfilen för att ange ägare/grupp för de extraherade filerna. I annat fall används de namngivna värdena från tarfilen.

Argumentet filter anger hur medlemmar modifieras eller avvisas före extraktion. Se Filter för utsugning för detaljer. Det rekommenderas att endast ange detta explicit om specifika tar-funktioner krävs, eller som filter='data' för att stödja Python-versioner med en mindre säker standard (3.13 och lägre).

Varning

Hämta aldrig ut arkiv från otillförlitliga källor utan föregående kontroll.

Sedan Python 3.14 kommer standard (data) att förhindra de farligaste säkerhetsproblemen. Det kommer dock inte att förhindra alla oavsiktliga eller osäkra beteenden. Läs avsnittet Filter för utsugning för mer information.

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

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

Ändrad i version 3.12: Parametern filter har lagts till.

Ändrad i version 3.14: Parametern filter har nu 'data' som standard.

TarFile.extract(member, path='', set_attrs=True, *, numeric_owner=False, filter=None)

Extrahera en medlem från arkivet till den aktuella arbetskatalogen med hjälp av dess fullständiga namn. Dess filinformation extraheras så exakt som möjligt. member kan vara ett filnamn eller ett TarInfo-objekt. Du kan ange en annan katalog med hjälp av sökväg. path kan vara ett path-like object. Filattribut (ägare, mtime, mode) anges om inte set_attrs är false.

Argumenten numeric_owner och filter är desamma som för extractall().

Anteckning

Metoden extract() tar inte hand om flera extraktionsproblem. I de flesta fall bör du överväga att använda metoden extractall().

Varning

Extrahera aldrig arkiv från otillförlitliga källor utan föregående inspektion. Se varningen för extractall() för detaljer.

Ändrad i version 3.2: Parametern set_attrs har lagts till.

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

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

Ändrad i version 3.12: Parametern filter har lagts till.

TarFile.extractfile(member)

Extraherar en medlem från arkivet som ett filobjekt. member kan vara ett filnamn eller ett TarInfo-objekt. Om medlem är en vanlig fil eller en länk returneras ett io.BufferedReader-objekt. För alla andra existerande medlemmar returneras None. Om member inte finns i arkivet returneras KeyError.

Ändrad i version 3.3: Returnerar ett io.BufferedReader-objekt.

Ändrad i version 3.13: Det returnerade io.BufferedReader-objektet har attributet mode som alltid är lika med 'rb'.

TarFile.errorlevel: int

Om errorlevel är 0 ignoreras felen när du använder TarFile.extract() och TarFile.extractall(). De visas dock som felmeddelanden i felsökningsutmatningen när debug är större än 0. Om 1 (standard) visas alla dödliga fel som OSError eller FilterError undantag. Om 2, kommer alla fel som inte är fatala också att visas som TarError.

Vissa undantag, t.ex. sådana som orsakas av fel argumenttyper eller datakorruption, tas alltid upp.

Anpassade extraktionsfilter bör ge upphov till FilterError för dödliga fel och ExtractError för icke-dödliga fel.

Observera att när ett undantag uppstår kan arkivet vara delvis extraherat. Det är användarens ansvar att städa upp.

TarFile.extraction_filter

Tillagd i version 3.12.

Filtret extraction filter används som standard för filter-argumentet i extract() och extractall().

Attributet kan vara None eller en callable. Strängnamn är inte tillåtna för detta attribut, till skillnad från filter-argumentet till extract().

Om extraction_filter är None (standard) kommer extraktionsmetoderna att använda filtret data som standard.

Attributet kan ställas in på instanser eller åsidosättas i underklasser. Det är också möjligt att ställa in det på TarFile-klassen själv för att ställa in en global standard, men eftersom det påverkar alla användningar av tarfile, är det bästa praxis att bara göra det i applikationer på högsta nivå eller site configuration. För att ställa in en global standard på detta sätt måste en filterfunktion förpackas i staticmethod() för att förhindra injektion av ett self-argument.

Ändrad i version 3.14: Standardfiltret är inställt på data, vilket inte tillåter vissa farliga funktioner som länkar till absoluta sökvägar eller sökvägar utanför destinationen. Tidigare motsvarade standardinställningen fully_trusted.

TarFile.add(name, arcname=None, recursive=True, *, filter=None)

Lägger till filen namn i arkivet. name kan vara vilken typ av fil som helst (katalog, fifo, symbolisk länk etc.). Om det anges anger arcname ett alternativt namn för filen i arkivet. Kataloger läggs till rekursivt som standard. Detta kan undvikas genom att ställa in recursive till False. Rekursion lägger till poster i sorterad ordning. Om filter anges bör det vara en funktion som tar ett argument i form av ett TarInfo-objekt och returnerar det ändrade TarInfo-objektet. Om den istället returnerar None kommer TarInfo-objektet att uteslutas från arkivet. Se Exempel för ett exempel.

Ändrad i version 3.2: Parametern filter har lagts till.

Ändrad i version 3.7: Recursion lägger till poster i sorterad ordning.

TarFile.addfile(tarinfo, fileobj=None)

Lägg till TarInfo-objektet tarinfo i arkivet. Om tarinfo representerar en vanlig fil som inte är nollstor, bör argumentet fileobj vara en binary file, och tarinfo.size bytes läses från den och läggs till i arkivet. Du kan skapa TarInfo-objekt direkt, eller genom att använda gettarinfo().

Ändrad i version 3.13: fileobj måste anges för vanliga filer som inte är nollstorlekar.

TarFile.gettarinfo(name=None, arcname=None, fileobj=None)

Skapar ett TarInfo-objekt från resultatet av os.stat() eller motsvarande på en befintlig fil. Filen är antingen namngiven med name, eller specificerad som ett file object fileobj med en filbeskrivare. name kan vara ett path-like object. Om det anges, anger arcname ett alternativt namn för filen i arkivet, annars hämtas namnet från fileobj:s name-attribut eller argumentet name. Namnet bör vara en textsträng.

Du kan modifiera några av TarInfo:s attribut innan du lägger till det med addfile(). Om filobjektet inte är ett vanligt filobjekt som är placerat i början av filen, kan attribut som size behöva ändras. Detta är fallet för objekt som GzipFile. Attributet name kan också behöva ändras, och i så fall kan arcname vara en dummysträng.

Ändrad i version 3.6: Parametern name accepterar en path-like object.

TarFile.close()

Stäng TarFile. I skrivläge läggs två avslutande nollblock till i arkivet.

TarFile.pax_headers: dict

En ordbok som innehåller nyckel-värde-par av globala pax-huvuden.

TarInfo-objekt

Ett TarInfo-objekt representerar en medlem i en TarFile. Förutom att lagra alla nödvändiga attribut för en fil (som filtyp, storlek, tid, behörigheter, ägare etc.), innehåller den några användbara metoder för att bestämma dess typ. Den innehåller inte själva filens data.

TarInfo-objekt returneras av TarFile:s metoder getmember(), getmembers() och gettarinfo().

Modifiering av de objekt som returneras av getmember() eller getmembers() kommer att påverka alla efterföljande operationer på arkivet. I fall där detta inte är önskvärt kan du använda copy.copy() eller anropa metoden replace() för att skapa en modifierad kopia i ett steg.

Flera attribut kan sättas till None för att ange att en del av metadata är oanvänd eller okänd. Olika TarInfo-metoder hanterar None på olika sätt:

  • Metoderna extract() eller extractall() ignorerar motsvarande metadata och låter dem vara inställda på ett standardvärde.

  • addfile() kommer att misslyckas.

  • list() skriver ut en platshållarsträng.

class tarfile.TarInfo(name='')

Skapa ett TarInfo-objekt.

classmethod TarInfo.frombuf(buf, encoding, errors)

Skapa och returnera ett TarInfo-objekt från strängbufferten buf.

Utlöser HeaderError om bufferten är ogiltig.

classmethod TarInfo.fromtarfile(tarfile)

Läs nästa medlem från TarFile-objektet tarfile och returnera den som ett TarInfo-objekt.

TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='surrogateescape')

Skapar en strängbuffert från ett TarInfo-objekt. För information om argumenten se konstruktören för klassen TarFile.

Ändrad i version 3.2: Använd 'surrogateescape' som standard för errors-argumentet.

Ett TarInfo-objekt har följande offentliga dataattribut:

TarInfo.name: str

Namn på arkivmedlem.

TarInfo.size: int

Storlek i byte.

TarInfo.mtime: int | float

Tidpunkt för senaste ändring i sekunder sedan epoch, som i os.stat_result.st_mtime.

Ändrad i version 3.12: Kan sättas till None för extract() och extractall(), vilket gör att extraktionen hoppar över att tillämpa detta attribut.

TarInfo.mode: int

Behörighetsbitar, som för os.chmod().

Ändrad i version 3.12: Kan sättas till None för extract() och extractall(), vilket gör att extraktionen hoppar över att tillämpa detta attribut.

TarInfo.type

Filtyp. type är vanligtvis en av dessa konstanter: REGTYPE, AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, CONTTYPE, CHRTYPE, BLKTYPE, GNUTYPE_SPARSE. För att bestämma typen av ett TarInfo-objekt mer bekvämt, använd is*()-metoderna nedan.

TarInfo.linkname: str

Namnet på målfilens namn, som endast finns i TarInfo-objekt av typen LNKTYPE och SYMTYPE.

För symboliska länkar (SYMTYPE) är länknamnet relativt till den katalog som innehåller länken. För hårda länkar (LNKTYPE) är länknamnet relativt till arkivets rot.

TarInfo.uid: int

Användar-ID för den användare som ursprungligen lagrade den här medlemmen.

Ändrad i version 3.12: Kan sättas till None för extract() och extractall(), vilket gör att extraktionen hoppar över att tillämpa detta attribut.

TarInfo.gid: int

Grupp-ID för den användare som ursprungligen lagrade den här medlemmen.

Ändrad i version 3.12: Kan sättas till None för extract() och extractall(), vilket gör att extraktionen hoppar över att tillämpa detta attribut.

TarInfo.uname: str

Användarnamn.

Ändrad i version 3.12: Kan sättas till None för extract() och extractall(), vilket gör att extraktionen hoppar över att tillämpa detta attribut.

TarInfo.gname: str

Gruppens namn.

Ändrad i version 3.12: Kan sättas till None för extract() och extractall(), vilket gör att extraktionen hoppar över att tillämpa detta attribut.

TarInfo.chksum: int

Kontrollsumma för huvud.

TarInfo.devmajor: int

Enhetens huvudnummer.

TarInfo.devminor: int

Enhetens mindre nummer.

TarInfo.offset: int

Tjärhuvudet börjar här.

TarInfo.offset_data: int

Filens data börjar här.

TarInfo.sparse

Gles medlemsinformation.

TarInfo.pax_headers: dict

En ordbok som innehåller nyckel-värdepar för en associerad pax extended header.

TarInfo.replace(name=..., mtime=..., mode=..., linkname=..., uid=..., gid=..., uname=..., gname=..., deep=True)

Tillagd i version 3.12.

Returnerar en ny kopia av TarInfo-objektet med de angivna attributen ändrade. För att till exempel returnera ett TarInfo med gruppnamnet satt till 'staff', använd:

new_tarinfo = old_tarinfo.replace(gname='staff')

Som standard görs en djup kopia. Om deep är false är kopian ytlig, dvs. pax_headers och eventuella anpassade attribut delas med det ursprungliga TarInfo-objektet.

Ett TarInfo-objekt innehåller också några praktiska frågemetoder:

TarInfo.isfile()

Returnerar True om TarInfo-objektet är en vanlig fil.

TarInfo.isreg()

Samma som isfile().

TarInfo.isdir()

Returnerar True om det är en katalog.

TarInfo.issym()

Returnerar True om det är en symbolisk länk.

TarInfo.islnk()

Returnerar True om det är en hård länk.

TarInfo.ischr()

Returnerar True om det är en teckenenhet.

TarInfo.isblk()

Returnerar True om det är en blockenhet.

TarInfo.isfifo()

Returnerar True om det är en FIFO.

TarInfo.isdev()

Returnerar True om det är en av character device, block device eller FIFO.

Filter för utsugning

Tillagd i version 3.12.

tar-formatet är utformat för att fånga alla detaljer i ett UNIX-liknande filsystem, vilket gör det mycket kraftfullt. Tyvärr gör funktionerna att det är lätt att skapa tar-filer som har oavsiktliga - och eventuellt skadliga - effekter när de extraheras. När en tar-fil extraheras kan den till exempel skriva över godtyckliga filer på olika sätt (t.ex. genom att använda absoluta sökvägar, .. sökvägskomponenter eller symlänkar som påverkar senare medlemmar).

I de flesta fall behövs inte hela funktionaliteten. Därför stöder tarfile extraktionsfilter: en mekanism för att begränsa funktionaliteten och därmed mildra vissa av säkerhetsproblemen.

Varning

Inget av de tillgängliga filtren blockerar alla farliga arkivfunktioner. Extrahera aldrig arkiv från otillförlitliga källor utan föregående inspektion. Se även Tips för ytterligare verifiering.

Se även

PEP 706

Innehåller ytterligare motivering och skälen bakom designen.

Argumentet filter till TarFile.extract() eller extractall() kan vara:

  • strängen 'fully_trusted': Respekterar alla metadata som anges i arkivet. Bör användas om användaren litar helt på arkivet eller implementerar sin egen komplexa verifiering.

  • strängen 'tar': Hedrar de flesta tar-specifika funktioner (dvs. funktioner i UNIX-liknande filsystem), men blockerar funktioner som med stor sannolikhet är överraskande eller skadliga. Se tar_filter() för detaljer.

  • strängen 'data': Ignorera eller blockera de flesta funktioner som är specifika för UNIX-liknande filsystem. Avsedd för utvinning av plattformsoberoende dataarkiv. Se data_filter() för mer information.

  • None (standard): Använd TarFile.extraction_filter.

    Om det också är None (standard), kommer filtret 'data att användas.

    Ändrad i version 3.14: Standardfiltret är inställt på data. Tidigare var standardvärdet likvärdigt med fully_trusted.

  • En callable som kommer att anropas för varje extraherad medlem med en TarInfo som beskriver medlemmen och destinationssökvägen till där arkivet extraheras (dvs. samma sökväg används för alla medlemmar):

    filter(medlem: TarInfo, sökväg: str, /) -> TarInfo | Ingen
    

    Callable anropas precis innan varje medlem extraheras, så att den kan ta hänsyn till diskens aktuella tillstånd. Det kan den göra:

    • returnera ett TarInfo-objekt som kommer att användas istället för metadata i arkivet, eller

    • returnera None, i vilket fall medlemmen kommer att hoppas över, eller

    • skapa ett undantag för att avbryta operationen eller hoppa över medlemmen, beroende på errorlevel. Observera att när extraktionen avbryts kan extractall() lämna arkivet delvis extraherat. Den försöker inte städa upp.

Namngivna standardfilter

De fördefinierade, namngivna filtren är tillgängliga som funktioner, så att de kan återanvändas i anpassade filter:

tarfile.fully_trusted_filter(member, path)

Returnera medlem oförändrad.

Detta implementerar filtret 'fully_trusted'.

tarfile.tar_filter(member, path)

Implementerar filtret 'tar'.

  • Ta bort ledande snedstreck (/ och os.sep) från filnamn.

  • Refuse för att extrahera filer med absoluta sökvägar (om namnet är absolut även efter borttagning av snedstreck, t.ex. C:/foo på Windows). Detta ger upphov till AbsolutePathError.

  • Refuse för att extrahera filer vars absoluta sökväg (efter att ha följt symlänkar) skulle hamna utanför destinationen. Detta ger upphov till OutsideDestinationError.

  • Rensa höglägesbitar (setuid, setgid, sticky) och skrivbitar för grupp/annat (S_IWGRP | S_IWOTH).

Returnerar den modifierade TarInfo-medlemmen.

tarfile.data_filter(member, path)

Implementerar filtret 'data. Utöver vad tar_filter gör:

  • Normalisera länkmål (TarInfo.linkname) med hjälp av os.path.normpath(). Observera att detta tar bort interna ..-komponenter, vilket kan ändra betydelsen av länken om sökvägen i TarInfo.linkname passerar symboliska länkar.

  • Refuse för att extrahera länkar (hårda eller mjuka) som länkar till absoluta sökvägar, eller sådana som länkar utanför destinationen.

    Detta ger upphov till AbsoluteLinkError eller LinkOutsideDestinationError.

    Observera att sådana filer nekas även på plattformar som inte stöder symboliska länkar.

  • Refuse för att extrahera enhetsfiler (inklusive pipes). Detta ger upphov till SpecialFileError.

  • För vanliga filer, inklusive hårda länkar:

  • För andra filer (kataloger), sätt mode till None, så att extraktionsmetoderna hoppar över att tillämpa behörighetsbitar.

  • Ställ in användar- och gruppinformation (uid, gid, uname, gname) till None, så att extraktionsmetoderna hoppar över att ställa in den.

Returnerar den modifierade TarInfo-medlemmen.

Observera att detta filter inte blockerar alla farliga arkivfunktioner. Se Tips för ytterligare verifiering för mer information.

Ändrad i version 3.14: Länkmålen är nu normaliserade.

Fel i filter

När ett filter vägrar att extrahera en fil kommer det att ge upphov till ett lämpligt undantag, en underklass till FilterError. Detta kommer att avbryta extraktionen om TarFile.errorlevel är 1 eller mer. Med errorlevel=0 kommer felet att loggas och medlemmen kommer att hoppas över, men extraktionen kommer att fortsätta.

Tips för ytterligare verifiering

Även med filter='data' är tarfile inte lämpad för att extrahera otillförlitliga filer utan föregående inspektion. Bland annat förhindrar de fördefinierade filtren inte överbelastningsattacker. Användare bör göra ytterligare kontroller.

Här är en ofullständig lista på saker att tänka på:

  • Extrahera till en ny temporär katalog för att förhindra t.ex. utnyttjande av redan existerande länkar och för att göra det lättare att städa upp efter en misslyckad extrahering.

  • Avvisa symboliska länkar om du inte behöver funktionen.

  • När du arbetar med otillförlitliga data ska du använda externa begränsningar (t.ex. på OS-nivå) för disk-, minnes- och CPU-användning.

  • Kontrollera filnamn mot en lista med tillåtna tecken (för att filtrera bort kontrolltecken, förväxlingsbara tecken, utländska sökvägsseparatorer och så vidare).

  • Kontrollera att filnamnen har förväntade tillägg (avråda från filer som körs när du ”klickar på dem” eller filer utan tillägg som Windows speciella enhetsnamn).

  • Begränsa antalet extraherade filer, total storlek på extraherade data, filnamnslängd (inklusive symlänkslängd) och storlek på enskilda filer.

  • Kontrollera om det finns filer som skulle skuggas på filsystem som inte tar hänsyn till skiftlägeskänslighet.

Observera också detta:

  • Tar-filer kan innehålla flera versioner av samma fil. De senare versionerna förväntas skriva över alla tidigare versioner. Denna funktion är avgörande för att kunna uppdatera bandarkiv, men kan missbrukas på ett illvilligt sätt.

  • tarfile skyddar inte mot problem med ”levande” data, t.ex. om en angripare mixtrar med målkatalogen (eller källkatalogen) medan extrahering (eller arkivering) pågår.

Stöd för äldre Python-versioner

Extraktionsfilter lades till i Python 3.12, men kan vara backporterade till äldre versioner som säkerhetsuppdateringar. För att kontrollera om funktionen är tillgänglig, använd t.ex. hasattr(tarfile, 'data_filter') i stället för att kontrollera Python-versionen.

Följande exempel visar hur man stöder Python-versioner med och utan denna funktion. Observera att inställningen av extraction_filter kommer att påverka alla efterföljande operationer.

  • Fullt betrott arkiv:

    my_tarfile.extraction_filter = (lambda medlem, sökväg: medlem)
    my_tarfile.extrahera()
    
  • Använd filtret 'data' om det finns tillgängligt, men återgå till Python 3.11-beteende ('fully_trusted') om den här funktionen inte är tillgänglig:

    my_tarfile.extraction_filter = getattr(tarfile, 'data_filter',
                                           (lambda medlem, sökväg: medlem))
    my_tarfile.extractall()
    
  • Använd filtret 'data'; fail om det inte är tillgängligt:

    my_tarfile.extractall(filter=tarfile.data_filter)
    

    eller:

    my_tarfile.extraction_filter = tarfile.data_filter
    my_tarfile.extraheraall()
    
  • Använd filtret 'data'; varna om det inte är tillgängligt:

    if hasattr(tarfile, 'data_filter'):
        my_tarfile.extractall(filter='data')
    else:
        # ta bort detta när det inte längre behövs
        warn_the_user('Extrahering kan vara osäkert; överväg att uppdatera Python')
        my_tarfile.extractall()
    

Exempel på filter för statlig extraktion

Medan tarfile:s extraktionsmetoder tar en enkel filter callable, kan anpassade filter vara mer komplexa objekt med ett internt tillstånd. Det kan vara användbart att skriva dessa som kontexthanterare, som kan användas så här:

med StatefulFilter() som filter_func:
    tar.extractall(sökväg, filter=filter_func)

Ett sådant filter kan till exempel skrivas som:

klass StatefulFilter:
    def __init__(self):
        self.file_count = 0

    def __enter__(self):
        return self

    def __call__(self, medlem, sökväg):
        self.file_count += 1
        returnera medlem

    def __exit__(self, *exc_info):
        print(f'{self.file_count} filer extraherade')

Kommandoradsgränssnitt

Tillagd i version 3.4.

Modulen tarfile tillhandahåller ett enkelt kommandoradsgränssnitt för att interagera med tar-arkiv.

Om du vill skapa ett nytt tar-arkiv anger du dess namn efter alternativet -c och listar sedan filnamnen som ska inkluderas:

$ python -m tarfile -c monty.tar spam.txt eggs.txt

Att skicka en katalog är också acceptabelt:

$ python -m tarfile -c monty.tar life-of-brian_1979/

Om du vill extrahera ett tar-arkiv till den aktuella katalogen använder du alternativet -e:

$ python -m tarfile -e monty.tar

Du kan också extrahera ett tar-arkiv till en annan katalog genom att ange katalogens namn:

$ python -m tarfile -e monty.tar annan-dir/

Om du vill ha en lista över filerna i ett tar-arkiv använder du alternativet -l:

$ python -m tarfile -l monty.tar

Alternativ för kommandoraden

-l <tarfile>
--list <tarfile>

Lista filer i en tarfile.

-c <tarfile> <source1> ... <sourceN>
--create <tarfile> <source1> ... <sourceN>

Skapa tarfile från källfilerna.

-e <tarfile> [<output_dir>]
--extract <tarfile> [<output_dir>]

Extrahera tarfilen till den aktuella katalogen om output_dir inte har angetts.

-t <tarfile>
--test <tarfile>

Testa om tarfilen är giltig eller inte.

-v, --verbose

Verbose-utdata.

--filter <filtername>

Anger filter för --extract. Se Filter för utsugning för detaljer. Endast strängnamn accepteras (det vill säga fully_trusted, tar och data).

Exempel

Exempel på läsning

Så här extraherar du ett helt tar-arkiv till den aktuella arbetskatalogen:

import tarfile
tar = tarfile.open("sample.tar.gz")
tar.extractall(filter='data')
tar.close()

Hur man extraherar en delmängd av ett tararkiv med TarFile.extractall() med hjälp av en generatorfunktion istället för en lista:

import os
import tarfile

def py_files(members):
    for tarinfo in members:
        if os.path.splitext(tarinfo.name)[1] == ".py":
            yield tarinfo

tar = tarfile.open("sample.tar.gz")
tar.extractall(members=py_files(tar))
tar.close()

Så här läser du ett gzip-komprimerat tar-arkiv och visar viss medlemsinformation:

import tarfile
tar = tarfile.open("sample.tar.gz", "r:gz")
för tarinfo i tar:
    print(tarinfo.name,"är", tarinfo.size,"bytes i storlek och är ", end="")
    if tarinfo.isreg():
        print("en vanlig fil.")
    elif tarinfo.isdir():
        print("en katalog.")
    annat:
        print("något annat.")
tar.close()

Exempel på skrivande

Hur man skapar ett okomprimerat tar-arkiv från en lista med filnamn:

import tarfile
tar = tarfile.open("sample.tar", "w")
for name in ["foo", "bar", "quux"]:
    tar.add(name)
tar.close()

Samma exempel med with-satsen:

import tarfile
with tarfile.open("sample.tar", "w") as tar:
    for name in ["foo", "bar", "quux"]:
        tar.add(name)

Hur man skapar och skriver ett arkiv till stdout med hjälp av sys.stdout.buffer i parametern fileobj i TarFile.add():

import sys
import tarfile
with tarfile.open("sample.tar.gz", "w|gz", fileobj=sys.stdout.buffer) as tar:
    for name in ["foo", "bar", "quux"]:
        tar.add(name)

Så här skapar du ett arkiv och återställer användarinformationen med parametern filter i TarFile.add():

import tarfile
def reset(tarinfo):
    tarinfo.uid = tarinfo.gid = 0
    tarinfo.uname = tarinfo.gname = "root"
    return tarinfo
tar = tarfile.open("sample.tar.gz", "w:gz")
tar.add("foo", filter=reset)
tar.close()

Tar-format som stöds

Det finns tre olika tar-format som kan skapas med modulen tarfile:

  • POSIX.1-1988 ustar-format (USTAR_FORMAT). Det stöder filnamn upp till en längd av 256 tecken och länknamn upp till 100 tecken. Den maximala filstorleken är 8 GiB. Det här är ett gammalt och begränsat format som dock har brett stöd.

  • GNU:s tar-format (GNU_FORMAT). Det stöder långa filnamn och länknamn, filer större än 8 GiB och glesa filer. Det är de facto-standarden på GNU/Linux-system. tarfile har fullt stöd för GNU:s tar-tillägg för långa namn, stödet för glesa filer är skrivskyddat.

  • POSIX.1-2001 pax-formatet (PAX_FORMAT). Det är det mest flexibla formatet med praktiskt taget inga begränsningar. Det stöder långa filnamn och länknamn, stora filer och lagrar sökvägsnamn på ett portabelt sätt. Moderna tar-implementeringar, inklusive GNU tar, bsdtar/libarchive och star, har fullt stöd för utökade pax-funktioner; vissa gamla eller ounderhållna bibliotek kanske inte har det, men bör behandla pax-arkiv som om de vore i det allmänt stödda ustar-formatet. Det är det nuvarande standardformatet för nya arkiv.

    Det utökar det befintliga ustar-formatet med extra rubriker för information som inte kan lagras på annat sätt. Det finns två varianter av pax-rubriker: Extended headers påverkar endast efterföljande filhuvud, global headers gäller för hela arkivet och påverkar alla efterföljande filer. Alla data i en pax-header är kodade i UTF-8 av portabilitetsskäl.

Det finns ytterligare några varianter av tar-formatet som kan läsas, men inte skapas:

  • Det gamla V7-formatet. Detta är det första tar-formatet från Unix Seventh Edition, som endast lagrar vanliga filer och kataloger. Namnen får inte vara längre än 100 tecken, det finns ingen information om användar-/gruppnamn. Vissa arkiv har felberäknat kontrollsummor för rubriker i fält med icke-ASCII-tecken.

  • Det utökade SunOS tar-formatet. Detta format är en variant av POSIX.1-2001 pax-formatet, men är inte kompatibelt.

Unicode-problem

Tar-formatet utvecklades ursprungligen för att göra säkerhetskopior på bandstationer med huvudfokus på att bevara information om filsystemet. Numera används tar-arkiv ofta för distribution av filer och för att utbyta arkiv över nätverk. Ett problem med det ursprungliga formatet (som ligger till grund för alla andra format) är att det inte finns något koncept för att stödja olika teckenkodningar. Ett vanligt tar-arkiv som skapats på ett UTF-8-system kan t.ex. inte läsas korrekt på ett Latin-1-system om det innehåller tecken som inte är ASCII-tecken. Textuella metadata (t.ex. filnamn, länknamn, användar-/gruppnamn) kommer att skadas. Tyvärr finns det inget sätt att autodetektera kodningen av ett arkiv. Pax-formatet har utformats för att lösa detta problem. Det lagrar icke-ASCII-metadata med hjälp av den universella teckenkodningen UTF-8.

Detaljerna för teckenkonvertering i tarfile styrs av nyckelordsargumenten encoding och errors i klassen TarFile.

encoding definierar den teckenkodning som ska användas för metadata i arkivet. Standardvärdet är sys.getfilesystemencoding() eller 'ascii' som reserv. Beroende på om arkivet läses eller skrivs måste metadata antingen avkodas eller kodas. Om encoding inte är korrekt inställd kan konverteringen misslyckas.

Argumentet errors definierar hur tecken som inte kan konverteras ska behandlas. Möjliga värden listas i avsnitt Felhanterare. Standardschemat är 'surrogateescape' som Python också använder för sina filsystemanrop, se Filnamn, kommandoradsargument och miljövariabler.

För PAX_FORMAT-arkiv (standard) behövs encoding i allmänhet inte eftersom alla metadata lagras med UTF-8. encoding används endast i de sällsynta fall då binära pax-rubriker avkodas eller då strängar med surrogattecken lagras.