tempfile — Temporäre Dateien und Verzeichnisse generieren

Quellcode: Lib/tempfile.py

Dieses Modul erstellt temporäre Dateien und Verzeichnisse. Es funktioniert auf allen unterstützten Plattformen. TemporaryFile, NamedTemporaryFile, TemporaryDirectory und SpooledTemporaryFile sind High-Level-Schnittstellen, die eine automatische Bereinigung bieten und als Kontextmanager verwendet werden können. mkstemp() und mkdtemp() sind Low-Level-Funktionen, die eine manuelle Bereinigung erfordern.

Alle benutzbaren Funktionen und Konstruktoren akzeptieren zusätzliche Argumente, die eine direkte Kontrolle über den Speicherort und den Namen von temporären Dateien und Verzeichnissen ermöglichen. Dateinamen, die von diesem Modul verwendet werden, enthalten eine Zeichenkette zufälliger Zeichen, die eine sichere Erstellung dieser Dateien in gemeinsamen temporären Verzeichnissen ermöglicht. Um die Abwärtskompatibilität zu wahren, ist die Reihenfolge der Argumente etwas ungewöhnlich; es wird empfohlen, Schlüsselwortargumente für mehr Klarheit zu verwenden.

Das Modul definiert die folgenden benutzbaren Elemente

tempfile.TemporaryFile(mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)

Gibt ein dateiähnliches Objekt zurück, das als temporärer Speicherbereich verwendet werden kann. Die Datei wird sicher erstellt, unter Verwendung derselben Regeln wie bei mkstemp(). Sie wird zerstört, sobald sie geschlossen wird (einschließlich eines impliziten Schließens, wenn das Objekt garbage collected wird). Unter Unix wird der Verzeichniseintrag der Datei entweder gar nicht erstellt oder unmittelbar nach der Erstellung der Datei entfernt. Andere Plattformen unterstützen dies nicht; Ihr Code sollte sich nicht darauf verlassen, dass eine temporäre Datei, die mit dieser Funktion erstellt wurde, einen sichtbaren Namen im Dateisystem hat oder nicht.

Das resultierende Objekt kann als Kontextmanager verwendet werden (siehe Beispiele). Nach Abschluss des Kontexts oder der Zerstörung des Datei-Objekts wird die temporäre Datei aus dem Dateisystem entfernt.

Der Parameter mode hat standardmäßig 'w+b', sodass die erstellte Datei gelesen und geschrieben werden kann, ohne sie zu schließen. Der binäre Modus wird verwendet, damit er auf allen Plattformen konsistent funktioniert, unabhängig von den gespeicherten Daten. buffering, encoding, errors und newline werden wie für open() interpretiert.

Die Parameter dir, prefix und suffix haben die gleiche Bedeutung und Standardwerte wie bei mkstemp().

Das zurückgegebene Objekt ist auf POSIX-Plattformen ein echtes Datei-Objekt. Auf anderen Plattformen ist es ein dateiähnliches Objekt, dessen Attribut file das zugrunde liegende echte Datei-Objekt ist.

Das Flag os.O_TMPFILE wird verwendet, wenn es verfügbar und funktionsfähig ist (Linux-spezifisch, erfordert Linux-Kernel 3.11 oder neuer).

Auf Plattformen, die weder Posix noch Cygwin sind, ist TemporaryFile ein Alias für NamedTemporaryFile.

Löst ein Audit-Ereignis tempfile.mkstemp mit dem Argument fullpath aus.

Geändert in Version 3.5: Das Flag os.O_TMPFILE wird nun verwendet, wenn es verfügbar ist.

Geändert in Version 3.8: Parameter errors hinzugefügt.

tempfile.NamedTemporaryFile(mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, delete=True, *, errors=None, delete_on_close=True)

Diese Funktion arbeitet genau wie TemporaryFile(), mit den folgenden Unterschieden

  • Diese Funktion gibt eine Datei zurück, die garantiert einen sichtbaren Namen im Dateisystem hat.

  • Zur Verwaltung der benannten Datei erweitert sie die Parameter von TemporaryFile() um die Parameter delete und delete_on_close, die bestimmen, ob und wie die benannte Datei automatisch gelöscht werden soll.

