`zipfile` — Mit ZIP-Archiven arbeiten¶

Quellcode: Lib/zipfile/

Das ZIP-Dateiformat ist ein verbreiteter Standard zum Archivieren und Komprimieren. Dieses Modul bietet Werkzeuge, um eine ZIP-Datei zu erzeugen, zu lesen, zu schreiben, zu erweitern und aufzulisten. Für jede weitergehende Verwendung dieses Moduls brauchst du ein Verständnis des Formats, wie es in der PKZIP Application Note festgelegt ist.

Mit mehrteiligen ZIP-Dateien kann dieses Modul nicht umgehen. Mit ZIP-Dateien, die die ZIP64-Erweiterungen verwenden, also mit Dateien über 4 GiB, kann es umgehen. Es kann verschlüsselte Dateien in ZIP-Archiven entschlüsseln, aber keine verschlüsselte Datei erzeugen. Das Entschlüsseln ist außerordentlich langsam, weil es in reinem Python und nicht in C umgesetzt ist.

Für den Umgang mit komprimierten Archiven braucht es optionale Module wie zlib, bz2, lzma und compression.zstd. Fehlt eines davon in deiner CPython-Fassung, schau in die Dokumentation deines Distributors, also dessen, der dir Python bereitgestellt hat. Bist du selbst der Distributor, siehe Voraussetzungen für optionale Module.

Das Modul definiert die folgenden Elemente:

exception zipfile.BadZipFile¶: Der Fehler, der bei fehlerhaften ZIP-Dateien ausgelöst wird.

Added in version 3.2.

exception zipfile.BadZipfile¶: Alias für BadZipFile, aus Gründen der Verträglichkeit mit älteren Python-Versionen.

Veraltet ab Version 3.2.

exception zipfile.LargeZipFile¶: Der Fehler, der ausgelöst wird, wenn eine ZIP-Datei die ZIP64-Funktionalität bräuchte, diese aber nicht eingeschaltet ist.

class zipfile.ZipFile: Die Klasse zum Lesen und Schreiben von ZIP-Dateien. Einzelheiten zum Konstruktor im Abschnitt ZipFile-Objekte.

class zipfile.Path: Klasse, die einen Teil der Schnittstelle von pathlib.Path umsetzt, darunter die vollständige importlib.resources.abc.Traversable-Schnittstelle.

Added in version 3.8.

class zipfile.PyZipFile: Klasse zum Erzeugen von ZIP-Archiven, die Python-Bibliotheken enthalten.

class zipfile.ZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))¶

Klasse, die Angaben über einen Eintrag eines Archivs darstellt. Instanzen dieser Klasse geben die Methoden getinfo() und infolist() von ZipFile-Objekten zurück. Die meisten Nutzer des Moduls zipfile müssen sie nicht selbst erzeugen, sondern verwenden nur die von diesem Modul erzeugten. filename sollte der vollständige Name des Archiveintrags sein, und date_time sollte ein Tupel mit sechs Feldern sein, die den Zeitpunkt der letzten Änderung der Datei beschreiben. Die Felder sind im Abschnitt ZipInfo-Objekte beschrieben.

Geändert in Version 3.13: Ein öffentliches Attribut compress_level wurde hinzugefügt, das das früher geschützte _compresslevel zugänglich macht. Der ältere geschützte Name funktioniert aus Gründen der Rückwärtskompatibilität weiter als Eigenschaft.

_for_archive(archive)¶

Setzt date_time, die Kompressionsattribute und die externen Attribute auf passende Standardwerte, wie ZipFile.writestr() sie verwendet.

Gibt self zurück, damit sich Aufrufe verketten lassen.

Added in version 3.14.

zipfile.is_zipfile(filename)¶: Gibt True zurück, wenn filename anhand seiner magischen Zahl eine gültige ZIP-Datei ist, sonst False. filename kann auch eine Datei oder ein dateiähnliches Objekt sein.

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

zipfile.ZIP_STORED¶: Die Zahlenkonstante für einen unkomprimierten Archiveintrag.

zipfile.ZIP_DEFLATED¶: Die Zahlenkonstante für das übliche ZIP-Kompressionsverfahren. Dafür braucht es das Modul zlib.

zipfile.ZIP_BZIP2¶: Die Zahlenkonstante für das Kompressionsverfahren BZIP2. Dafür braucht es das Modul bz2.

Added in version 3.3.

zipfile.ZIP_LZMA¶: Die Zahlenkonstante für das Kompressionsverfahren LZMA. Dafür braucht es das Modul lzma.

Added in version 3.3.

zipfile.ZIP_ZSTANDARD¶: Die Zahlenkonstante für die Zstandard-Kompression. Dafür braucht es das Modul compression.zstd.

Bemerkung

In APPNOTE 6.3.7 war der Zstandard-Kompression die Verfahrenskennung 20 zugewiesen. In APPNOTE 6.3.8 wurde das auf die Kennung 93 geändert, um Konflikte zu vermeiden, und die Kennung 20 für veraltet erklärt. Aus Gründen der Verträglichkeit liest das Modul zipfile beide Kennungen, schreibt Daten aber nur mit der Kennung 93.

Added in version 3.14.

Bemerkung

