tarfile — Lese und schreibe Tar-Archivdateien

Quellcode: Lib/tarfile.py

Das Modul tarfile ermöglicht das Lesen und Schreiben von Tar-Archiven, einschließlich derjenigen, die gzip-, bz2- und lzma-Kompression verwenden. Verwenden Sie das Modul zipfile, um .zip-Dateien zu lesen oder zu schreiben, oder die höherstufigen Funktionen in shutil.

Einige Fakten und Zahlen

  • liest und schreibt gzip, bz2, compression.zstd und lzma komprimierte Archive, wenn die jeweiligen Module verfügbar sind.

  • Lese-/Schreibunterstützung für das POSIX.1-1988 (ustar)-Format.

  • Lese-/Schreibunterstützung für das GNU tar-Format einschließlich der Erweiterungen longname und longlink, Leseunterstützung für alle Varianten der sparse-Erweiterung, einschließlich der Wiederherstellung von Sparse-Dateien.

  • Lese-/Schreibunterstützung für das POSIX.1-2001 (pax)-Format.

  • behandelt Verzeichnisse, reguläre Dateien, Hardlinks, symbolische Links, FIFOs, Zeichengerätee und Blockgeräte und ist in der Lage, Dateiinformationen wie Zeitstempel, Zugriffsrechte und Besitzer abzurufen und wiederherzustellen.

Geändert in Version 3.3: Unterstützung für lzma-Kompression hinzugefügt.

Geändert in Version 3.12: Archive werden mit einem Filter extrahiert, der es ermöglicht, entweder überraschende/gefährliche Funktionen einzuschränken oder anzuerkennen, dass sie erwartet werden und das Archiv vollständig vertrauenswürdig ist.

Geändert in Version 3.14: Der Standard-Extraktionsfilter wurde auf data gesetzt, was einige gefährliche Funktionen wie Links zu absoluten Pfaden oder Pfaden außerhalb des Ziels verbietet. Zuvor war die Filterstrategie äquivalent zu fully_trusted.

Geändert in Version 3.14: Unterstützung für Zstandard-Kompression mit compression.zstd hinzugefügt.

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

Gibt ein TarFile-Objekt für den Pfadnamen name zurück. Detaillierte Informationen zu TarFile-Objekten und den erlaubten Schlüsselwortargumenten finden Sie unter TarFile-Objekte.

mode muss eine Zeichenkette der Form 'filemode[:compression]' sein, standardmäßig ist es 'r'. Hier ist eine vollständige Liste der Moduskombinationen

Modus

action

'r' oder 'r:*'

Zum Lesen mit transparenter Kompression öffnen (empfohlen).

'r:'

Zum ausschließlichen Lesen ohne Kompression öffnen.

'r:gz'

Zum Lesen mit gzip-Kompression öffnen.

'r:bz2'

Zum Lesen mit bzip2-Kompression öffnen.

'r:xz'

Zum Lesen mit lzma-Kompression öffnen.

'r:zst'

Zum Lesen mit Zstandard-Kompression öffnen.

'x' oder 'x:'

Erstellt ein Tar-Archiv exklusiv ohne Kompression. Löst eine FileExistsError-Ausnahme aus, wenn es bereits existiert.

'x:gz'

Erstellt ein Tar-Archiv mit gzip-Kompression. Löst eine FileExistsError-Ausnahme aus, wenn es bereits existiert.

'x:bz2'

Erstellt ein Tar-Archiv mit bzip2-Kompression. Löst eine FileExistsError-Ausnahme aus, wenn es bereits existiert.

'x:xz'

Erstellt ein Tar-Archiv mit lzma-Kompression. Löst eine FileExistsError-Ausnahme aus, wenn es bereits existiert.

'x:zst'

Erstellt ein Tar-Archiv mit Zstandard-Kompression. Löst eine FileExistsError-Ausnahme aus, wenn es bereits existiert.

'a' oder 'a:'

Zum Anhängen ohne Kompression öffnen. Die Datei wird erstellt, wenn sie nicht existiert.

'w' oder 'w:'

Zum unkomprimierten Schreiben öffnen.

'w:gz'

Zum gzip-komprimierten Schreiben öffnen.

'w:bz2'

Zum bzip2-komprimierten Schreiben öffnen.

'w:xz'

Zum lzma-komprimierten Schreiben öffnen.

'w:zst'

Zum Zstandard-komprimierten Schreiben öffnen.

Beachten Sie, dass 'a:gz', 'a:bz2' oder 'a:xz' nicht möglich ist. Wenn mode nicht geeignet ist, eine bestimmte (komprimierte) Datei zum Lesen zu öffnen, wird ReadError ausgelöst. Verwenden Sie mode 'r', um dies zu vermeiden. Wenn eine Kompressionsmethode nicht unterstützt wird, wird CompressionError ausgelöst.

Wenn fileobj angegeben ist, wird es als Alternative zu einem im Binärmodus geöffneten Dateiobjekt für name verwendet. Es wird erwartet, dass es sich an Position 0 befindet.

Für Modi 'w:gz', 'x:gz', 'w|gz', 'w:bz2', 'x:bz2', 'w|bz2' akzeptiert tarfile.open() das Schlüsselwortargument compresslevel (Standardwert 9), um die Kompressionsstufe der Datei anzugeben.

Für Modi 'w:xz', 'x:xz' und 'w|xz' akzeptiert tarfile.open() das Schlüsselwortargument preset, um die Kompressionsstufe der Datei anzugeben.

Für Modi 'w:zst', 'x:zst' und 'w|zst' akzeptiert tarfile.open() das Schlüsselwortargument level, um die Kompressionsstufe der Datei anzugeben. Das Schlüsselwortargument options kann ebenfalls übergeben werden und bietet erweiterte Zstandard-Kompressionsparameter, die von CompressionParameter beschrieben werden. Das Schlüsselwortargument zstd_dict kann übergeben werden, um ein ZstdDict bereitzustellen, ein Zstandard-Wörterbuch zur Verbesserung der Kompression kleinerer Datenmengen.

Für spezielle Zwecke gibt es ein zweites Format für mode: 'filemode|[compression]'. tarfile.open() gibt ein TarFile-Objekt zurück, das seine Daten als Blockstrom verarbeitet. Es werden keine zufälligen Sprünge in der Datei durchgeführt. Wenn angegeben, kann fileobj jedes Objekt sein, das eine read()- oder write()-Methode (abhängig vom mode) besitzt, die mit Bytes arbeitet. bufsize gibt die Blockgröße an und beträgt standardmäßig 20 * 512 Bytes. Verwenden Sie diese Variante in Kombination mit z.B. sys.stdin.buffer, einem Socket-Dateiobjekt oder einem Bandlaufwerk. Ein solches TarFile-Objekt ist jedoch eingeschränkt, da es keinen zufälligen Zugriff erlaubt, siehe Beispiele. Die derzeit möglichen Modi