Das zurückgegebene Objekt ist immer ein dateiähnliches Objekt, dessen Attribut file das zugrunde liegende echte Datei-Objekt ist. Dieses dateiähnliche Objekt kann in einer with-Anweisung verwendet werden, genau wie eine normale Datei. Der Name der temporären Datei kann aus dem Attribut name des zurückgegebenen dateiähnlichen Objekts abgerufen werden. Unter Unix wird im Gegensatz zu TemporaryFile() der Verzeichniseintrag nicht sofort nach der Dateierstellung aus dem Verzeichnis entfernt.

Wenn delete wahr ist (Standard) und delete_on_close wahr ist (Standard), wird die Datei gelöscht, sobald sie geschlossen wird. Wenn delete wahr ist und delete_on_close falsch ist, wird die Datei nur beim Verlassen des Kontextmanagers gelöscht, oder wenn das dateiähnliche Objekt finalisiert wird. Die Löschung ist in diesem Fall nicht immer garantiert (siehe object.__del__()). Wenn delete falsch ist, wird der Wert von delete_on_close ignoriert.

Um den Namen der temporären Datei zur Wiedereröffnung der Datei nach dem Schließen zu verwenden, stellen Sie entweder sicher, dass die Datei nicht beim Schließen gelöscht wird (setzen Sie den Parameter delete auf falsch) oder, falls die temporäre Datei in einer with-Anweisung erstellt wird, setzen Sie den Parameter delete_on_close auf falsch. Letzterer Ansatz wird empfohlen, da er bei der automatischen Bereinigung der temporären Datei beim Verlassen des Kontextmanagers hilft.

Das erneute Öffnen der temporären Datei über ihren Namen, während sie noch geöffnet ist, funktioniert wie folgt

  • Unter POSIX kann die Datei immer wieder geöffnet werden.

  • Unter Windows stellen Sie sicher, dass mindestens eine der folgenden Bedingungen erfüllt ist

    • delete ist falsch

    • zusätzliches Öffnen teilt sich den Löschzugriff (z. B. durch Aufruf von os.open() mit dem Flag O_TEMPORARY)

    • delete ist wahr, aber delete_on_close ist falsch. Beachten Sie, dass in diesem Fall die zusätzlichen Öffnungen, die den Löschzugriff nicht teilen (z. B. über das eingebaute open() erstellt), vor dem Verlassen des Kontextmanagers geschlossen werden müssen, andernfalls schlägt der os.unlink()-Aufruf beim Verlassen des Kontextmanagers mit einem PermissionError fehl.

Unter Windows, wenn delete_on_close falsch ist und die Datei in einem Verzeichnis erstellt wird, für das der Benutzer keine Löschzugriffsberechtigung hat, schlägt der Aufruf von os.unlink() beim Verlassen des Kontextmanagers mit einem PermissionError fehl. Dies kann nicht passieren, wenn delete_on_close wahr ist, da der Löschzugriff durch das Öffnen angefordert wird, was sofort fehlschlägt, wenn der angeforderte Zugriff nicht gewährt wird.

Unter POSIX (nur) kann ein Prozess, der abrupt mit SIGKILL beendet wird, keine von ihm erstellten NamedTemporaryFiles automatisch löschen.

Löst ein Audit-Ereignis tempfile.mkstemp mit dem Argument fullpath aus.

Geändert in Version 3.8: Parameter errors hinzugefügt.

Geändert in Version 3.12: Parameter delete_on_close hinzugefügt.

class tempfile.SpooledTemporaryFile(max_size=0, mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)

Diese Klasse arbeitet genau wie TemporaryFile(), außer dass Daten im Speicher gehalten werden, bis die Dateigröße max_size überschreitet, oder bis die Methode fileno() der Datei aufgerufen wird. Zu diesem Zeitpunkt werden die Inhalte auf die Festplatte geschrieben und die Operation wird fortgesetzt wie bei TemporaryFile().

rollover()

Die resultierende Datei hat eine zusätzliche Methode, rollover(), die dazu führt, dass die Datei unabhängig von ihrer Größe auf eine Festplattendatei umgestellt wird.

Das zurückgegebene Objekt ist ein dateiähnliches Objekt, dessen Attribut _file entweder ein io.BytesIO- oder io.TextIOWrapper-Objekt ist (abhängig davon, ob der binäre oder Textmodus angegeben wurde) oder ein echtes Datei-Objekt, je nachdem, ob rollover() aufgerufen wurde. Dieses dateiähnliche Objekt kann wie eine normale Datei in einer with-Anweisung verwendet werden.

Geändert in Version 3.3: Die Methode truncate akzeptiert nun ein Argument size.

Geändert in Version 3.8: Parameter errors hinzugefügt.

