tempfile — Skapa temporära filer och kataloger

Källkod: Lib/tempfile.py

Den här modulen skapar temporära filer och kataloger. Den fungerar på alla plattformar som stöds. TemporaryFile, NamedTemporaryFile, TemporaryDirectory och SpooledTemporaryFile är högnivågränssnitt som ger automatisk rensning och kan användas som kontexthanterare. mkstemp() och mkdtemp() är funktioner på lägre nivå som kräver manuell rensning.

Alla funktioner och konstruktörer som kan anropas av användaren tar ytterligare argument som ger direkt kontroll över platsen för och namnet på temporära filer och kataloger. Filnamn som används av denna modul innehåller en sträng med slumpmässiga tecken som gör att dessa filer kan skapas på ett säkert sätt i delade temporära kataloger. För att upprätthålla bakåtkompatibilitet är argumentordningen något udda; det rekommenderas att använda nyckelordsargument för tydlighetens skull.

Modulen definierar följande användaranropsbara objekt:

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

Returnerar ett filliknande objekt som kan användas som ett tillfälligt lagringsutrymme. Filen skapas på ett säkert sätt med samma regler som mkstemp(). Den kommer att förstöras så snart den stängs (inklusive en implicit stängning när objektet garbage collected). Under Unix skapas antingen inte katalogposten för filen alls eller så tas den bort omedelbart efter att filen har skapats. Andra plattformar stöder inte detta; din kod bör inte förlita sig på att en temporär fil som skapats med denna funktion har eller inte har ett synligt namn i filsystemet.

Det resulterande objektet kan användas som en kontexthanterare (se Exempel). När kontexten är klar eller filobjektet förstörs kommer den temporära filen att tas bort från filsystemet.

Parametern mode är som standard inställd på 'w+b' så att den fil som skapas kan läsas och skrivas utan att stängas. Binary mode används så att den beter sig konsekvent på alla plattformar utan hänsyn till vilka data som lagras. buffring, kodning, fel och ny linje tolkas som för open().

Parametrarna dir, prefix och suffix har samma betydelse och standardvärden som i mkstemp().

Det returnerade objektet är ett äkta filobjekt på POSIX-plattformar. På andra plattformar är det ett filliknande objekt vars file-attribut är det underliggande äkta filobjektet.

Flaggan os.O_TMPFILE används om den är tillgänglig och fungerar (Linux-specifik, kräver Linux-kärnan 3.11 eller senare).

På plattformar som varken är Posix eller Cygwin är TemporaryFile ett alias för NamedTemporaryFile.

Utlöser en auditing event tempfile.mkstemp med argumentet fullpath.

Ändrad i version 3.5: Flaggan os.O_TMPFILE används nu om den är tillgänglig.

Ändrad i version 3.8: Lagt till parametern errors.

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)

Den här funktionen fungerar precis som TemporaryFile(), med undantag för följande skillnader:

  • Denna funktion returnerar en fil som garanterat har ett synligt namn i filsystemet.

  • För att hantera den namngivna filen utökas parametrarna i TemporaryFile() med parametrarna delete och delete_on_close som avgör om och hur den namngivna filen ska raderas automatiskt.

Det returnerade objektet är alltid ett filliknande objekt vars file-attribut är det underliggande riktiga filobjektet. Detta filliknande objekt kan användas i en with-sats, precis som en vanlig fil. Namnet på den temporära filen kan hämtas från attributet name i det returnerade filliknande objektet. På Unix, till skillnad från med TemporaryFile(), blir inte katalogposten avlänkad omedelbart efter att filen skapats.

Om delete är true (standard) och delete_on_close är true (standard) raderas filen så snart den har stängts. Om delete är true och delete_on_close är false raderas filen endast när kontexthanteraren avslutas, eller när file-like object avslutas. Radering är inte alltid garanterad i detta fall (se object.__del__()). Om delete är false ignoreras värdet för delete_on_close.