Modus

Aktion

'r|*'

Öffnet einen Stream von Tar-Blöcken zum Lesen mit transparenter Kompression.

'r|'

Öffnet einen Stream von unkomprimierten Tar-Blöcken zum Lesen.

'r|gz'

Öffnet einen gzip-komprimierten Stream zum Lesen.

'r|bz2'

Öffnet einen bzip2-komprimierten Stream zum Lesen.

'r|xz'

Öffnet einen lzma-komprimierten Stream zum Lesen.

'r|zst'

Öffnet einen Zstandard-komprimierten Stream zum Lesen.

'w|'

Öffnet einen unkomprimierten Stream zum Schreiben.

'w|gz'

Öffnet einen gzip-komprimierten Stream zum Schreiben.

'w|bz2'

Öffnet einen bzip2-komprimierten Stream zum Schreiben.

'w|xz'

Öffnet einen lzma-komprimierten Stream zum Schreiben.

'w|zst'

Öffnet einen Zstandard-komprimierten Stream zum Schreiben.

Geändert in Version 3.5: Der Modus 'x' (exklusive Erstellung) wurde hinzugefügt.

Geändert in Version 3.6: Der Parameter name akzeptiert ein pfadähnliches Objekt.

Geändert in Version 3.12: Das Schlüsselwortargument compresslevel funktioniert auch für Streams.

Geändert in Version 3.14: Das Schlüsselwortargument preset funktioniert auch für Streams.

class tarfile.TarFile

Klasse zum Lesen und Schreiben von Tar-Archiven. Verwenden Sie diese Klasse nicht direkt: verwenden Sie stattdessen tarfile.open(). Siehe TarFile-Objekte.

tarfile.is_tarfile(name)

Gibt True zurück, wenn name ein Tar-Archiv ist, das das Modul tarfile lesen kann. name kann eine str-, Datei- oder dateiähnliche Objekt sein.

Geändert in Version 3.9: Unterstützung für Datei- und dateiähnliche Objekte.

Das Modul tarfile definiert die folgenden Ausnahmen

exception tarfile.TarError

Basisklasse für alle tarfile-Ausnahmen.

exception tarfile.ReadError

Wird ausgelöst, wenn ein Tar-Archiv geöffnet wird, das entweder nicht vom Modul tarfile behandelt werden kann oder in irgendeiner Weise ungültig ist.

exception tarfile.CompressionError

Wird ausgelöst, wenn eine Kompressionsmethode nicht unterstützt wird oder wenn die Daten nicht korrekt dekodiert werden können.

exception tarfile.StreamError

Wird für die Einschränkungen ausgelöst, die für stromartige TarFile-Objekte typisch sind.

exception tarfile.ExtractError

Wird für nicht-fatale Fehler bei der Verwendung von TarFile.extract() ausgelöst, aber nur, wenn TarFile.errorlevel== 2 ist.

exception tarfile.HeaderError

Wird von TarInfo.frombuf() ausgelöst, wenn der erhaltene Puffer ungültig ist.

exception tarfile.FilterError

Basisklasse für Mitglieder, die von Filtern abgelehnt wurden.

tarinfo

Informationen über das Mitglied, dessen Extraktion der Filter verweigert hat, als TarInfo.

exception tarfile.AbsolutePathError

Ausgelöst, um die Extraktion eines Mitglieds mit einem absoluten Pfad zu verweigern.

exception tarfile.OutsideDestinationError

Ausgelöst, um die Extraktion eines Mitglieds außerhalb des Zielverzeichnisses zu verweigern.

exception tarfile.SpecialFileError

Ausgelöst, um die Extraktion einer speziellen Datei (z.B. eines Geräts oder einer Pipe) zu verweigern.

exception tarfile.AbsoluteLinkError

Ausgelöst, um die Extraktion eines symbolischen Links mit absolutem Pfad zu verweigern.

exception tarfile.LinkOutsideDestinationError

Ausgelöst, um die Extraktion eines symbolischen Links, der außerhalb des Zielverzeichnisses zeigt, zu verweigern.

exception tarfile.LinkFallbackError

Ausgelöst, um die Emulation eines Links (hart oder symbolisch) durch Extraktion eines anderen Archivmembers zu verweigern, wenn dieses Mitglied vom Filterstandort abgelehnt würde. Die Ausnahme, die zum Ablehnen des Ersatzmembers ausgelöst wurde, ist als BaseException.__context__ verfügbar.

Hinzugefügt in Version 3.14.

Die folgenden Konstanten sind auf Modulebene verfügbar

tarfile.ENCODING

Die Standard-Zeichenkodierung: 'utf-8' unter Windows, andernfalls der Wert von sys.getfilesystemencoding().

tarfile.REGTYPE
tarfile.AREGTYPE

Ein regulärer Dateityp type.

tarfile.LNKTYPE

Ein Link (innerhalb des Tar-Archivs) type.

tarfile.SYMTYPE

Ein symbolischer Link type.

tarfile.CHRTYPE

Ein Zeichengerät type.

tarfile.BLKTYPE

Ein Blockgerät type.

tarfile.DIRTYPE

Ein Verzeichnis type.

tarfile.FIFOTYPE

Ein FIFO-Spezialgerät type.

tarfile.CONTTYPE

Eine fortlaufende Datei type.

tarfile.GNUTYPE_LONGNAME

Ein GNU tar Longname type.

Ein GNU tar Longlink type.

tarfile.GNUTYPE_SPARSE

Eine GNU tar Sparse-Datei type.

Jede der folgenden Konstanten definiert ein Tar-Archivformat, das das Modul tarfile erstellen kann. Siehe Abschnitt Unterstützte Tar-Formate für Details.

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

Das Standardformat zum Erstellen von Archiven. Dies ist derzeit PAX_FORMAT.

Geändert in Version 3.8: Das Standardformat für neue Archive wurde von GNU_FORMAT auf PAX_FORMAT geändert.

Siehe auch

Modul zipfile

Dokumentation des Standardmoduls zipfile.

Archivierungsoperationen

Dokumentation der höherstufigen Archivierungsfunktionen, die vom Standardmodul shutil bereitgestellt werden.

GNU tar Handbuch, Grundlegendes Tar-Format

Dokumentation für Tar-Archivdateien, einschließlich GNU tar-Erweiterungen.

TarFile-Objekte

Das TarFile-Objekt bietet eine Schnittstelle zu einem Tar-Archiv. Ein Tar-Archiv ist eine Sequenz von Blöcken. Ein Archivmitglied (eine gespeicherte Datei) besteht aus einem Header-Block gefolgt von Datenblöcken. Es ist möglich, eine Datei mehrmals in einem Tar-Archiv zu speichern. Jedes Archivmitglied wird durch ein TarInfo-Objekt repräsentiert, siehe TarInfo-Objekte für Details.