Geändert in Version 3.11: Implementiert vollständig die abstrakten Basisklassen io.BufferedIOBase und io.TextIOBase (abhängig davon, ob der binäre oder Textmodus angegeben wurde).

class tempfile.TemporaryDirectory(suffix=None, prefix=None, dir=None, ignore_cleanup_errors=False, *, delete=True)

Diese Klasse erstellt sicher ein temporäres Verzeichnis, unter Verwendung derselben Regeln wie bei mkdtemp(). Das resultierende Objekt kann als Kontextmanager verwendet werden (siehe Beispiele). Nach Abschluss des Kontexts oder der Zerstörung des temporären Verzeichnisobjekts werden das neu erstellte temporäre Verzeichnis und alle seine Inhalte aus dem Dateisystem entfernt.

name

Der Verzeichnisname kann aus dem Attribut name des zurückgegebenen Objekts abgerufen werden. Wenn das zurückgegebene Objekt als Kontextmanager verwendet wird, wird der name der Zielvariable der as-Klausel in der with-Anweisung zugewiesen, falls vorhanden.

cleanup()

Das Verzeichnis kann explizit durch Aufruf der Methode cleanup() bereinigt werden. Wenn ignore_cleanup_errors wahr ist, werden alle unbehandelten Ausnahmen während der expliziten oder impliziten Bereinigung (wie ein PermissionError beim Entfernen geöffneter Dateien unter Windows) ignoriert, und die verbleibenden löschbaren Elemente werden "nach bestem Vermögen" gelöscht. Andernfalls werden im jeweiligen Kontext, in dem die Bereinigung stattfindet (der Aufruf von cleanup(), das Verlassen des Kontextmanagers, wenn das Objekt garbage collected wird oder während des Beendens des Interpreters), Fehler ausgelöst.

Der Parameter delete kann verwendet werden, um die Bereinigung des Verzeichnisbaums beim Verlassen des Kontexts zu deaktivieren. Obwohl es für einen Kontextmanager ungewöhnlich erscheinen mag, die Aktion beim Verlassen des Kontexts zu deaktivieren, kann dies beim Debuggen oder wenn Sie möchten, dass Ihr Bereinigungsverhalten bedingt von anderer Logik abhängt, nützlich sein.

Löst ein Audit-Ereignis tempfile.mkdtemp mit dem Argument fullpath aus.

Hinzugefügt in Version 3.2.

Geändert in Version 3.10: Parameter ignore_cleanup_errors hinzugefügt.

Geändert in Version 3.12: Parameter delete hinzugefügt.

tempfile.mkstemp(suffix=None, prefix=None, dir=None, text=False)

Erstellt eine temporäre Datei auf die sicherste mögliche Weise. Es gibt keine Race Conditions bei der Erstellung der Datei, vorausgesetzt, die Plattform implementiert das Flag os.O_EXCL für os.open() korrekt. Die Datei ist nur für den erstellenden Benutzer lesbar und beschreibbar. Wenn die Plattform Berechtigungsbits verwendet, um anzugeben, ob eine Datei ausführbar ist, ist die Datei für niemanden ausführbar. Der Dateideskriptor wird nicht an Kindprozesse vererbt.

Im Gegensatz zu TemporaryFile() ist der Benutzer von mkstemp() dafür verantwortlich, die temporäre Datei zu löschen, wenn er sie nicht mehr benötigt.

Wenn suffix nicht None ist, endet der Dateiname mit diesem Suffix; andernfalls gibt es kein Suffix. mkstemp() fügt keinen Punkt zwischen Dateiname und Suffix ein; wenn Sie einen benötigen, setzen Sie ihn an den Anfang von suffix.

Wenn prefix nicht None ist, beginnt der Dateiname mit diesem Präfix; andernfalls wird ein Standardpräfix verwendet. Standardmäßig ist dies der Rückgabewert von gettempprefix() oder gettempprefixb(), je nachdem.

Wenn dir nicht None ist, wird die Datei in diesem Verzeichnis erstellt; andernfalls wird ein Standardverzeichnis verwendet. Das Standardverzeichnis wird aus einer plattformabhängigen Liste ausgewählt, aber der Benutzer der Anwendung kann den Verzeichnisspeicherort steuern, indem er die Umgebungsvariablen TMPDIR, TEMP oder TMP setzt. Es gibt daher keine Garantie, dass der generierte Dateiname nützliche Eigenschaften hat, wie z. B. dass er nicht zitiert werden muss, wenn er über os.popen() an externe Befehle übergeben wird.