Om du vill använda namnet på den temporära filen för att öppna filen igen efter att ha stängt den måste du antingen se till att inte radera filen vid stängning (ange att parametern delete ska vara false) eller, om den temporära filen skapas i en with-sats, ange att parametern delete_on_close ska vara false. Den senare metoden rekommenderas eftersom den hjälper till att automatiskt rensa den temporära filen när kontexthanteraren avslutas.

Att öppna den tillfälliga filen igen med dess namn medan den fortfarande är öppen fungerar på följande sätt:

  • På POSIX kan filen alltid öppnas igen.

  • I Windows ska du kontrollera att minst ett av följande villkor är uppfyllt:

    • delete är falskt

    • ytterligare öppna aktier radera åtkomst (t.ex. genom att anropa os.open() med flaggan O_TEMPORARY)

    • delete är sant men delete_on_close är falskt. Observera att i detta fall måste de ytterligare öppningar som inte delar delete-åtkomst (t.ex. skapade via inbyggda open()) stängas innan kontexthanteraren avslutas, annars kommer os.unlink()-anropet vid kontexthanterarens avslutning att misslyckas med ett PermissionError.

I Windows, om delete_on_close är false och filen skapas i en katalog som användaren saknar delete-åtkomst till, kommer os.unlink()-anropet vid avslutning av kontexthanteraren att misslyckas med PermissionError. Detta kan inte hända när delete_on_close är true eftersom delete-åtkomst begärs av open, som misslyckas omedelbart om den begärda åtkomsten inte beviljas.

På POSIX (endast) kan en process som avslutas abrupt med SIGKILL inte automatiskt ta bort NamedTemporaryFiles som den har skapat.

Utlöser en auditing event tempfile.mkstemp med argumentet fullpath.

Ändrad i version 3.8: Lagt till parametern errors.

Ändrad i version 3.12: Lagt till parametern delete_on_close.

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

Den här klassen fungerar precis som TemporaryFile(), förutom att data spolas i minnet tills filstorleken överstiger max_size, eller tills filens fileno()-metod anropas, varvid innehållet skrivs till disken och operationen fortsätter som med TemporaryFile().

rollover()

Den resulterande filen har ytterligare en metod, rollover(), som gör att filen rullas över till en fil på disken oavsett dess storlek.

Det returnerade objektet är ett filliknande objekt vars attribut _file är antingen ett io.BytesIO- eller io.TextIOWrapper-objekt (beroende på om binärt eller text mode specificerades) eller ett äkta filobjekt, beroende på om rollover() har anropats. Detta filliknande objekt kan användas i en with-sats, precis som en vanlig fil.

Ändrad i version 3.3: trunkeringsmetoden accepterar nu ett size-argument.

Ändrad i version 3.8: Lagt till parametern errors.

Ändrad i version 3.11: Implementerar fullständigt de abstrakta basklasserna io.BufferedIOBase och io.TextIOBase (beroende på om binärt eller text mode angavs).

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

Denna klass skapar en temporär katalog på ett säkert sätt med samma regler som mkdtemp(). Det resulterande objektet kan användas som en kontexthanterare (se Exempel). När kontexten är klar eller när objektet för den temporära katalogen förstörs, tas den nyskapade temporära katalogen och allt dess innehåll bort från filsystemet.

name

Katalognamnet kan hämtas från attributet name i det returnerade objektet. När det returnerade objektet används som en context manager, kommer name att tilldelas målet för as klausulen i with uttalandet, om det finns ett sådant.

cleanup()

Katalogen kan uttryckligen rensas upp genom att anropa metoden cleanup(). Om ignore_cleanup_errors är true, kommer alla ohanterade undantag under explicit eller implicit rensning (t.ex. ett PermissionError som tar bort öppna filer i Windows) att ignoreras, och de återstående flyttbara objekten kommer att raderas på ”bästa möjliga” sätt. I annat fall kommer fel att uppstå i det sammanhang där rensningen sker (anropet cleanup(), när kontexthanteraren avslutas, när objektet samlas in eller när tolken stängs av).