Ein TarFile-Objekt kann als Kontextmanager in einer with-Anweisung verwendet werden. Es wird automatisch geschlossen, wenn der Block abgeschlossen ist. Bitte beachten Sie, dass im Falle einer Ausnahme ein zum Schreiben geöffnetes Archiv nicht finalisiert wird; nur das intern verwendete Dateiobjekt wird geschlossen. Ein Anwendungsfall finden Sie im Abschnitt Beispiele.

Hinzugefügt in Version 3.2: Unterstützung für das Context-Management-Protokoll hinzugefügt.

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)

Alle folgenden Argumente sind optional und können auch als Instanzattribute abgerufen werden.

name ist der Pfadname des Archivs. name kann ein pfadähnliches Objekt sein. Er kann weggelassen werden, wenn fileobj angegeben ist. In diesem Fall wird, falls vorhanden, das `name`-Attribut des Dateiobjekts verwendet.

mode ist entweder 'r' zum Lesen aus einem vorhandenen Archiv, 'a' zum Anhängen von Daten an eine vorhandene Datei, 'w' zum Erstellen einer neuen Datei, wobei eine vorhandene überschrieben wird, oder 'x' zum Erstellen einer neuen Datei nur, wenn sie noch nicht existiert.

Wenn fileobj angegeben wird, wird es zum Lesen oder Schreiben von Daten verwendet. Wenn es ermittelt werden kann, wird mode von fileobjs Modus überschrieben. fileobj wird ab Position 0 verwendet.

Hinweis

fileobj wird nicht geschlossen, wenn TarFile geschlossen wird.

format steuert das Archivformat für das Schreiben. Es muss eine der Konstanten USTAR_FORMAT, GNU_FORMAT oder PAX_FORMAT sein, die auf Modulebene definiert sind. Beim Lesen wird das Format automatisch erkannt, auch wenn im selben Archiv unterschiedliche Formate vorhanden sind.

Das Argument tarinfo kann verwendet werden, um die Standardklasse TarInfo durch eine andere zu ersetzen.

Wenn dereference False ist, werden symbolische Links und Hardlinks zum Archiv hinzugefügt. Wenn es True ist, wird der Inhalt der Zieldateien zum Archiv hinzugefügt. Dies hat keine Auswirkung auf Systeme, die keine symbolischen Links unterstützen.

Wenn ignore_zeros False ist, wird ein leerer Block als Ende des Archivs behandelt. Wenn es True ist, werden leere (und ungültige) Blöcke übersprungen und versucht, so viele Mitglieder wie möglich zu erhalten. Dies ist nur nützlich für das Lesen von verketteten oder beschädigten Archiven.

debug kann von 0 (keine Debug-Meldungen) bis 3 (alle Debug-Meldungen) eingestellt werden. Die Meldungen werden nach sys.stderr geschrieben.

errorlevel steuert, wie Extraktionsfehler behandelt werden, siehe das entsprechende Attribut.

Die Argumente encoding und errors definieren die Zeichenkodierung, die zum Lesen oder Schreiben des Archivs verwendet wird, und wie Konvertierungsfehler behandelt werden. Die Standardeinstellungen funktionieren für die meisten Benutzer. Ausführliche Informationen finden Sie im Abschnitt Unicode-Probleme.

Das Argument pax_headers ist ein optionales Wörterbuch von Zeichenketten, die als globaler Pax-Header hinzugefügt werden, wenn format PAX_FORMAT ist.

Wenn stream auf True gesetzt ist, werden beim Lesen des Archivs Informationen über Dateien im Archiv nicht zwischengespeichert, was Speicher spart.

Geändert in Version 3.2: Verwendet 'surrogateescape' als Standard für das Argument errors.

Geändert in Version 3.5: Der Modus 'x' (exklusive Erstellung) wurde hinzugefügt.

Geändert in Version 3.6: Der Parameter name akzeptiert ein pfadähnliches Objekt.

Geändert in Version 3.13: Fügt den Parameter stream hinzu.

classmethod TarFile.open(...)

Alternativer Konstruktor. Die Funktion tarfile.open() ist tatsächlich eine Abkürzung zu dieser Klassenmethode.

TarFile.getmember(name)

Gibt ein TarInfo-Objekt für das Mitglied name zurück. Wenn name nicht im Archiv gefunden werden kann, wird KeyError ausgelöst.

Hinweis

Wenn ein Mitglied mehr als einmal im Archiv vorkommt, wird seine letzte Erscheinung als die aktuellste Version angenommen.

TarFile.getmembers()

Gibt die Mitglieder des Archivs als Liste von TarInfo-Objekten zurück. Die Liste hat die gleiche Reihenfolge wie die Mitglieder im Archiv.

TarFile.getnames()

Gibt die Mitglieder als Liste ihrer Namen zurück. Sie hat die gleiche Reihenfolge wie die Liste, die von getmembers() zurückgegeben wird.

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

Gibt ein Inhaltsverzeichnis nach sys.stdout aus. Wenn verbose False ist, werden nur die Namen der Mitglieder ausgegeben. Wenn es True ist, wird eine Ausgabe ähnlich der von ls -l erzeugt. Wenn optional members angegeben wird, muss es eine Teilmenge der von getmembers() zurückgegebenen Liste sein.

Geändert in Version 3.5: Der Parameter members wurde hinzugefügt.

TarFile.next()

Gibt das nächste Mitglied des Archivs als TarInfo-Objekt zurück, wenn TarFile zum Lesen geöffnet ist. Gibt None zurück, wenn keine weiteren verfügbar sind.

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

Extrahieren Sie alle Mitglieder aus dem Archiv in das aktuelle Arbeitsverzeichnis oder das Verzeichnis path. Wenn optional members angegeben wird, muss es eine Teilmenge der von getmembers() zurückgegebenen Liste sein. Verzeichnisinformationen wie Besitzer, Änderungszeit und Berechtigungen werden gesetzt, nachdem alle Mitglieder extrahiert wurden. Dies geschieht, um zwei Probleme zu umgehen: Die Änderungszeit eines Verzeichnisses wird bei jeder Erstellung einer Datei darin zurückgesetzt. Und wenn die Berechtigungen eines Verzeichnisses keinen Schreibzugriff zulassen, schlägt das Extrahieren von Dateien dorthin fehl.

Wenn numeric_owner True ist, werden die uid- und gid-Zahlen aus der Tarfile verwendet, um den Besitzer/die Gruppe für die extrahierten Dateien festzulegen. Andernfalls werden die benannten Werte aus der Tarfile verwendet.

Das Argument filter gibt an, wie members vor der Extraktion geändert oder abgelehnt werden. Details finden Sie unter Extraktionsfilter. Es wird empfohlen, dies nur dann explizit festzulegen, wenn spezifische tar-Funktionen benötigt werden, oder als filter='data' zur Unterstützung von Python-Versionen mit einer weniger sicheren Standardeinstellung (3.13 und niedriger).