Die Spezifikation des ZIP-Dateiformats unterstützt die bzip2-Kompression seit 2001, die LZMA-Kompression seit 2006 und die Zstandard-Kompression seit 2020. Manche Werkzeuge, darunter ältere Python-Ausgaben, unterstützen diese Verfahren allerdings nicht. Sie verweigern dann entweder die Verarbeitung der ganzen ZIP-Datei oder scheitern beim Entpacken einzelner Dateien.

Siehe auch

PKZIP Application Note: Dokumentation zum ZIP-Dateiformat von Phil Katz, dem Urheber des Formats und der verwendeten Algorithmen.
Startseite von Info-ZIP: Angaben zu den ZIP-Archivprogrammen und Entwicklungsbibliotheken des Info-ZIP-Projekts.

ZipFile-Objekte¶

class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None, *, strict_timestamps=True, metadata_encoding=None)¶

Öffnet eine ZIP-Datei, wobei file ein Pfad zu einer Datei (als Zeichenkette), ein dateiähnliches Objekt oder ein pfadähnliches Objekt sein kann.

Der Parameter mode sollte 'r' sein, um eine vorhandene Datei zu lesen, 'w', um sie zu leeren und neu zu schreiben, 'a', um an eine vorhandene Datei anzufügen, oder 'x', um eine neue Datei ausschließlich zu erzeugen und zu schreiben. Ist mode 'x' und verweist file auf eine vorhandene Datei, wird FileExistsError ausgelöst. Ist mode 'a' und verweist file auf eine vorhandene ZIP-Datei, werden ihr weitere Dateien hinzugefügt. Verweist file nicht auf eine ZIP-Datei, wird ein neues ZIP-Archiv an die Datei angehängt. Das ist dafür gedacht, ein ZIP-Archiv an eine andere Datei anzufügen, etwa an python.exe. Ist mode 'a' und die Datei gibt es überhaupt nicht, wird sie erzeugt. Ist mode 'r' oder 'a', sollte die Datei positionierbar sein.

compression ist das ZIP-Kompressionsverfahren, das beim Schreiben des Archivs verwendet wird. Es sollte ZIP_STORED, ZIP_DEFLATED, ZIP_BZIP2, ZIP_LZMA oder ZIP_ZSTANDARD sein. Bei unbekannten Werten wird NotImplementedError ausgelöst. Ist ZIP_DEFLATED, ZIP_BZIP2, ZIP_LZMA oder ZIP_ZSTANDARD angegeben, das zugehörige Modul (zlib, bz2, lzma oder compression.zstd) steht aber nicht zur Verfügung, wird RuntimeError ausgelöst. Voreingestellt ist ZIP_STORED.

Ist allowZip64 True, die Voreinstellung, erzeugt zipfile ZIP-Dateien mit den ZIP64-Erweiterungen, sobald die Datei größer als 4 GiB ist. Ist es false, löst zipfile eine Ausnahme aus, wenn die ZIP-Datei die ZIP64-Erweiterungen bräuchte.

Der Parameter compresslevel steuert die Kompressionsstufe beim Schreiben von Dateien in das Archiv. Bei ZIP_STORED und ZIP_LZMA hat er keine Wirkung. Bei ZIP_DEFLATED sind die ganzen Zahlen 0 bis 9 zulässig (Näheres unter zlib). Bei ZIP_BZIP2 sind die ganzen Zahlen 1 bis 9 zulässig (Näheres unter bz2). Bei ZIP_ZSTANDARD sind üblicherweise die ganzen Zahlen -131072 bis 22 zulässig (mehr dazu, wie man die gültigen Werte und ihre Bedeutung erfährt, unter CompressionParameter.compression_level).

Steht das Argument strict_timestamps auf False, lassen sich auch Dateien einpacken, die älter als der 01.01.1980 sind – um den Preis, dass ihr Zeitstempel auf den 01.01.1980 gesetzt wird. Bei Dateien, die neuer als der 31.12.2107 sind, geschieht Entsprechendes: Der Zeitstempel wird auf die Grenze gesetzt.

Ist mode 'r', kann metadata_encoding auf den Namen eines Codecs gesetzt werden, mit dem Metadaten wie die Namen der Einträge und ZIP-Kommentare dekodiert werden.

Wird die Datei mit mode 'w', 'x' oder 'a' erzeugt und dann geschlossen, ohne dass dem Archiv Dateien hinzugefügt wurden, werden die passenden ZIP-Strukturen für ein leeres Archiv in die Datei geschrieben.

ZipFile ist außerdem ein Kontextmanager und unterstützt daher die with-Anweisung. Im Beispiel wird myzip geschlossen, sobald der Block der with-Anweisung beendet ist — auch dann, wenn eine Ausnahme auftritt:

with ZipFile('spam.zip', 'w') as myzip:
    myzip.write('eggs.txt')

Bemerkung

metadata_encoding gilt für die gesamte ZipFile-Instanz. Es lässt sich nicht je Eintrag festlegen.

Dieses Attribut ist ein Behelf für ältere Umsetzungen, die Archive mit Namen in der Kodierung der aktuellen Locale oder Codepage erzeugen, meist unter Windows. Nach dem .ZIP-Standard lässt sich die Kodierung der Metadaten über ein Flag im Archivkopf festlegen, entweder als IBM-Codepage, die Voreinstellung, oder als UTF-8. Dieses Flag hat Vorrang vor metadata_encoding, das eine Python-eigene Erweiterung ist.