Parametern delete kan användas för att inaktivera rensning av katalogträdet när kontexten avslutas. Även om det kan verka ovanligt att en kontexthanterare inaktiverar den åtgärd som vidtas när kontexten avslutas, kan det vara användbart vid felsökning eller när du vill att rensningsbeteendet ska vara villkorligt baserat på annan logik.

Utlöser en auditing event tempfile.mkdtemp med argumentet fullpath.

Tillagd i version 3.2.

Ändrad i version 3.10: Lagt till parametern ignore_cleanup_errors.

Ändrad i version 3.12: Lagt till parametern delete.

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

Skapar en temporär fil på det säkraste sättet som är möjligt. Det finns inga tävlingsförhållanden i skapandet av filen, förutsatt att plattformen korrekt implementerar flaggan os.O_EXCL för os.open(). Filen är läsbar och skrivbar endast av det skapande användar-ID:t. Om plattformen använder behörighetsbitar för att ange om en fil är körbar, är filen inte körbar av någon. Filens deskriptor ärvs inte av underordnade processer.

Till skillnad från TemporaryFile() är användaren av mkstemp() ansvarig för att radera den temporära filen när den är klar.

Om suffix inte är None, kommer filnamnet att sluta med det suffixet, annars kommer det inte att finnas något suffix. mkstemp() sätter inte en punkt mellan filnamnet och suffixet; om du behöver en, sätt den i början av suffix.

Om prefix inte är None kommer filnamnet att börja med det prefixet, annars används ett standardprefix. Standardvärdet är returvärdet för gettempprefix() eller gettempprefixb(), beroende på vad som är lämpligt.

Om dir inte är None kommer filen att skapas i den katalogen, annars används en standardkatalog. Standardkatalogen väljs från en plattformsberoende lista, men användaren av programmet kan styra katalogplatsen genom att ange miljövariablerna TMPDIR, TEMP eller TMP. Det finns därför ingen garanti för att det genererade filnamnet kommer att ha några bra egenskaper, som t.ex. att inte kräva citattecken när det skickas till externa kommandon via os.popen().

Om något av suffix, prefix och dir inte är None måste de vara av samma typ. Om de är bytes kommer det returnerade namnet att vara bytes istället för str. Om du vill tvinga fram ett bytes-returvärde med annat standardbeteende, skicka uffix=b''.

Om text anges och true, öppnas filen i textläge. I annat fall (standard) öppnas filen i binärt läge.

mkstemp() returnerar en tupel som innehåller ett OS-nivåhandtag till en öppen fil (som skulle returneras av os.open()) och det absoluta sökvägsnamnet för den filen, i den ordningen.

Utlöser en auditing event tempfile.mkstemp med argumentet fullpath.

Ändrad i version 3.5: suffix, prefix och dir kan nu anges i bytes för att få ett bytes-returvärde. Tidigare var endast str tillåtet. suffix och prefix accepterar nu och är standard för None för att ett lämpligt standardvärde ska användas.

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

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

Skapar en tillfällig katalog på säkrast möjliga sätt. Det finns inga tävlingsvillkor i skapandet av katalogen. Katalogen är läsbar, skrivbar och sökbar endast av det skapande användar-ID:t.

Användaren av mkdtemp() är ansvarig för att radera den temporära katalogen och dess innehåll när den är klar.

Argumenten prefix, suffix och dir är desamma som för mkstemp().

mkdtemp() returnerar det absoluta sökvägsnamnet för den nya katalogen.

Utlöser en auditing event tempfile.mkdtemp med argumentet fullpath.

Ändrad i version 3.5: suffix, prefix och dir kan nu anges i bytes för att få ett bytes-returvärde. Tidigare var endast str tillåtet. suffix och prefix accepterar nu och är standard för None för att ett lämpligt standardvärde ska användas.

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

Ändrad i version 3.12: mkdtemp() returnerar nu alltid en absolut sökväg, även om dir är relativ.