Wenn eines der Argumente suffix, prefix und dir nicht None ist, müssen sie vom gleichen Typ sein. Wenn sie Bytes sind, wird der zurückgegebene Name Bytes anstelle von str sein. Wenn Sie einen Byte-Rückgabewert mit ansonsten Standardverhalten erzwingen möchten, übergeben Sie suffix=b''.

Wenn text angegeben und wahr ist, wird die Datei im Textmodus geöffnet. Andernfalls (Standard) wird die Datei im Binärmodus geöffnet.

mkstemp() gibt ein Tupel zurück, das einen Betriebssystem-Handle für eine offene Datei (wie von os.open() zurückgegeben) und den absoluten Pfad dieser Datei enthält, in dieser Reihenfolge.

Löst ein Audit-Ereignis tempfile.mkstemp mit dem Argument fullpath aus.

Geändert in Version 3.5: suffix, prefix und dir können jetzt als Bytes übergeben werden, um einen Byte-Rückgabewert zu erhalten. Zuvor war nur str erlaubt. suffix und prefix akzeptieren nun und verwenden standardmäßig None, um einen geeigneten Standardwert zu verwenden.

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

tempfile.mkdtemp(suffix=None, prefix=None, dir=None)

Erstellt ein temporäres Verzeichnis auf die sicherste mögliche Weise. Es gibt keine Race Conditions bei der Erstellung des Verzeichnisses. Das Verzeichnis ist nur für den erstellenden Benutzer lesbar, beschreibbar und durchsuchbar.

Der Benutzer von mkdtemp() ist dafür verantwortlich, das temporäre Verzeichnis und seinen Inhalt zu löschen, wenn er sie nicht mehr benötigt.

Die Argumente prefix, suffix und dir sind die gleichen wie bei mkstemp().

mkdtemp() gibt den absoluten Pfad des neuen Verzeichnisses zurück.

Löst ein Audit-Ereignis tempfile.mkdtemp mit dem Argument fullpath aus.

Geändert in Version 3.5: suffix, prefix und dir können jetzt als Bytes übergeben werden, um einen Byte-Rückgabewert zu erhalten. Zuvor war nur str erlaubt. suffix und prefix akzeptieren nun und verwenden standardmäßig None, um einen geeigneten Standardwert zu verwenden.

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

Geändert in Version 3.12: mkdtemp() gibt jetzt immer einen absoluten Pfad zurück, auch wenn dir relativ ist.

tempfile.gettempdir()

Gibt den Namen des Verzeichnisses zurück, das für temporäre Dateien verwendet wird. Dies definiert den Standardwert für das Argument dir für alle Funktionen in diesem Modul.

Python durchsucht eine Standardliste von Verzeichnissen, um eines zu finden, in dem der aufrufende Benutzer Dateien erstellen kann. Die Liste lautet

  1. Das Verzeichnis, das durch die Umgebungsvariable TMPDIR benannt ist.

  2. Das Verzeichnis, das durch die Umgebungsvariable TEMP benannt ist.

  3. Das Verzeichnis, das durch die Umgebungsvariable TMP benannt ist.

  4. Ein plattformspezifischer Speicherort

    • Unter Windows die Verzeichnisse C:\TEMP, C:\TMP, \TEMP und \TMP, in dieser Reihenfolge.

    • Auf allen anderen Plattformen die Verzeichnisse /tmp, /var/tmp und /usr/tmp, in dieser Reihenfolge.

  5. Als letzte Möglichkeit das aktuelle Arbeitsverzeichnis.

Das Ergebnis dieser Suche wird zwischengespeichert, siehe Beschreibung von tempdir unten.

Geändert in Version 3.10: Gibt immer eine Zeichenkette zurück. Zuvor wurde jeder Wert von tempdir unabhängig von seinem Typ zurückgegeben, solange er nicht None war.

tempfile.gettempdirb()

Dasselbe wie gettempdir(), aber der Rückgabewert ist in Bytes.

Hinzugefügt in Version 3.5.

tempfile.gettempprefix()

Gibt das für die Erstellung temporärer Dateien verwendete Dateinamenspräfix zurück. Dieses enthält nicht die Verzeichnungskomponente.

tempfile.gettempprefixb()

Wie gettempprefix(), aber der Rückgabewert ist in Bytes.

Hinzugefügt in Version 3.5.