Geändert in Version 3.2: Die Möglichkeit, ZipFile als Kontextmanager zu verwenden, wurde hinzugefügt.

Geändert in Version 3.3: Unterstützung für die Kompression mit bzip2 und lzma hinzugefügt.

Geändert in Version 3.4: Die ZIP64-Erweiterungen sind voreingestellt eingeschaltet.

Geändert in Version 3.5: Unterstützung für das Schreiben in nicht positionierbare Datenströme hinzugefügt. Unterstützung für den Modus 'x' hinzugefügt.

Geändert in Version 3.6: Vorher wurde bei unbekannten Kompressionswerten ein RuntimeError ausgelöst.

Geändert in Version 3.6.2: Der Parameter file nimmt ein pfadähnliches Objekt an.

Geändert in Version 3.7: Der Parameter compresslevel wurde hinzugefügt.

Geändert in Version 3.8: Der Parameter strict_timestamps, der nur als Schlüsselwort übergeben werden kann.

Geändert in Version 3.11: Unterstützung dafür hinzugefügt, die Kodierung der Eintragsnamen anzugeben, um die Metadaten im Verzeichnis und in den Dateiköpfen der ZIP-Datei zu lesen.

ZipFile.close()¶: Schließt die Archivdatei. Du musst close() aufrufen, bevor dein Programm endet, sonst werden wesentliche Datensätze nicht geschrieben.

ZipFile.getinfo(name)¶: Gibt ein ZipInfo-Objekt mit Angaben über den Archiveintrag name zurück. Ein Aufruf von getinfo() für einen Namen, der derzeit nicht im Archiv enthalten ist, löst KeyError aus.

ZipFile.infolist()¶: Gibt eine Liste mit einem ZipInfo-Objekt für jeden Eintrag des Archivs zurück. Wurde ein vorhandenes Archiv geöffnet, stehen die Objekte in derselben Reihenfolge wie ihre Einträge in der ZIP-Datei auf der Platte.

ZipFile.namelist()¶: Gibt eine Liste der Archiveinträge nach Namen zurück.

ZipFile.open(name, mode='r', pwd=None, *, force_zip64=False)¶

Greift auf einen Eintrag des Archivs als binäres, dateiähnliches Objekt zu. name ist entweder der Name einer Datei im Archiv oder ein ZipInfo-Objekt. Der Parameter mode muss, wenn er angegeben wird, 'r' (die Voreinstellung) oder 'w' sein. pwd ist das Passwort zum Entschlüsseln verschlüsselter ZIP-Dateien, als bytes-Objekt.

open() ist außerdem ein Kontextmanager und unterstützt daher die with-Anweisung:

with ZipFile('spam.zip') as myzip:
    with myzip.open('eggs.txt') as myfile:
        print(myfile.read())

Mit mode 'r' ist das dateiähnliche Objekt (ZipExtFile) nur lesbar und bietet die folgenden Methoden: read(), readline(), readlines(), seek(), tell(), __iter__(), __next__(). Diese Objekte können unabhängig von der ZipFile arbeiten.

Mit mode='w' wird ein beschreibbares Dateihandle zurückgegeben, das die Methode write() unterstützt. Solange ein beschreibbares Dateihandle offen ist, löst der Versuch, andere Dateien der ZIP-Datei zu lesen oder zu schreiben, ValueError aus.

In beiden Fällen hat das dateiähnliche Objekt außerdem die Attribute name, das dem Namen einer Datei im Archiv entspricht, und mode, das je nach Eingabemodus 'rb' oder 'wb' ist.

Ist beim Schreiben einer Datei ihre Größe nicht vorab bekannt, könnte aber 2 GiB übersteigen, übergib force_zip64=True, damit das Kopfformat große Dateien tragen kann. Ist die Größe vorab bekannt, erzeuge ein ZipInfo-Objekt mit gesetztem file_size und übergib es als Parameter name.

Bemerkung

Die Methoden open(), read() und extract() nehmen einen Dateinamen oder ein ZipInfo-Objekt an. Das wirst du zu schätzen wissen, wenn du eine ZIP-Datei lesen willst, in der Einträge mit doppelten Namen stecken.

Geändert in Version 3.6: Die Unterstützung für mode='U' wurde entfernt. Verwende io.TextIOWrapper, um komprimierte Textdateien im Modus der universellen Zeilenumbrüche zu lesen.

Geändert in Version 3.6: ZipFile.open() lässt sich jetzt mit der Option mode='w' auch dazu verwenden, Dateien in das Archiv zu schreiben.

Geändert in Version 3.6: Ein Aufruf von open() auf einer geschlossenen ZipFile löst ValueError aus. Vorher wurde RuntimeError ausgelöst.

Geändert in Version 3.13: Die Attribute name und mode für das beschreibbare dateiähnliche Objekt wurden hinzugefügt. Der Wert des Attributs mode für das lesbare dateiähnliche Objekt wurde von 'r' auf 'rb' geändert.

ZipFile.extract(member, path=None, pwd=None)¶

Entpackt einen Eintrag des Archivs in das aktuelle Arbeitsverzeichnis. member muss sein vollständiger Name oder ein ZipInfo-Objekt sein. Die Dateiangaben werden so genau wie möglich übernommen. path gibt ein anderes Zielverzeichnis an. member kann ein Dateiname oder ein ZipInfo-Objekt sein. pwd ist das Passwort für verschlüsselte Dateien, als bytes-Objekt.