Warnung

Extrahieren Sie niemals Archive aus nicht vertrauenswürdigen Quellen ohne vorherige Überprüfung.

Seit Python 3.14 verhindert die Standardeinstellung (data) die gefährlichsten Sicherheitsprobleme. Sie verhindert jedoch nicht alle unbeabsichtigten oder unsicheren Verhaltensweisen. Lesen Sie den Abschnitt Extraktionsfilter für Details.

Geändert in Version 3.5: Der Parameter numeric_owner wurde hinzugefügt.

Geändert in Version 3.6: Der Parameter path akzeptiert ein pfadähnliches Objekt.

Geändert in Version 3.12: Der Parameter filter wurde hinzugefügt.

Geändert in Version 3.14: Der Parameter filter hat jetzt den Standardwert 'data'.

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

Extrahiert ein Mitglied aus dem Archiv in das aktuelle Arbeitsverzeichnis unter Verwendung seines vollständigen Namens. Seine Dateiinformationen werden so genau wie möglich extrahiert. member kann ein Dateiname oder ein TarInfo-Objekt sein. Sie können ein anderes Verzeichnis mit path angeben. path kann ein pfadähnliches Objekt sein. Dateieigenschaften (Besitzer, mtime, Modus) werden gesetzt, es sei denn, set_attrs ist falsch.

Die Argumente numeric_owner und filter sind dieselben wie für extractall().

Hinweis

Die Methode extract() berücksichtigt mehrere Extraktionsprobleme nicht. In den meisten Fällen sollten Sie die Methode extractall() in Betracht ziehen.

Warnung

Extrahieren Sie niemals Archive aus nicht vertrauenswürdigen Quellen ohne vorherige Überprüfung. Einzelheiten finden Sie in der Warnung für extractall().

Geändert in Version 3.2: Der Parameter set_attrs wurde hinzugefügt.

Geändert in Version 3.5: Der Parameter numeric_owner wurde hinzugefügt.

Geändert in Version 3.6: Der Parameter path akzeptiert ein pfadähnliches Objekt.

Geändert in Version 3.12: Der Parameter filter wurde hinzugefügt.

TarFile.extractfile(member)

Extrahiert ein Mitglied aus dem Archiv als Datei-Objekt. member kann ein Dateiname oder ein TarInfo-Objekt sein. Wenn member eine reguläre Datei oder ein Link ist, wird ein io.BufferedReader-Objekt zurückgegeben. Für alle anderen vorhandenen Mitglieder wird None zurückgegeben. Wenn member nicht im Archiv vorkommt, wird KeyError ausgelöst.

Geändert in Version 3.3: Gibt ein io.BufferedReader-Objekt zurück.

Geändert in Version 3.13: Das zurückgegebene io.BufferedReader-Objekt hat das Attribut mode, das immer gleich 'rb' ist.

TarFile.errorlevel: int

Wenn errorlevel 0 ist, werden Fehler bei der Verwendung von TarFile.extract() und TarFile.extractall() ignoriert. Dennoch erscheinen sie als Fehlermeldungen in der Debug-Ausgabe, wenn debug größer als 0 ist. Wenn 1 (der Standardwert), werden alle fatalen Fehler als OSError oder FilterError-Ausnahmen ausgelöst. Wenn 2, werden alle nicht-fatalen Fehler ebenfalls als TarError-Ausnahmen ausgelöst.

Einige Ausnahmen, z. B. solche, die durch falsche Argumenttypen oder Datenbeschädigung verursacht werden, werden immer ausgelöst.

Benutzerdefinierte Extraktionsfilter sollten FilterError für fatale Fehler und ExtractError für nicht-fatale Fehler auslösen.

Beachten Sie, dass das Archiv teilweise extrahiert sein kann, wenn eine Ausnahme ausgelöst wird. Es liegt in der Verantwortung des Benutzers, aufzuräumen.

TarFile.extraction_filter

Hinzugefügt in Version 3.12.

Der Extraktionsfilter, der als Standard für das Argument filter von extract() und extractall() verwendet wird.

Das Attribut kann None oder ein aufrufbares Objekt sein. Zeichenkettennamen sind für dieses Attribut nicht zulässig, im Gegensatz zum Argument filter für extract().

Wenn extraction_filter None (der Standardwert) ist, verwenden die Extraktionsmethoden standardmäßig den data-Filter.

Das Attribut kann auf Instanzen gesetzt oder in Unterklassen überschrieben werden. Es ist auch möglich, es für die Klasse TarFile selbst festzulegen, um einen globalen Standard festzulegen, obwohl dies aufgrund der Auswirkungen auf alle Verwendungen von tarfile am besten in obersten Anwendungen oder site Konfigurationen erfolgt. Um einen globalen Standard auf diese Weise festzulegen, muss eine Filterfunktion in staticmethod() eingewickelt werden, um die Einführung eines self-Arguments zu verhindern.

Geändert in Version 3.14: Der Standardfilter wird auf data gesetzt, was einige gefährliche Funktionen wie Links zu absoluten Pfaden oder Pfaden außerhalb des Ziels ablehnt. Zuvor entsprach die Standardeinstellung fully_trusted.

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

Fügt die Datei name dem Archiv hinzu. name kann jeder Dateityp sein (Verzeichnis, FIFO, symbolischer Link usw.). Wenn angegeben, legt arcname einen alternativen Namen für die Datei im Archiv fest. Verzeichnisse werden standardmäßig rekursiv hinzugefügt. Dies kann durch Setzen von recursive auf False vermieden werden. Rekursion fügt Einträge in sortierter Reihenfolge hinzu. Wenn filter angegeben ist, sollte es eine Funktion sein, die ein TarInfo-Objekt als Argument nimmt und das geänderte TarInfo-Objekt zurückgibt. Wenn stattdessen None zurückgegeben wird, wird das TarInfo-Objekt aus dem Archiv ausgeschlossen. Siehe Beispiele für ein Beispiel.

Geändert in Version 3.2: Der Parameter filter wurde hinzugefügt.

Geändert in Version 3.7: Rekursion fügt Einträge in sortierter Reihenfolge hinzu.

TarFile.addfile(tarinfo, fileobj=None)

Fügt das TarInfo-Objekt tarinfo dem Archiv hinzu. Wenn tarinfo eine reguläre Datei mit nicht null Größe darstellt, muss das Argument fileobj eine Binärdatei sein, und es werden tarinfo.size Bytes daraus gelesen und zum Archiv hinzugefügt. Sie können TarInfo-Objekte direkt oder mit gettarinfo() erstellen.

Geändert in Version 3.13: fileobj muss für nicht null große reguläre Dateien angegeben werden.

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