tempfile.gettempdir()

Returnerar namnet på den katalog som används för temporära filer. Detta definierar standardvärdet för argumentet dir för alla funktioner i denna modul.

Python söker igenom en standardlista med kataloger för att hitta en katalog som den anropande användaren kan skapa filer i. Listan är följande:

  1. Den katalog som anges av miljövariabeln TMPDIR.

  2. Den katalog som anges av miljövariabeln TEMP.

  3. Den katalog som anges av miljövariabeln TMP.

  4. En plattformsspecifik plats:

    • I Windows, katalogerna C:\TEMP, C:\TMP, \TEMP och \TMP, i den ordningen.

    • På alla andra plattformar, katalogerna /tmp, /var/tmp och /usr/tmp, i nämnd ordning.

  5. Som en sista utväg, den aktuella arbetskatalogen.

Resultatet av denna sökning cachelagras, se beskrivningen av tempdir nedan.

Ändrad i version 3.10: Returnerar alltid en str. Tidigare returnerade den alla tempdir-värden oavsett typ så länge det inte var None.

tempfile.gettempdirb()

Samma som gettempdir() men returvärdet är i bytes.

Tillagd i version 3.5.

tempfile.gettempprefix()

Returnerar det filnamnsprefix som används för att skapa temporära filer. Detta innehåller inte katalogkomponenten.

tempfile.gettempprefixb()

Samma som gettempprefix() men returvärdet är i bytes.

Tillagd i version 3.5.

Modulen använder en global variabel för att lagra namnet på den katalog som används för temporära filer som returneras av gettempdir(). Den kan ställas in direkt för att åsidosätta urvalsprocessen, men detta avråds. Alla funktioner i den här modulen tar ett dir-argument som kan användas för att ange katalogen. Detta är det rekommenderade tillvägagångssättet som inte överraskar annan intet ont anande kod genom att ändra det globala API-beteendet.

tempfile.tempdir

När den här variabeln anges till ett annat värde än None definierar den standardvärdet för dir-argumentet till de funktioner som definieras i den här modulen, inklusive dess typ, bytes eller str. Det kan inte vara ett path-like object.

Om tempdir är None (standard) vid något anrop till någon av ovanstående funktioner utom gettempprefix() initialiseras den enligt algoritmen som beskrivs i gettempdir().

Anteckning

Tänk på att om du sätter tempdir till ett bytes-värde, så finns det en otäck bieffekt: Den globala standardreturtypen för mkstemp() och mkdtemp() ändras till bytes när inga explicita prefix, suffix eller dir-argument av typen str anges. Skriv inte kod som förväntar sig eller är beroende av detta. Detta besvärliga beteende bibehålls för kompatibilitet med den historiska implementationen.

Exempel

Här följer några exempel på typisk användning av modulen 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

Föråldrade funktioner och variabler

Ett historiskt sätt att skapa temporära filer var att först generera ett filnamn med funktionen mktemp() och sedan skapa en fil med detta namn. Tyvärr är detta inte säkert, eftersom en annan process kan skapa en fil med detta namn under tiden mellan anropet till mktemp() och det efterföljande försöket att skapa filen av den första processen. Lösningen är att kombinera de två stegen och skapa filen omedelbart. Detta tillvägagångssätt används av mkstemp() och de andra funktionerna som beskrivs ovan.

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

Föråldrad sedan version 2.3: Använd mkstemp() istället.

Returnerar ett absolut sökvägsnamn för en fil som inte fanns när anropet gjordes. Argumenten prefix, suffix och dir liknar argumenten i mkstemp(), förutom att filnamn för byte, suffix=None och prefix=None inte stöds.

Varning

Om du använder den här funktionen kan du få ett säkerhetshål i ditt program. När du väl hinner göra något med filnamnet som returneras, kan någon annan ha hunnit före dig. mktemp() kan enkelt ersättas med NamedTemporaryFile(), med parametern delete=False:

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