Gibt den erzeugten normalisierten Pfad zurück, ein Verzeichnis oder eine neue Datei.

Bemerkung

Ist der Dateiname eines Eintrags ein absoluter Pfad, werden Laufwerksbuchstabe beziehungsweise UNC-Freigabe sowie führende Schrägstriche entfernt. Aus ///foo/bar wird unter Unix also foo/bar, und aus C:\foo\bar wird unter Windows foo\bar. Außerdem werden alle ".."-Bestandteile aus dem Dateinamen eines Eintrags entfernt: aus ../../foo../../ba..r wird foo../ba..r. Unter Windows werden unzulässige Zeichen (:, <, >, |, ", ? und *) durch einen Unterstrich (_) ersetzt.

Geändert in Version 3.6: Ein Aufruf von extract() auf einer geschlossenen ZipFile löst ValueError aus. Vorher wurde RuntimeError ausgelöst.

Geändert in Version 3.6.2: Der Parameter path nimmt ein pfadähnliches Objekt an.

ZipFile.extractall(path=None, members=None, pwd=None)¶: Entpackt alle Einträge des Archivs in das aktuelle Arbeitsverzeichnis. path gibt ein anderes Zielverzeichnis an. members ist optional und muss eine Teilmenge der Liste sein, die namelist() zurückgibt. pwd ist das Passwort für verschlüsselte Dateien, als bytes-Objekt.

Warnung

Entpacke Archive aus nicht vertrauenswürdigen Quellen niemals, ohne sie vorher zu prüfen. Es ist möglich, dass Dateien außerhalb von path angelegt werden, etwa durch Einträge mit absoluten Dateinamen oder mit „..“-Bestandteilen im Namen. Dieses Modul versucht, das zu verhindern. Siehe den Hinweis bei extract().

Geändert in Version 3.6: Ein Aufruf von extractall() auf einer geschlossenen ZipFile löst ValueError aus. Vorher wurde RuntimeError ausgelöst.

Geändert in Version 3.6.2: Der Parameter path nimmt ein pfadähnliches Objekt an.

ZipFile.printdir()¶: Gibt ein Inhaltsverzeichnis des Archivs auf sys.stdout aus.

ZipFile.setpassword(pwd)¶: Legt pwd, ein bytes-Objekt, als voreingestelltes Passwort zum Entpacken verschlüsselter Dateien fest.

ZipFile.read(name, pwd=None)¶: Gibt die Bytes der Datei name im Archiv zurück. name ist der Name der Datei im Archiv oder ein ZipInfo-Objekt. Das Archiv muss zum Lesen oder Anfügen geöffnet sein. pwd ist das Passwort für verschlüsselte Dateien, als bytes-Objekt. Wird es angegeben, hat es Vorrang vor dem mit setpassword() festgelegten voreingestellten Passwort. Ein Aufruf von read() auf einer ZipFile, die ein anderes Kompressionsverfahren als ZIP_STORED, ZIP_DEFLATED, ZIP_BZIP2, ZIP_LZMA oder ZIP_ZSTANDARD verwendet, löst NotImplementedError aus. Ein Fehler wird auch dann ausgelöst, wenn das zugehörige Kompressionsmodul nicht zur Verfügung steht.

Geändert in Version 3.6: Ein Aufruf von read() auf einer geschlossenen ZipFile löst ValueError aus. Vorher wurde RuntimeError ausgelöst.

ZipFile.testzip()¶: Liest alle Dateien im Archiv und prüft ihre CRC-Werte und Dateiköpfe. Gibt den Namen der ersten fehlerhaften Datei zurück, sonst None.

Geändert in Version 3.6: Ein Aufruf von testzip() auf einer geschlossenen ZipFile löst ValueError aus. Vorher wurde RuntimeError ausgelöst.

ZipFile.write(filename, arcname=None, compress_type=None, compresslevel=None)¶: Schreibt die Datei mit dem Namen filename in das Archiv und gibt ihr dort den Namen arcname. Voreingestellt ist das derselbe wie filename, nur ohne Laufwerksbuchstaben und ohne führende Pfadtrennzeichen. Wird compress_type angegeben, hat es für den neuen Eintrag Vorrang vor dem Wert, der dem Konstruktor als compression übergeben wurde. Ebenso hat compresslevel Vorrang vor dem Konstruktor, wenn es angegeben wird. Das Archiv muss mit mode 'w', 'x' oder 'a' geöffnet sein.

Bemerkung

Der ZIP-Dateistandard hat historisch keine Kodierung für Metadaten festgelegt, aber CP437, die ursprüngliche IBM-PC-Kodierung, für die Zusammenarbeit nachdrücklich empfohlen. Neuere Fassungen erlauben ausschließlich UTF-8. Dieses Modul verwendet UTF-8 selbsttätig zum Schreiben der Eintragsnamen, sobald diese Zeichen außerhalb von ASCII enthalten. Eintragsnamen in einer anderen Kodierung als ASCII oder UTF-8 zu schreiben, ist nicht möglich.

Bemerkung

Archivnamen sollten relativ zur Archivwurzel sein, also nicht mit einem Pfadtrennzeichen beginnen.

Bemerkung

Enthält arcname – oder filename, wenn arcname fehlt – ein Nullbyte, wird der Name der Datei im Archiv am Nullbyte abgeschnitten.