Erstellt ein TarInfo-Objekt aus dem Ergebnis von os.stat() oder einem Äquivalent auf einer vorhandenen Datei. Die Datei wird entweder durch name benannt oder als Datei-Objekt fileobj mit einem Dateideskriptor angegeben. name kann ein pfadähnliches Objekt sein. Wenn angegeben, legt arcname einen alternativen Namen für die Datei im Archiv fest, andernfalls wird der Name aus dem name-Attribut von fileobj oder dem Argument name übernommen. Der Name sollte eine Textzeichenkette sein.

Sie können einige der Attribute von TarInfo ändern, bevor Sie es mit addfile() hinzufügen. Wenn das Datei-Objekt kein gewöhnliches Datei-Objekt am Anfang der Datei ist, müssen Attribute wie size möglicherweise geändert werden. Dies ist bei Objekten wie GzipFile der Fall. Der name kann ebenfalls geändert werden, in diesem Fall könnte arcname eine Dummy-Zeichenkette sein.

Geändert in Version 3.6: Der Parameter name akzeptiert ein pfadähnliches Objekt.

TarFile.close()

Schließt die TarFile. Im Schreibmodus werden zwei abschließende Nullblöcke an das Archiv angehängt.

TarFile.pax_headers: dict

Ein Wörterbuch, das Schlüssel-Wert-Paare von globalen Pax-Headern enthält.

TarInfo-Objekte

Ein TarInfo-Objekt repräsentiert ein Mitglied in einer TarFile. Neben der Speicherung aller erforderlichen Attribute einer Datei (wie Dateityp, Größe, Zeit, Berechtigungen, Besitzer usw.) bietet es einige nützliche Methoden zur Bestimmung ihres Typs. Es enthält nicht die Daten der Datei selbst.

TarInfo-Objekte werden von den Methoden getmember(), getmembers() und gettarinfo() von TarFile zurückgegeben.

Das Ändern der von getmember() oder getmembers() zurückgegebenen Objekte wirkt sich auf alle nachfolgenden Operationen auf dem Archiv aus. Für Fälle, in denen dies unerwünscht ist, können Sie copy.copy() verwenden oder die Methode replace() aufrufen, um eine geänderte Kopie in einem Schritt zu erstellen.

Mehrere Attribute können auf None gesetzt werden, um anzuzeigen, dass ein Metadatenstück ungenutzt oder unbekannt ist. Verschiedene TarInfo-Methoden behandeln None unterschiedlich.

  • Die Methoden extract() oder extractall() ignorieren die entsprechenden Metadaten und lassen sie auf einen Standardwert gesetzt.

  • addfile() wird fehlschlagen.

  • list() gibt eine Platzhalterzeichenkette aus.

class tarfile.TarInfo(name='')

Erstellt ein TarInfo-Objekt.

classmethod TarInfo.frombuf(buf, encoding, errors)

Erstellt und gibt ein TarInfo-Objekt aus dem Zeichenkettenpuffer buf zurück.

Löst HeaderError aus, wenn der Puffer ungültig ist.

classmethod TarInfo.fromtarfile(tarfile)

Liest das nächste Mitglied aus dem TarFile-Objekt tarfile und gibt es als TarInfo-Objekt zurück.

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

Erzeugt einen String-Puffer aus einem TarInfo-Objekt. Informationen zu den Argumenten finden Sie im Konstruktor der Klasse TarFile.

Geändert in Version 3.2: Verwendet 'surrogateescape' als Standard für das Argument errors.

Ein TarInfo-Objekt verfügt über die folgenden öffentlichen Datenattribute

TarInfo.name: str

Name des Archivmembers.

TarInfo.size: int

Größe in Bytes.

TarInfo.mtime: int | float

Zeit der letzten Änderung in Sekunden seit der Epoche, wie bei os.stat_result.st_mtime.

Geändert in Version 3.12: Kann für extract() und extractall() auf None gesetzt werden, was dazu führt, dass die Extraktion das Anwenden dieses Attributs überspringt.

TarInfo.mode: int

Berechtigungsbits, wie bei os.chmod().

Geändert in Version 3.12: Kann für extract() und extractall() auf None gesetzt werden, was dazu führt, dass die Extraktion das Anwenden dieses Attributs überspringt.

TarInfo.type

Dateityp. type ist normalerweise eine dieser Konstanten: REGTYPE, AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, CONTTYPE, CHRTYPE, BLKTYPE, GNUTYPE_SPARSE. Um den Typ eines TarInfo-Objekts bequemer zu ermitteln, verwenden Sie die nachstehenden is*()-Methoden.

TarInfo.linkname: str

Name der Zieldatei, der nur in TarInfo-Objekten vom Typ LNKTYPE und SYMTYPE vorhanden ist.

Bei symbolischen Links (SYMTYPE) ist der linkname relativ zu dem Verzeichnis, das den Link enthält. Bei Hardlinks (LNKTYPE) ist der linkname relativ zur Wurzel des Archivs.

TarInfo.uid: int

Benutzer-ID des Benutzers, der dieses Mitglied ursprünglich gespeichert hat.

Geändert in Version 3.12: Kann für extract() und extractall() auf None gesetzt werden, was dazu führt, dass die Extraktion das Anwenden dieses Attributs überspringt.

TarInfo.gid: int

Gruppen-ID des Benutzers, der dieses Mitglied ursprünglich gespeichert hat.

Geändert in Version 3.12: Kann für extract() und extractall() auf None gesetzt werden, was dazu führt, dass die Extraktion das Anwenden dieses Attributs überspringt.

TarInfo.uname: str

Benutzername.

Geändert in Version 3.12: Kann für extract() und extractall() auf None gesetzt werden, was dazu führt, dass die Extraktion das Anwenden dieses Attributs überspringt.

TarInfo.gname: str

Gruppenname.

Geändert in Version 3.12: Kann für extract() und extractall() auf None gesetzt werden, was dazu führt, dass die Extraktion das Anwenden dieses Attributs überspringt.

TarInfo.chksum: int

Prüfsumme des Headers.

TarInfo.devmajor: int

Geräte-Major-Nummer.

TarInfo.devminor: int

Geräte-Minor-Nummer.

TarInfo.offset: int

Der Tar-Header beginnt hier.

TarInfo.offset_data: int

Die Daten der Datei beginnen hier.

TarInfo.sparse

Informationen zu spärlichen Membern.

TarInfo.pax_headers: dict

Ein Dictionary, das Schlüssel-Wert-Paare eines zugehörigen Pax-Erweiterungsheaders enthält.

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

Hinzugefügt in Version 3.12.

Gibt eine *neue* Kopie des TarInfo-Objekts mit den geänderten Attributen zurück. Um beispielsweise ein TarInfo mit dem Gruppennamen 'staff' zu erhalten, verwenden Sie

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

Standardmäßig wird eine tiefe Kopie erstellt. Wenn deep falsch ist, ist die Kopie flach, d.h. pax_headers und alle benutzerdefinierten Attribute werden mit dem ursprünglichen TarInfo-Objekt geteilt.