Das Modul verwendet eine globale Variable, um den Namen des Verzeichnisses für temporäre Dateien zu speichern, der von gettempdir() zurückgegeben wird. Diese kann direkt gesetzt werden, um den Auswahlprozess zu überschreiben, dies wird jedoch nicht empfohlen. Alle Funktionen in diesem Modul akzeptieren ein Argument dir, mit dem das Verzeichnis angegeben werden kann. Dies ist der empfohlene Ansatz, der kein anderes unachtsam geschriebenes Programm durch Ändern des globalen API-Verhaltens überrascht.

tempfile.tempdir

Wenn dieser Wert auf etwas anderes als None gesetzt ist, definiert diese Variable den Standardwert für das Argument dir für die in diesem Modul definierten Funktionen, einschließlich seines Typs (Bytes oder String). Es kann kein pfadähnliches Objekt sein.

Wenn tempdir bei einem Aufruf einer der obigen Funktionen außer gettempprefix() gleich None ist (Standard), wird es gemäß dem in gettempdir() beschriebenen Algorithmus initialisiert.

Hinweis

Beachten Sie, dass die globale Standardrückgabe von mkstemp() und mkdtemp() auf Bytes geändert wird, wenn Sie tempdir auf einen Byte-Wert setzen. Dies geschieht, wenn keine expliziten String-Argumente für prefix, suffix oder dir übergeben werden. Bitte schreiben Sie keinen Code, der dieses Verhalten erwartet oder davon abhängt. Dieses umständliche Verhalten wird aus Kompatibilitätsgründen mit der historischen Implementierung beibehalten.

Beispiele

Hier sind einige Beispiele für die typische Verwendung des Moduls tempfile

>>> import tempfile

# create a temporary file and write some data to it
>>> fp = tempfile.TemporaryFile()
>>> fp.write(b'Hello world!')
# read data from file
>>> fp.seek(0)
>>> fp.read()
b'Hello world!'
# close the file, it will be removed
>>> fp.close()

# create a temporary file using a context manager
>>> with tempfile.TemporaryFile() as fp:
...     fp.write(b'Hello world!')
...     fp.seek(0)
...     fp.read()
b'Hello world!'
>>>
# file is now closed and removed

# create a temporary file using a context manager
# close the file, use the name to open the file again
>>> with tempfile.NamedTemporaryFile(delete_on_close=False) as fp:
...     fp.write(b'Hello world!')
...     fp.close()
... # the file is closed, but not removed
... # open the file again by using its name
...     with open(fp.name, mode='rb') as f:
...         f.read()
b'Hello world!'
>>>
# file is now removed

# create a temporary directory using the context manager
>>> with tempfile.TemporaryDirectory() as tmpdirname:
...     print('created temporary directory', tmpdirname)
>>>
# directory and contents have been removed

Veraltete Funktionen und Variablen

Eine historische Methode zur Erstellung temporärer Dateien bestand darin, zuerst mit der Funktion mktemp() einen Dateinamen zu generieren und dann mit diesem Namen eine Datei zu erstellen. Leider ist dies nicht sicher, da ein anderer Prozess eine Datei mit diesem Namen erstellen könnte, bevor der erste Prozess versucht, die Datei zu erstellen. Die Lösung besteht darin, die beiden Schritte zu kombinieren und die Datei sofort zu erstellen. Dieser Ansatz wird von mkstemp() und den oben beschriebenen Funktionen verwendet.

tempfile.mktemp(suffix='', prefix='tmp', dir=None)

Seit Version 2.3 veraltet: Verwenden Sie stattdessen mkstemp().

Gibt einen absoluten Pfad zu einer Datei zurück, die zum Zeitpunkt des Aufrufs nicht existierte. Die Argumente prefix, suffix und dir sind ähnlich wie bei mkstemp(), mit der Ausnahme, dass Byte-Dateinamen sowie suffix=None und prefix=None nicht unterstützt werden.

Warnung

Die Verwendung dieser Funktion kann eine Sicherheitslücke in Ihrem Programm einführen. Bis zu dem Zeitpunkt, an dem Sie mit dem zurückgegebenen Dateinamen etwas tun, könnte jemand anderes Ihnen zuvorgekommen sein. Die Verwendung von mktemp() kann einfach durch NamedTemporaryFile() ersetzt werden, indem der Parameter delete=False übergeben wird.

>>> f = NamedTemporaryFile(delete=False)
>>> f.name
'/tmp/tmptjujjt'
>>> f.write(b"Hello World!\n")
13
>>> f.close()
>>> os.unlink(f.name)
>>> os.path.exists(f.name)
False