Bemerkung

Ein führender Schrägstrich im Dateinamen kann dazu führen, dass sich das Archiv mit manchen ZIP-Programmen unter Windows nicht öffnen lässt.

Geändert in Version 3.6: Ein Aufruf von write() auf einer mit mode 'r' erzeugten oder auf einer geschlossenen ZipFile löst ValueError aus. Vorher wurde RuntimeError ausgelöst.

ZipFile.writestr(zinfo_or_arcname, data, compress_type=None, compresslevel=None)¶

Schreibt eine Datei in das Archiv. Der Inhalt ist data, entweder eine str- oder eine bytes-Instanz. Ist es str, wird es zuerst als UTF-8 kodiert. zinfo_or_arcname ist entweder der Dateiname, den die Datei im Archiv erhält, oder eine ZipInfo-Instanz. Bei einer Instanz müssen mindestens Dateiname, Datum und Uhrzeit angegeben sein. Bei einem Namen werden Datum und Uhrzeit auf das aktuelle Datum und die aktuelle Uhrzeit gesetzt. Das Archiv muss mit mode 'w', 'x' oder 'a' geöffnet sein.

Wird compress_type angegeben, hat es für den neuen Eintrag Vorrang vor dem Wert, der dem Konstruktor als compression übergeben wurde, beziehungsweise vor dem in zinfo_or_arcname, falls das eine ZipInfo-Instanz ist. Ebenso hat compresslevel Vorrang vor dem Konstruktor, wenn es angegeben wird.

Bemerkung

Wird eine ZipInfo-Instanz als Parameter zinfo_or_arcname übergeben, wird das Kompressionsverfahren verwendet, das im Feld compress_type dieser ZipInfo-Instanz angegeben ist. Voreingestellt setzt der ZipInfo-Konstruktor dieses Feld auf ZIP_STORED.

Geändert in Version 3.2: Das Argument compress_type.

Geändert in Version 3.6: Ein Aufruf von writestr() auf einer mit mode 'r' erzeugten oder auf einer geschlossenen ZipFile löst ValueError aus. Vorher wurde RuntimeError ausgelöst.

Geändert in Version 3.14: Beachtet jetzt die Umgebungsvariable SOURCE_DATE_EPOCH. Ist sie gesetzt, wird ihr Wert als Änderungszeitstempel der in das ZIP-Archiv geschriebenen Datei verwendet, nicht die aktuelle Zeit.

ZipFile.mkdir(zinfo_or_directory, mode=511)¶

Erzeugt ein Verzeichnis im Archiv. Ist zinfo_or_directory eine Zeichenkette, wird im Archiv ein Verzeichnis mit dem Modus erzeugt, der im Argument mode angegeben ist. Ist zinfo_or_directory dagegen eine ZipInfo-Instanz, wird das Argument mode ignoriert.

Das Archiv muss mit mode 'w', 'x' oder 'a' geöffnet sein.

Added in version 3.11.

Außerdem stehen die folgenden Datenattribute zur Verfügung:

ZipFile.filename¶: Name der ZIP-Datei.

ZipFile.debug¶: Die Stufe der Debug-Ausgabe. Sie lässt sich von 0 – die Voreinstellung, keine Ausgabe – bis 3 für die ausführlichste Ausgabe setzen. Die Debug-Angaben werden auf sys.stdout geschrieben.

ZipFile.comment¶: Der Kommentar zur ZIP-Datei als bytes-Objekt. Weist du einer mit mode 'w', 'x' oder 'a' erzeugten ZipFile-Instanz einen Kommentar zu, sollte er nicht länger als 65535 Bytes sein. Längere Kommentare werden abgeschnitten.

Path-Objekte¶

class zipfile.Path(root, at='')¶

Erzeugt ein Path-Objekt aus einer ZIP-Datei root, die entweder eine ZipFile-Instanz oder ein file sein kann, das sich an den ZipFile-Konstruktor übergeben lässt.

at gibt die Stelle dieses Path innerhalb der ZIP-Datei an, zum Beispiel ‚dir/file.txt‘, ‚dir/‘ oder ‚‘. Voreingestellt ist die leere Zeichenkette, also die Wurzel.

Bemerkung

Die Klasse Path bereinigt Dateinamen innerhalb des ZIP-Archivs nicht. Anders als bei den Methoden ZipFile.extract() und ZipFile.extractall() ist es Sache des Aufrufers, Dateinamen zu prüfen oder zu bereinigen, um Schwachstellen durch Pfadwechsel zu vermeiden, etwa absolute Pfade oder Pfade mit „..“-Bestandteilen. Beim Umgang mit nicht vertrauenswürdigen Archiven solltest du die Dateinamen mit os.path.abspath() auflösen und sie mit os.path.commonpath() gegen das Zielverzeichnis prüfen.

Path-Objekte machen die folgenden Eigenschaften von pathlib.Path-Objekten zugänglich:

Path-Objekte lassen sich mit dem Operator / oder mit joinpath durchlaufen.

Path.name¶: Der letzte Bestandteil des Pfades.