Ein TarInfo-Objekt bietet außerdem einige praktische Abfragemethoden

TarInfo.isfile()

Gibt True zurück, wenn das TarInfo-Objekt eine reguläre Datei ist.

TarInfo.isreg()

Identisch mit isfile().

TarInfo.isdir()

Gibt True zurück, wenn es sich um ein Verzeichnis handelt.

TarInfo.issym()

Gibt True zurück, wenn es sich um einen symbolischen Link handelt.

TarInfo.islnk()

Gibt True zurück, wenn es sich um einen Hardlink handelt.

TarInfo.ischr()

Gibt True zurück, wenn es sich um ein Zeichengerät handelt.

TarInfo.isblk()

Gibt True zurück, wenn es sich um ein Blockgerät handelt.

TarInfo.isfifo()

Gibt True zurück, wenn es sich um eine FIFO handelt.

TarInfo.isdev()

Gibt True zurück, wenn es sich um ein Zeichengerät, ein Blockgerät oder eine FIFO handelt.

Extraktionsfilter

Hinzugefügt in Version 3.12.

Das tar-Format wurde entwickelt, um alle Details eines UNIX-ähnlichen Dateisystems zu erfassen, was es sehr leistungsfähig macht. Leider können die Funktionen dazu führen, dass Tar-Dateien erstellt werden, die beim Extrahieren unbeabsichtigte – und möglicherweise bösartige – Auswirkungen haben. So kann beispielsweise das Extrahieren einer Tar-Datei beliebige Dateien auf verschiedene Weise überschreiben (z. B. durch die Verwendung absoluter Pfade, ..-Pfadkomponenten oder Symlinks, die spätere Member beeinflussen).

In den meisten Fällen ist die volle Funktionalität nicht erforderlich. Daher unterstützt tarfile Extraktionsfilter: einen Mechanismus zur Einschränkung der Funktionalität und damit zur Minderung einiger Sicherheitsprobleme.

Warnung

Keiner der verfügbaren Filter blockiert alle gefährlichen Archivfunktionen. Extrahieren Sie niemals Archive aus nicht vertrauenswürdigen Quellen ohne vorherige Überprüfung. Siehe auch Hinweise zur weiteren Verifizierung.

Siehe auch

PEP 706

Enthält weitere Motivation und Begründungen für das Design.

Das Argument filter für TarFile.extract() oder extractall() kann sein

  • der String 'fully_trusted': Alle im Archiv angegebenen Metadaten werden berücksichtigt. Sollte verwendet werden, wenn der Benutzer dem Archiv vollständig vertraut oder seine eigene komplexe Verifizierung implementiert.

  • der String 'tar': Berücksichtigt die meisten tar-spezifischen Funktionen (d. h. Funktionen von UNIX-ähnlichen Dateisystemen), blockiert jedoch Funktionen, die sehr wahrscheinlich überraschend oder bösartig sind. Details finden Sie unter tar_filter().

  • der String 'data': Ignoriert oder blockiert die meisten Funktionen, die spezifisch für UNIX-ähnliche Dateisysteme sind. Vorgesehen für das Extrahieren von plattformübergreifenden Datenarchiven. Details finden Sie unter data_filter().

  • None (Standard): Verwendet TarFile.extraction_filter.

    Wenn dieser ebenfalls None ist (Standard), wird der 'data'-Filter verwendet.

    Geändert in Version 3.14: Der Standardfilter wurde auf data gesetzt. Zuvor war der Standard äquivalent zu fully_trusted.

  • Ein aufrufbares Objekt, das für jedes extrahierte Mitglied mit einem TarInfo-Objekt aufgerufen wird, das das Mitglied beschreibt, und mit dem Zielpfad, in den das Archiv extrahiert wird (d. h. derselbe Pfad wird für alle Mitglieder verwendet).

    filter(member: TarInfo, path: str, /) -> TarInfo | None

    Das aufrufbare Objekt wird kurz vor der Extraktion jedes Mitglieds aufgerufen, sodass es den aktuellen Zustand der Festplatte berücksichtigen kann. Es kann

    • ein TarInfo-Objekt zurückgeben, das anstelle der Metadaten im Archiv verwendet wird, oder

    • None zurückgeben, in diesem Fall wird das Mitglied übersprungen, oder

    • eine Ausnahme auslösen, um die Operation abzubrechen oder das Mitglied zu überspringen, je nach errorlevel. Beachten Sie, dass bei einem Abbruch der Extraktion extractall() das Archiv möglicherweise teilweise extrahiert hinterlässt. Es wird keine Bereinigung versucht.

Standardmäßige benannte Filter

Die vordefinierten, benannten Filter sind als Funktionen verfügbar, sodass sie in benutzerdefinierten Filtern wiederverwendet werden können

tarfile.fully_trusted_filter(member, path)

Gibt member unverändert zurück.

Dies implementiert den Filter 'fully_trusted'.

tarfile.tar_filter(member, path)

Implementiert den Filter 'tar'.

  • Entfernt führende Schrägstriche (/ und os.sep) aus Dateinamen.

  • Weigert sich, Dateien mit absoluten Pfaden zu extrahieren (falls der Name auch nach dem Entfernen von Schrägstrichen absolut ist, z. B. C:/foo unter Windows). Dies löst AbsolutePathError aus.

  • Weigert sich, Dateien zu extrahieren, deren absoluter Pfad (nach dem Auflösen von Symlinks) außerhalb des Ziels liegen würde. Dies löst OutsideDestinationError aus.

  • Löscht hohe Modusbits (setuid, setgid, sticky) und Schreibberechtigungen für Gruppen/andere (S_IWGRP | S_IWOTH).

Gibt den modifizierten TarInfo-Member zurück.

tarfile.data_filter(member, path)

Implementiert den 'data'-Filter. Zusätzlich zu dem, was tar_filter tut

  • Normalisiert Link-Ziele (TarInfo.linkname) mithilfe von os.path.normpath(). Beachten Sie, dass dies interne ..-Komponenten entfernt, was die Bedeutung des Links ändern kann, wenn der Pfad in TarInfo.linkname symbolische Links durchläuft.

  • Weigert sich, Links (hart oder weich) zu extrahieren, die auf absolute Pfade verweisen oder außerhalb des Ziels liegen.

    Dies löst AbsoluteLinkError oder LinkOutsideDestinationError aus.

    Beachten Sie, dass solche Dateien auch auf Plattformen verweigert werden, die keine symbolischen Links unterstützen.

  • Weigert sich, Geräte-Dateien (einschließlich Pipes) zu extrahieren. Dies löst SpecialFileError aus.

  • Für reguläre Dateien, einschließlich Hardlinks

    • Setzt die Lese- und Schreibberechtigungen des Besitzers (S_IRUSR | S_IWUSR).

    • Entfernt die Ausführungsberechtigung für Gruppen & andere (S_IXGRP | S_IXOTH), wenn der Besitzer diese nicht hat (S_IXUSR).

  • Für andere Dateien (Verzeichnisse) wird mode auf None gesetzt, sodass Extraktionsmethoden das Anwenden von Berechtigungsbits überspringen.

  • Setzt Benutzer- und Gruppeninformationen (uid, gid, uname, gname) auf None, sodass Extraktionsmethoden das Setzen überspringen.

