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
ochlzma
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 omTarFile
-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, visasCompressionError
.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'
accepterartarfile.open()
nyckelordsargumentet compresslevel (standard9
) för att ange filens komprimeringsnivå.För lägena
'w:xz'
,'x:xz'
och'w|xz'
accepterartarfile.open()
nyckelordsargumentet preset för att ange filens komprimeringsnivå.För lägena
'w:zst'
,'x:zst'
och'w|zst'
accepterartarfile.open()
nyckelordsargumentet level för att ange filens komprimeringsnivå. Nyckelordsargumentet options kan också skickas, vilket ger avancerade Zstandard-komprimeringsparametrar som beskrivs avCompressionParameter
. Nyckelordsargumentet zstd_dict kan skickas för att tillhandahålla enZstdDict
, 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 ettTarFile
-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 enread()
- ellerwrite()
-metod (beroende på mode) som arbetar med bytes. bufsize anger blockstorleken och standardvärdet är20 * 512
byte. Använd denna variant i kombination med t.ex.sys.stdin.buffer
, en socket file object eller en bandenhet. Ett sådantTarFile
-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 modulentarfile
kan läsa. name kan vara enstr
, 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.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 omTarFile.errorlevel
== 2
.
- exception tarfile.HeaderError¶
Utlöses av
TarInfo.frombuf()
om bufferten den hämtar är ogiltig.
- 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 avsys.getfilesystemencoding()
.
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ånGNU_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
ellerPAX_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 ärTrue
, 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 ärTrue
, 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 till3
(alla debug-meddelanden). Meddelandena skrivs tillsys.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 ärFalse
skrivs endast namnen på medlemmarna ut. Om det ärTrue
, 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 avgetmembers()
.Ändrad i version 3.5: Parametern members har lagts till.
- TarFile.next()¶
Returnerar nästa medlem i arkivet som ett
TarInfo
-objekt, närTarFile
öppnas för läsning. ReturnerarNone
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 somfilter='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 metodenextractall()
.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 ettio.BufferedReader
-objekt. För alla andra existerande medlemmar returnerasNone
. Om member inte finns i arkivet returnerasKeyError
.Ändrad i version 3.3: Returnerar ett
io.BufferedReader
-objekt.Ändrad i version 3.13: Det returnerade
io.BufferedReader
-objektet har attributetmode
som alltid är lika med'rb'
.
- TarFile.errorlevel: int¶
Om errorlevel är
0
ignoreras felen när du använderTarFile.extract()
ochTarFile.extractall()
. De visas dock som felmeddelanden i felsökningsutmatningen när debug är större än 0. Om1
(standard) visas alla dödliga fel somOSError
ellerFilterError
undantag. Om2
, kommer alla fel som inte är fatala också att visas somTarError
.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 ochExtractError
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()
ochextractall()
.Attributet kan vara
None
eller en callable. Strängnamn är inte tillåtna för detta attribut, till skillnad från filter-argumentet tillextract()
.Om
extraction_filter
ärNone
(standard) kommer extraktionsmetoderna att använda filtretdata
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å ellersite configuration
. För att ställa in en global standard på detta sätt måste en filterfunktion förpackas istaticmethod()
för att förhindra injektion av ettself
-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ällningenfully_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 ettTarInfo
-objekt och returnerar det ändradeTarInfo
-objektet. Om den istället returnerarNone
kommerTarInfo
-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, ochtarinfo.size
bytes läses från den och läggs till i arkivet. Du kan skapaTarInfo
-objekt direkt, eller genom att användagettarinfo()
.Ä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 avos.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:sname
-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 medaddfile()
. Om filobjektet inte är ett vanligt filobjekt som är placerat i början av filen, kan attribut somsize
behöva ändras. Detta är fallet för objekt somGzipFile
. Attributetname
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.
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()
ellerextractall()
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.
- 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 ettTarInfo
-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 klassenTarFile
.Ändrad i version 3.2: Använd
'surrogateescape'
som standard för errors-argumentet.
Ett TarInfo
-objekt har följande offentliga dataattribut:
- 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örextract()
ochextractall()
, 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örextract()
ochextractall()
, 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 ettTarInfo
-objekt mer bekvämt, användis*()
-metoderna nedan.
- TarInfo.linkname: str¶
Namnet på målfilens namn, som endast finns i
TarInfo
-objekt av typenLNKTYPE
ochSYMTYPE
.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örextract()
ochextractall()
, 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örextract()
ochextractall()
, 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örextract()
ochextractall()
, 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örextract()
ochextractall()
, vilket gör att extraktionen hoppar över att tillämpa detta attribut.
- 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 ettTarInfo
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 ursprungligaTarInfo
-objektet.
Ett TarInfo
-objekt innehåller också några praktiska frågemetoder:
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. Setar_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. Sedata_filter()
för mer information.None
(standard): AnvändTarFile.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 medfully_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, ellerreturnera
None
, i vilket fall medlemmen kommer att hoppas över, ellerskapa ett undantag för att avbryta operationen eller hoppa över medlemmen, beroende på
errorlevel
. Observera att när extraktionen avbryts kanextractall()
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 (
/
ochos.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 tillAbsolutePathError
.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 vadtar_filter
gör:Normalisera länkmål (
TarInfo.linkname
) med hjälp avos.path.normpath()
. Observera att detta tar bort interna..
-komponenter, vilket kan ändra betydelsen av länken om sökvägen iTarInfo.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
ellerLinkOutsideDestinationError
.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
tillNone
, så att extraktionsmetoderna hoppar över att tillämpa behörighetsbitar.Ställ in användar- och gruppinformation (
uid
,gid
,uname
,gname
) tillNone
, 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¶
- -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.
- -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ägafully_trusted
,tar
ochdata
).
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.