Path.open(mode='r', *, pwd, **)¶: Ruft ZipFile.open() auf dem aktuellen Pfad auf. Erlaubt das Öffnen zum Lesen oder Schreiben, als Text oder binär, über die unterstützten Modi ‚r‘, ‚w‘, ‚rb‘ und ‚wb‘. Positions- und Schlüsselwortargumente werden beim Öffnen als Text an io.TextIOWrapper weitergegeben, sonst ignoriert. pwd ist der Parameter pwd von ZipFile.open().

Geändert in Version 3.9: Unterstützung für Text- und Binärmodus bei open hinzugefügt. Voreingestellt ist jetzt Text.

Geändert in Version 3.11.2: Der Parameter encoding lässt sich als Positionsargument übergeben, ohne dass TypeError ausgelöst wird – so wie es in 3.9 schon möglich war. Code, der mit den ungepatchten Fassungen 3.10 und 3.11 verträglich sein muss, hat alle io.TextIOWrapper-Argumente einschließlich encoding als Schlüsselwort zu übergeben.

Path.iterdir()¶: Listet die Kindeinträge des aktuellen Verzeichnisses auf.

Path.is_dir()¶: Gibt True zurück, wenn der aktuelle Kontext auf ein Verzeichnis verweist.

Path.is_file()¶: Gibt True zurück, wenn der aktuelle Kontext auf eine Datei verweist.

Path.is_symlink()¶: Gibt True zurück, wenn der aktuelle Kontext auf eine symbolische Verknüpfung verweist.

Added in version 3.12.

Geändert in Version 3.13: Vorher gab is_symlink bedingungslos False zurück.

Path.exists()¶: Gibt True zurück, wenn der aktuelle Kontext auf eine Datei oder ein Verzeichnis in der ZIP-Datei verweist.

Path.suffix¶: Der letzte durch Punkt getrennte Teil des letzten Bestandteils, sofern vorhanden. Üblicherweise nennt man das die Dateiendung.

Added in version 3.11: Die Eigenschaft Path.suffix wurde hinzugefügt.

Path.stem¶: Der letzte Bestandteil des Pfades, ohne seine Endung.

Added in version 3.11: Die Eigenschaft Path.stem wurde hinzugefügt.

Path.suffixes¶: Eine Liste der Endungen des Pfades, üblicherweise Dateiendungen genannt.

Added in version 3.11: Die Eigenschaft Path.suffixes wurde hinzugefügt.

Path.read_text(*, **)¶: Liest die aktuelle Datei als Unicode-Text. Positions- und Schlüsselwortargumente werden an io.TextIOWrapper weitergegeben, mit Ausnahme von buffer, das sich aus dem Kontext ergibt.

Geändert in Version 3.11.2: Der Parameter encoding lässt sich als Positionsargument übergeben, ohne dass TypeError ausgelöst wird – so wie es in 3.9 schon möglich war. Code, der mit den ungepatchten Fassungen 3.10 und 3.11 verträglich sein muss, hat alle io.TextIOWrapper-Argumente einschließlich encoding als Schlüsselwort zu übergeben.

Path.read_bytes()¶: Liest die aktuelle Datei als Bytes.

Path.joinpath(*other)¶

Gibt ein neues Path-Objekt zurück, an das die Argumente other angefügt sind. Die folgenden Aufrufe sind gleichwertig:

>>> Path(...).joinpath('child').joinpath('grandchild')
>>> Path(...).joinpath('child', 'grandchild')
>>> Path(...) / 'child' / 'grandchild'

Geändert in Version 3.10: Vor 3.10 war joinpath nicht dokumentiert und nahm genau einen Parameter an.

Das Projekt zipp stellt Rückportierungen der neuesten Path-Funktionalität für ältere Python-Versionen bereit. Verwende zipp.Path anstelle von zipfile.Path, um Änderungen früher nutzen zu können.

PyZipFile-Objekte¶

Der PyZipFile-Konstruktor nimmt dieselben Parameter wie der ZipFile-Konstruktor und zusätzlich den Parameter optimize.

class zipfile.PyZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, optimize=-1)¶

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

Geändert in Version 3.4: Die ZIP64-Erweiterungen sind voreingestellt eingeschaltet.

Instanzen haben zusätzlich zu den Methoden von ZipFile-Objekten eine weitere:

writepy(pathname, basename='', filterfunc=None)¶

Sucht nach Dateien *.py und fügt die zugehörige Datei dem Archiv hinzu.

Wurde der Parameter optimize von PyZipFile nicht angegeben oder war er -1, ist die zugehörige Datei eine *.pyc-Datei, die bei Bedarf kompiliert wird.

War der Parameter optimize von PyZipFile 0, 1 oder 2, werden dem Archiv nur Dateien mit dieser Optimierungsstufe hinzugefügt (siehe compile()), die bei Bedarf kompiliert werden.

Ist pathname eine Datei, muss der Dateiname auf .py enden, und nur die zugehörige *.pyc-Datei wird auf oberster Ebene hinzugefügt, ohne Pfadangaben. Ist pathname eine Datei, die nicht auf .py endet, wird RuntimeError ausgelöst. Ist es ein Verzeichnis und kein Paketverzeichnis, werden alle Dateien *.pyc auf oberster Ebene hinzugefügt. Ist das Verzeichnis ein Paketverzeichnis, werden alle *.pyc unter dem Paketnamen als Pfad hinzugefügt, und sind Unterverzeichnisse ebenfalls Paketverzeichnisse, werden sie alle rekursiv in sortierter Reihenfolge hinzugefügt.