Gibt den modifizierten TarInfo-Member zurück.

Beachten Sie, dass dieser Filter nicht alle gefährlichen Archivfunktionen blockiert. Details finden Sie unter Hinweise zur weiteren Verifizierung.

Geändert in Version 3.14: Link-Ziele werden nun normalisiert.

Filterfehler

Wenn ein Filter sich weigert, eine Datei zu extrahieren, löst er eine entsprechende Ausnahme aus, eine Unterklasse von FilterError. Dies bricht die Extraktion ab, wenn TarFile.errorlevel 1 oder höher ist. Mit errorlevel=0 wird der Fehler protokolliert und das Mitglied übersprungen, aber die Extraktion wird fortgesetzt.

Hinweise zur weiteren Verifizierung

Selbst mit filter='data' ist tarfile nicht geeignet, um nicht vertrauenswürdige Dateien ohne vorherige Inspektion zu extrahieren. Unter anderem verhindern die vordefinierten Filter keine Denial-of-Service-Angriffe. Benutzer sollten zusätzliche Prüfungen durchführen.

Hier ist eine unvollständige Liste von Überlegungen

  • Extrahieren Sie in ein neues temporäres Verzeichnis, um z. B. die Ausnutzung bereits vorhandener Links zu verhindern und die Bereinigung nach einer fehlgeschlagenen Extraktion zu erleichtern.

  • Verweigern Sie symbolische Links, wenn Sie die Funktionalität nicht benötigen.

  • Verwenden Sie bei der Arbeit mit nicht vertrauenswürdigen Daten externe (z. B. Betriebssystemebene) Grenzen für Festplatten-, Speicher- und CPU-Auslastung.

  • Überprüfen Sie Dateinamen gegen eine Zulassungsliste von Zeichen (um Steuerzeichen, Verwechslungszeichen, ausländische Pfadtrennzeichen usw. herauszufiltern).

  • Überprüfen Sie, ob Dateinamen erwartete Erweiterungen haben (um Dateien abzuschrecken, die ausgeführt werden, wenn Sie darauf „klicken“, oder dateilose Dateien wie Windows-Spezialgerätenamen).

  • Begrenzen Sie die Anzahl der extrahierten Dateien, die Gesamtgröße der extrahierten Daten, die Länge der Dateinamen (einschließlich der Länge von Symlinks) und die Größe einzelner Dateien.

  • Prüfen Sie auf Dateien, die auf fallbasiert nicht unterscheidenden Dateisystemen überschattet würden.

Beachten Sie auch, dass

  • Tar-Dateien mehrere Versionen derselben Datei enthalten können. Spätere Versionen sollen frühere überschreiben. Diese Funktion ist entscheidend, um Aktualisierungen von Bandarchiven zu ermöglichen, kann aber böswillig missbraucht werden.

  • tarfile schützt nicht vor Problemen mit „lebenden“ Daten, z. B. wenn ein Angreifer das Ziel- (oder Quell-) Verzeichnis manipuliert, während die Extraktion (oder Archivierung) läuft.

Unterstützung älterer Python-Versionen

Extraktionsfilter wurden in Python 3.12 hinzugefügt, können aber als Sicherheitsupdates in ältere Versionen zurückportiert werden. Um zu überprüfen, ob die Funktion verfügbar ist, verwenden Sie z. B. hasattr(tarfile, 'data_filter') anstelle der Überprüfung der Python-Version.

Die folgenden Beispiele zeigen, wie Python-Versionen mit und ohne die Funktion unterstützt werden. Beachten Sie, dass das Setzen von extraction_filter alle nachfolgenden Operationen beeinflusst.

  • Vollständig vertrauenswürdiges Archiv

    my_tarfile.extraction_filter = (lambda member, path: member)
my_tarfile.extractall()

  • Verwenden Sie den 'data'-Filter, wenn verfügbar, aber greifen Sie auf das Verhalten von Python 3.11 zurück ('fully_trusted'), wenn diese Funktion nicht verfügbar ist

    my_tarfile.extraction_filter = getattr(tarfile, 'data_filter',
                                       (lambda member, path: member))
my_tarfile.extractall()

  • Verwenden Sie den 'data'-Filter; Fehler, wenn er nicht verfügbar ist

    my_tarfile.extractall(filter=tarfile.data_filter)

    oder

    my_tarfile.extraction_filter = tarfile.data_filter
my_tarfile.extractall()

  • Verwenden Sie den 'data'-Filter; Warnung, wenn er nicht verfügbar ist

    if hasattr(tarfile, 'data_filter'):
    my_tarfile.extractall(filter='data')
else:
    # remove this when no longer needed
    warn_the_user('Extracting may be unsafe; consider updating Python')
    my_tarfile.extractall()

Beispiel für einen zustandsbehafteten Extraktionsfilter

Während die Extraktionsmethoden von tarfile einen einfachen aufrufbaren filter akzeptieren, können benutzerdefinierte Filter komplexere Objekte mit internem Zustand sein. Es kann nützlich sein, diese als Kontextmanager zu schreiben, die wie folgt verwendet werden können

with StatefulFilter() as filter_func:
    tar.extractall(path, filter=filter_func)

Ein solcher Filter kann beispielsweise wie folgt geschrieben werden

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

    def __enter__(self):
        return self

    def __call__(self, member, path):
        self.file_count += 1
        return member

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

Befehlszeilenschnittstelle

Hinzugefügt in Version 3.4.

Das Modul tarfile bietet eine einfache Befehlszeilenschnittstelle zur Interaktion mit Tar-Archiven.

Wenn Sie ein neues Tar-Archiv erstellen möchten, geben Sie seinen Namen nach der Option -c an und listen Sie dann die Dateinamen auf, die einbezogen werden sollen

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

Die Übergabe eines Verzeichnisses ist ebenfalls zulässig

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

Wenn Sie ein Tar-Archiv in das aktuelle Verzeichnis extrahieren möchten, verwenden Sie die Option -e

$ python -m tarfile -e monty.tar

Sie können ein Tar-Archiv auch in ein anderes Verzeichnis extrahieren, indem Sie den Namen des Verzeichnisses angeben

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

Für eine Liste der Dateien in einem Tar-Archiv verwenden Sie die Option -l

$ python -m tarfile -l monty.tar

Kommandozeilenoptionen

-l <tarfile>
--list <tarfile>

Listet Dateien in einem Tarfile auf.

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

Erstellt ein Tarfile aus Quellcodedateien.

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