basename ist nur für die interne Verwendung gedacht.

filterfunc muss, wenn es angegeben wird, eine Funktion sein, die ein einzelnes Zeichenkettenargument annimmt. Ihr wird jeder Pfad übergeben, auch jeder einzelne vollständige Dateipfad, bevor er dem Archiv hinzugefügt wird. Gibt filterfunc einen falschen Wert zurück, wird der Pfad nicht hinzugefügt, und handelt es sich um ein Verzeichnis, wird sein Inhalt ignoriert. Liegen unsere Testdateien zum Beispiel alle entweder in test-Verzeichnissen oder beginnen mit der Zeichenkette test_, können wir sie mit einem filterfunc ausschließen:

>>> zf = PyZipFile('myprog.zip', 'w')
>>> def notests(s):
...     fn = os.path.basename(s)
...     return (not (fn == 'test' or fn.startswith('test_')))
...
>>> zf.writepy('myprog', filterfunc=notests)

Die Methode writepy() erzeugt Archive mit Dateinamen wie diesen:

string.pyc                   # Top level name
test/__init__.pyc            # Package directory
test/testall.pyc             # Module test.testall
test/bogus/__init__.pyc      # Subpackage directory
test/bogus/myfile.pyc        # Submodule test.bogus.myfile

Geändert in Version 3.4: Der Parameter filterfunc wurde hinzugefügt.

Geändert in Version 3.6.2: Der Parameter pathname nimmt ein pfadähnliches Objekt an.

Geändert in Version 3.7: Die Rekursion sortiert die Verzeichniseinträge.

ZipInfo-Objekte¶

Instanzen der Klasse ZipInfo geben die Methoden getinfo() und infolist() von ZipFile-Objekten zurück. Jedes Objekt enthält die Angaben zu einem einzelnen Eintrag des ZIP-Archivs.

Es gibt eine Klassenmethode, um eine ZipInfo-Instanz für eine Datei im Dateisystem zu erzeugen:

classmethod ZipInfo.from_file(filename, arcname=None, *, strict_timestamps=True)¶

Erzeugt eine ZipInfo-Instanz für eine Datei im Dateisystem, um sie anschließend einer ZIP-Datei hinzuzufügen.

filename sollte der Pfad zu einer Datei oder einem Verzeichnis im Dateisystem sein.

Ist arcname angegeben, wird es als Name innerhalb des Archivs verwendet. Fehlt arcname, entspricht der Name filename, nur ohne Laufwerksbuchstaben und ohne führende Pfadtrennzeichen.

Steht das Argument strict_timestamps auf False, lassen sich auch Dateien einpacken, die älter als der 01.01.1980 sind – um den Preis, dass ihr Zeitstempel auf den 01.01.1980 gesetzt wird. Bei Dateien, die neuer als der 31.12.2107 sind, geschieht Entsprechendes: Der Zeitstempel wird auf die Grenze gesetzt.

Added in version 3.6.

Geändert in Version 3.6.2: Der Parameter filename nimmt ein pfadähnliches Objekt an.

Geändert in Version 3.8: Der Parameter strict_timestamps, der nur als Schlüsselwort übergeben werden kann, wurde hinzugefügt.

Instanzen haben die folgenden Methoden und Attribute:

ZipInfo.is_dir()¶

Gibt True zurück, wenn dieser Archiveintrag ein Verzeichnis ist.

Dazu wird der Name des Eintrags verwendet: Verzeichnisse sollten immer auf / enden.

Added in version 3.6.

ZipInfo.filename¶: Name der Datei im Archiv.

ZipInfo.date_time¶

Uhrzeit und Datum der letzten Änderung des Archiveintrags. Das ist ein Tupel aus sechs Werten, die den Feldern „last [modified] file time“ und „last [modified] file date“ im zentralen Verzeichnis der ZIP-Datei entsprechen.

Das Tupel enthält:

Index	Wert
`0`	Jahr (>= 1980)
`1`	Monat (ab 1 gezählt)
`2`	Tag des Monats (ab 1 gezählt)
`3`	Stunden (ab 0 gezählt)
`4`	Minuten (ab 0 gezählt)
`5`	Sekunden (ab 0 gezählt)

Bemerkung

Das ZIP-Format kennt mehrere Zeitstempelfelder an verschiedenen Stellen: im zentralen Verzeichnis, in Zusatzfeldern für NTFS- und UNIX-Systeme und so weiter. Dieses Attribut gibt ausdrücklich den Zeitstempel aus dem zentralen Verzeichnis zurück. Dessen Zeitstempelformat unterstützt in ZIP-Dateien keine Zeitpunkte vor 1980. Manche Formate für Zusatzfelder, etwa UNIX-Zeitstempel, können frühere Daten darstellen, dieses Attribut gibt aber nur den Zeitstempel aus dem zentralen Verzeichnis zurück.

Der Zeitstempel aus dem zentralen Verzeichnis wird als Ortszeit gedeutet, nicht als UTC, damit sich das Verhalten mit dem anderer ZIP-Werkzeuge deckt.

ZipInfo.compress_type¶: Art der Kompression des Archiveintrags.

ZipInfo.comment¶: Kommentar zum einzelnen Archiveintrag als bytes-Objekt.

ZipInfo.extra¶: Daten des Erweiterungsfeldes. Die PKZIP Application Note enthält einige Anmerkungen zum inneren Aufbau der Daten in diesem bytes-Objekt.

ZipInfo.create_system¶: System, das das ZIP-Archiv erzeugt hat.

ZipInfo.create_version¶: PKZIP-Version, die das ZIP-Archiv erzeugt hat.

ZipInfo.extract_version¶: PKZIP-Version, die zum Entpacken des Archivs nötig ist.

ZipInfo.reserved¶: Muss Null sein.

ZipInfo.flag_bits¶: ZIP-Flag-Bits.

ZipInfo.volume¶: Datenträgernummer des Dateikopfes.

ZipInfo.internal_attr¶: Interne Attribute.

ZipInfo.external_attr¶: Externe Dateiattribute.

ZipInfo.header_offset¶: Byte-Abstand zum Dateikopf.

ZipInfo.CRC¶: CRC-32 der unkomprimierten Datei.

ZipInfo.compress_size¶: Größe der komprimierten Daten.

ZipInfo.file_size¶: Größe der unkomprimierten Datei.

Befehlszeilenschnittstelle¶

Das Modul zipfile bietet eine einfache Befehlszeilenschnittstelle für die Arbeit mit ZIP-Archiven.

Willst du ein neues ZIP-Archiv erzeugen, gib seinen Namen nach der Option -c an und führe dann die Dateinamen auf, die hinein sollen:

$ python -m zipfile -c monty.zip spam.txt eggs.txt

Auch ein Verzeichnis ist zulässig:

$ python -m zipfile -c monty.zip life-of-brian_1979/

Willst du ein ZIP-Archiv in das angegebene Verzeichnis entpacken, verwende die Option -e:

$ python -m zipfile -e monty.zip target-dir/

Für eine Liste der Dateien in einem ZIP-Archiv verwende die Option -l:

$ python -m zipfile -l monty.zip

Optionen der Befehlszeile¶

-l <zipfile>¶
--list <zipfile>¶: Listet die Dateien einer ZIP-Datei auf.

-c <zipfile> <source1> ... <sourceN>¶
--create <zipfile> <source1> ... <sourceN>¶: Erzeugt eine ZIP-Datei aus Quelldateien.

-e <zipfile> <output_dir>¶
--extract <zipfile> <output_dir>¶: Entpackt eine ZIP-Datei in das Zielverzeichnis.

-t <zipfile>¶
--test <zipfile>¶: Prüft, ob die ZIP-Datei gültig ist.

--metadata-encoding <encoding>¶: Gibt die Kodierung der Eintragsnamen für -l, -e und -t an.

Added in version 3.11.

Fallstricke beim Entpacken¶

Das Entpacken im Modul zipfile kann aus den unten aufgeführten Gründen fehlschlagen.

Durch die Datei selbst¶

Das Entpacken kann an einem falschen Passwort, einer falschen CRC-Prüfsumme, einem falschen ZIP-Format oder an einem nicht unterstützten Kompressions- oder Entschlüsselungsverfahren scheitern.

Grenzen des Dateisystems¶

Werden Grenzen des jeweiligen Dateisystems überschritten, kann das Entpacken fehlschlagen. Dazu gehören die zulässigen Zeichen in Verzeichniseinträgen, die Länge des Dateinamens, die Länge des Pfades, die Größe einer einzelnen Datei und die Anzahl der Dateien.

Grenzen der Ressourcen¶

Fehlender Speicher oder fehlender Platz auf dem Datenträger lässt das Entpacken fehlschlagen. So wirken etwa Entpackbomben, auch ZIP bomb genannt, auch auf die Bibliothek zipfile und können den Platz auf dem Datenträger erschöpfen.

Unterbrechung¶

Eine Unterbrechung während des Entpackens, etwa durch Strg-C oder durch das Abschießen des Entpackvorgangs, kann dazu führen, dass das Archiv nur unvollständig entpackt ist.

Voreingestelltes Verhalten beim Entpacken¶

Wer das voreingestellte Verhalten beim Entpacken nicht kennt, kann unerwartete Ergebnisse erhalten. Entpackt man dasselbe Archiv zum Beispiel zweimal, werden Dateien ohne Rückfrage überschrieben.

`zipfile` — Mit ZIP-Archiven arbeiten¶

ZipFile-Objekte¶

Path-Objekte¶

PyZipFile-Objekte¶

ZipInfo-Objekte¶

Befehlszeilenschnittstelle¶

Optionen der Befehlszeile¶

Fallstricke beim Entpacken¶

Durch die Datei selbst¶

Grenzen des Dateisystems¶

Grenzen der Ressourcen¶

Unterbrechung¶

Voreingestelltes Verhalten beim Entpacken¶

Inhaltsverzeichnis

Vorheriges Thema

Nächstes Thema

Diese Seite

zipfile — Mit ZIP-Archiven arbeiten¶

ZipFile-Objekte¶

Path-Objekte¶

PyZipFile-Objekte¶

ZipInfo-Objekte¶

Befehlszeilenschnittstelle¶

Optionen der Befehlszeile¶

Fallstricke beim Entpacken¶

Durch die Datei selbst¶

Grenzen des Dateisystems¶

Grenzen der Ressourcen¶

Unterbrechung¶

Voreingestelltes Verhalten beim Entpacken¶

`zipfile` — Mit ZIP-Archiven arbeiten¶