Extrahieren Sie die tar-Datei in das aktuelle Verzeichnis, wenn output_dir nicht angegeben ist.

-t <tarfile>
--test <tarfile>

Testen Sie, ob die tar-Datei gültig ist oder nicht.

-v, --verbose

Ausführliche Ausgabe.

--filter <filtername>

Gibt den Filter für --extract an. Details finden Sie unter Extraktionsfilter. Es werden nur Zeichenkettennamen akzeptiert (d. h. fully_trusted, tar und data).

Beispiele

Lesebeispiele

So extrahieren Sie ein vollständiges Tar-Archiv in das aktuelle Arbeitsverzeichnis

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

So extrahieren Sie eine Teilmenge eines Tar-Archivs mit TarFile.extractall() unter Verwendung einer Generatorfunktion anstelle einer Liste

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

So lesen Sie ein gzip-komprimiertes Tar-Archiv und zeigen einige Mitgliedsinformationen an

import tarfile
tar = tarfile.open("sample.tar.gz", "r:gz")
for tarinfo in tar:
    print(tarinfo.name, "is", tarinfo.size, "bytes in size and is ", end="")
    if tarinfo.isreg():
        print("a regular file.")
    elif tarinfo.isdir():
        print("a directory.")
    else:
        print("something else.")
tar.close()

Schreibebeispiele

So erstellen Sie ein unkomprimiertes Tar-Archiv aus einer Liste von Dateinamen

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

Dasselbe Beispiel unter Verwendung der with-Anweisung

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

So erstellen und schreiben Sie ein Archiv nach stdout unter Verwendung von sys.stdout.buffer im Parameter fileobj in 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)

So erstellen Sie ein Archiv und setzen die Benutzerinformationen mithilfe des Parameters filter in TarFile.add() zurück

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

Unterstützte Tar-Formate

Es gibt drei Tar-Formate, die mit dem Modul tarfile erstellt werden können

  • Das POSIX.1-1988 ustar-Format (USTAR_FORMAT). Es unterstützt Dateinamen mit einer Länge von höchstens 256 Zeichen und Linknamen mit einer Länge von bis zu 100 Zeichen. Die maximale Dateigröße beträgt 8 GiB. Dies ist ein altes und begrenztes, aber weit verbreitetes Format.

  • Das GNU tar-Format (GNU_FORMAT). Es unterstützt lange Dateinamen und Linknamen, Dateien größer als 8 GiB und Sparse-Dateien. Es ist der De-facto-Standard auf GNU/Linux-Systemen. tarfile unterstützt die GNU tar-Erweiterungen für lange Namen vollständig, die Unterstützung für Sparse-Dateien ist schreibgeschützt.

  • Das POSIX.1-2001 pax-Format (PAX_FORMAT). Es ist das flexibelste Format mit praktisch keinen Einschränkungen. Es unterstützt lange Dateinamen und Linknamen, große Dateien und speichert Pfadnamen auf portable Weise. Moderne Tar-Implementierungen, einschließlich GNU tar, bsdtar/libarchive und star, unterstützen erweiterte pax-Funktionen vollständig; einige alte oder nicht gewartete Bibliotheken möglicherweise nicht, sollten aber pax-Archive behandeln, als wären sie im universell unterstützten ustar-Format. Es ist das aktuelle Standardformat für neue Archive.

    Es erweitert das bestehende ustar-Format um zusätzliche Header für Informationen, die auf andere Weise nicht gespeichert werden können. Es gibt zwei Varianten von Pax-Headern: Erweiterte Header wirken sich nur auf den nachfolgenden Dateikopf aus, globale Header sind für das gesamte Archiv gültig und wirken sich auf alle folgenden Dateien aus. Alle Daten in einem Pax-Header werden aus Gründen der Portabilität in UTF-8 kodiert.

Es gibt einige weitere Varianten des Tar-Formats, die gelesen, aber nicht erstellt werden können

  • Das alte V7-Format. Dies ist das erste Tar-Format der Unix Seventh Edition, das nur reguläre Dateien und Verzeichnisse speichert. Namen dürfen nicht länger als 100 Zeichen sein, es gibt keine Benutzer-/Gruppeninformationen. Einige Archive haben falsch berechnete Header-Prüfsummen bei Feldern mit Nicht-ASCII-Zeichen.

  • Das SunOS tar-Erweiterungsformat. Dieses Format ist eine Variante des POSIX.1-2001 pax-Formats, ist aber nicht kompatibel.

Unicode-Probleme

Das Tar-Format wurde ursprünglich zur Erstellung von Sicherungen auf Bandlaufwerken mit dem Hauptaugenmerk auf der Beibehaltung von Dateisysteminformationen entwickelt. Heutzutage werden Tar-Archive häufig für die Dateiverteilung und den Austausch von Archiven über Netzwerke verwendet. Ein Problem des ursprünglichen Formats (das die Grundlage aller anderen Formate bildet) ist, dass es kein Konzept zur Unterstützung unterschiedlicher Zeichenkodierungen gibt. Beispielsweise kann ein gewöhnliches Tar-Archiv, das auf einem UTF-8-System erstellt wurde, auf einem Latin-1-System nicht korrekt gelesen werden, wenn es Nicht-ASCII-Zeichen enthält. Textuelle Metadaten (wie Dateinamen, Linknamen, Benutzer-/Gruppennamen) erscheinen beschädigt. Leider gibt es keine Möglichkeit, die Kodierung eines Archivs automatisch zu erkennen. Das pax-Format wurde entwickelt, um dieses Problem zu lösen. Es speichert Nicht-ASCII-Metadaten mit der universellen Zeichenkodierung UTF-8.

Die Details der Zeichenkonvertierung in tarfile werden durch die Schlüsselwortargumente encoding und errors der Klasse TarFile gesteuert.

encoding definiert die zu verwendende Zeichenkodierung für die Metadaten im Archiv. Der Standardwert ist sys.getfilesystemencoding() oder als Fallback 'ascii'. Je nachdem, ob das Archiv gelesen oder geschrieben wird, müssen die Metadaten entweder dekodiert oder kodiert werden. Wenn encoding nicht korrekt eingestellt ist, kann diese Konvertierung fehlschlagen.

Das Argument errors definiert, wie mit Zeichen umgegangen wird, die nicht konvertiert werden können. Mögliche Werte sind in Abschnitt Fehlerbehandlung aufgeführt. Das Standardschema ist 'surrogateescape', das Python auch für seine Dateisystemaufrufe verwendet, siehe Dateinamen, Befehlszeilenargumente und Umgebungsvariablen.

Für PAX_FORMAT-Archive (der Standard) ist encoding im Allgemeinen nicht erforderlich, da alle Metadaten in UTF-8 gespeichert werden. encoding wird nur in den seltenen Fällen verwendet, in denen binäre Pax-Header dekodiert werden oder wenn Zeichenketten mit Surrogate-Zeichen gespeichert werden.