tempfile — Generate temporary files and directories¶

Source code:Lib/tempfile.py

This module creates temporary files and directories. It works on allsupported platforms.TemporaryFile,NamedTemporaryFile,TemporaryDirectory, andSpooledTemporaryFile are high-levelinterfaces which provide automatic cleanup and can be used ascontext managers.mkstemp() andmkdtemp() are lower-level functions which require manual cleanup.

All the user-callable functions and constructors take additional arguments whichallow direct control over the location and name of temporary files anddirectories. Files names used by this module include a string ofrandom characters which allows those files to be securely created inshared temporary directories.To maintain backward compatibility, the argument order is somewhat odd; itis recommended to use keyword arguments for clarity.

The module defines the following user-callable items:

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

Return afile-like object that can be used as a temporary storage area.The file is created securely, using the same rules asmkstemp(). It will be destroyed as soonas it is closed (including an implicit close when the object is garbagecollected). Under Unix, the directory entry for the file is either not created at all or is removedimmediately after the file is created. Other platforms do not supportthis; your code should not rely on a temporary file created using thisfunction having or not having a visible name in the file system.

The resulting object can be used as acontext manager (seeExamples). On completion of the context ordestruction of the file object the temporary file will be removedfrom the filesystem.

Themode parameter defaults to'w+b' so that the file created canbe read and written without being closed. Binary mode is used so that itbehaves consistently on all platforms without regard for the data that isstored.buffering,encoding,errors andnewline are interpreted as foropen().

Thedir,prefix andsuffix parameters have the same meaning anddefaults as withmkstemp().

The returned object is a true file object on POSIX platforms. On otherplatforms, it is a file-like object whosefile attribute is theunderlying true file object.

Theos.O_TMPFILE flag is used if it is available and works(Linux-specific, requires Linux kernel 3.11 or later).

On platforms that are neither Posix nor Cygwin, TemporaryFile is an aliasfor NamedTemporaryFile.

Raises anauditing eventtempfile.mkstemp with argumentfullpath.

Changed in version 3.5:Theos.O_TMPFILE flag is now used if available.

Changed in version 3.8:Addederrors parameter.

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

This function operates exactly asTemporaryFile() does, except thefollowing differences:

• This function returns a file that is guaranteed to have a visible name inthe file system.

• To manage the named file, it extends the parameters ofTemporaryFile() withdelete anddelete_on_close parameters thatdetermine whether and how the named file should be automatically deleted.

The returned object is always afile-like object whosefileattribute is the underlying true file object. This file-like objectcan be used in awith statement, just like a normal file. Thename of the temporary file can be retrieved from thename attributeof the returned file-like object. On Unix, unlike with theTemporaryFile(), the directory entry does not get unlinked immediatelyafter the file creation.

Ifdelete is true (the default) anddelete_on_close is true (thedefault), the file is deleted as soon as it is closed. Ifdelete is trueanddelete_on_close is false, the file is deleted on context manager exitonly, or else when thefile-like object is finalized. Deletion is notalways guaranteed in this case (seeobject.__del__()). Ifdelete isfalse, the value ofdelete_on_close is ignored.

Therefore to use the name of the temporary file to reopen the file afterclosing it, either make sure not to delete the file upon closure (set thedelete parameter to be false) or, in case the temporary file is created inawith statement, set thedelete_on_close parameter to be false.The latter approach is recommended as it provides assistance in automaticcleaning of the temporary file upon the context manager exit.

Opening the temporary file again by its name while it is still open works asfollows:

• On POSIX the file can always be opened again.

• On Windows, make sure that at least one of the following conditions arefulfilled:

  • delete is false

  • additional open shares delete access (e.g. by callingos.open()with the flagO_TEMPORARY)

  • delete is true butdelete_on_close is false. Note, that in thiscase the additional opens that do not share delete access (e.g.created via builtinopen()) must be closed before exiting thecontext manager, else theos.unlink() call on context managerexit will fail with aPermissionError.

On Windows, ifdelete_on_close is false, and the file is created in adirectory for which the user lacks delete access, then theos.unlink()call on exit of the context manager will fail with aPermissionError.This cannot happen whendelete_on_close is true because delete access isrequested by the open, which fails immediately if the requested access is notgranted.

On POSIX (only), a process that is terminated abruptly with SIGKILLcannot automatically delete any NamedTemporaryFiles it created.

Raises anauditing eventtempfile.mkstemp with argumentfullpath.

Changed in version 3.8:Addederrors parameter.

Changed in version 3.12:Addeddelete_on_close parameter.

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

This class operates exactly asTemporaryFile() does, except thatdata is spooled in memory until the file size exceedsmax_size, oruntil the file’sfileno() method is called, at which point thecontents are written to disk and operation proceeds as withTemporaryFile().

rollover()¶

The resulting file has one additional method,rollover(), whichcauses the file to roll over to an on-disk file regardless of its size.

The returned object is a file-like object whose_file attributeis either anio.BytesIO orio.TextIOWrapper object(depending on whether binary or textmode was specified) or a true fileobject, depending on whetherrollover() has been called. Thisfile-like object can be used in awith statement, just likea normal file.

Changed in version 3.3:the truncate method now accepts asize argument.

Changed in version 3.8:Addederrors parameter.

Changed in version 3.11:Fully implements theio.BufferedIOBase andio.TextIOBase abstract base classes (depending on whether binaryor textmode was specified).

classtempfile.TemporaryDirectory(suffix=None,prefix=None,dir=None,ignore_cleanup_errors=False,*,delete=True)¶

This class securely creates a temporary directory using the same rules asmkdtemp().The resulting object can be used as acontext manager (seeExamples). On completion of the context or destructionof the temporary directory object, the newly created temporary directoryand all its contents are removed from the filesystem.

name¶

The directory name can be retrieved from thename attribute of thereturned object. When the returned object is used as acontext manager, thename will be assigned to the target of theas clause inthewith statement, if there is one.

cleanup()¶

The directory can be explicitly cleaned up by calling thecleanup() method. Ifignore_cleanup_errors is true, any unhandledexceptions during explicit or implicit cleanup (such as aPermissionError removing open files on Windows) will be ignored,and the remaining removable items deleted on a “best-effort” basis.Otherwise, errors will be raised in whatever context cleanup occurs(thecleanup() call, exiting the context manager, when the objectis garbage-collected or during interpreter shutdown).

Thedelete parameter can be used to disable cleanup of the directory treeupon exiting the context. While it may seem unusual for a context managerto disable the action taken when exiting the context, it can be useful duringdebugging or when you need your cleanup behavior to be conditional based onother logic.

Raises anauditing eventtempfile.mkdtemp with argumentfullpath.

Added in version 3.2.

Changed in version 3.10:Addedignore_cleanup_errors parameter.

Changed in version 3.12:Added thedelete parameter.

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

Creates a temporary file in the most secure manner possible. There areno race conditions in the file’s creation, assuming that the platformproperly implements theos.O_EXCL flag foros.open(). Thefile is readable and writable only by the creating user ID. If theplatform uses permission bits to indicate whether a file is executable,the file is executable by no one. The file descriptor is not inheritedby child processes.

UnlikeTemporaryFile(), the user ofmkstemp() is responsiblefor deleting the temporary file when done with it.

Ifsuffix is notNone, the file name will end with that suffix,otherwise there will be no suffix.mkstemp() does not put a dotbetween the file name and the suffix; if you need one, put it at thebeginning ofsuffix.

Ifprefix is notNone, the file name will begin with that prefix;otherwise, a default prefix is used. The default is the return value ofgettempprefix() orgettempprefixb(), as appropriate.

Ifdir is notNone, the file will be created in that directory;otherwise, a default directory is used. The default directory is chosenfrom a platform-dependent list, but the user of the application cancontrol the directory location by setting theTMPDIR,TEMP orTMPenvironment variables. There is thus no guarantee that the generatedfilename will have any nice properties, such as not requiring quotingwhen passed to external commands viaos.popen().

If any ofsuffix,prefix, anddir are notNone, they must be the same type.If they are bytes, the returned name will be bytes instead of str.If you want to force a bytes return value with otherwise default behavior,passsuffix=b''.

Iftext is specified and true, the file is opened in text mode.Otherwise, (the default) the file is opened in binary mode.

mkstemp() returns a tuple containing an OS-level handle to an openfile (as would be returned byos.open()) and the absolute pathnameof that file, in that order.

Raises anauditing eventtempfile.mkstemp with argumentfullpath.

Changed in version 3.5:suffix,prefix, anddir may now be supplied in bytes in order toobtain a bytes return value. Prior to this, only str was allowed.suffix andprefix now accept and default toNone to causean appropriate default value to be used.

Changed in version 3.6:Thedir parameter now accepts apath-like object.

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

Creates a temporary directory in the most secure manner possible. Thereare no race conditions in the directory’s creation. The directory isreadable, writable, and searchable only by the creating user ID.

The user ofmkdtemp() is responsible for deleting the temporarydirectory and its contents when done with it.

Theprefix,suffix, anddir arguments are the same as formkstemp().

mkdtemp() returns the absolute pathname of the new directory.

Raises anauditing eventtempfile.mkdtemp with argumentfullpath.

Changed in version 3.5:suffix,prefix, anddir may now be supplied in bytes in order toobtain a bytes return value. Prior to this, only str was allowed.suffix andprefix now accept and default toNone to causean appropriate default value to be used.

Changed in version 3.6:Thedir parameter now accepts apath-like object.

Changed in version 3.12:mkdtemp() now always returns an absolute path, even ifdir is relative.

tempfile.gettempdir()¶

Return the name of the directory used for temporary files. Thisdefines the default value for thedir argument to all functionsin this module.

Python searches a standard list of directories to find one whichthe calling user can create files in. The list is:

1. The directory named by theTMPDIR environment variable.

2. The directory named by theTEMP environment variable.

3. The directory named by theTMP environment variable.

4. A platform-specific location:

   • On Windows, the directoriesC:\TEMP,C:\TMP,\TEMP, and\TMP, in that order.

   • On all other platforms, the directories/tmp,/var/tmp, and/usr/tmp, in that order.

5. As a last resort, the current working directory.

The result of this search is cached, see the description oftempdir below.

Changed in version 3.10:Always returns a str. Previously it would return anytempdirvalue regardless of type so long as it was notNone.

tempfile.gettempdirb()¶

Same asgettempdir() but the return value is in bytes.

Added in version 3.5.

tempfile.gettempprefix()¶

Return the filename prefix used to create temporary files. This does notcontain the directory component.

tempfile.gettempprefixb()¶

Same asgettempprefix() but the return value is in bytes.

Added in version 3.5.

The module uses a global variable to store the name of the directoryused for temporary files returned bygettempdir(). It can beset directly to override the selection process, but this is discouraged.All functions in this module take adir argument which can be usedto specify the directory. This is the recommended approach that doesnot surprise other unsuspecting code by changing global API behavior.

tempfile.tempdir¶

When set to a value other thanNone, this variable defines thedefault value for thedir argument to the functions defined in thismodule, including its type, bytes or str. It cannot be apath-like object.

Iftempdir isNone (the default) at any call to any of the abovefunctions exceptgettempprefix() it is initialized following thealgorithm described ingettempdir().

Note

Beware that if you settempdir to a bytes value, there is anasty side effect: The global default return type ofmkstemp() andmkdtemp() changes to bytes when noexplicitprefix,suffix, ordir arguments of typestr are supplied. Please do not write code expecting ordepending on this. This awkward behavior is maintained forcompatibility with the historical implementation.

>>>importtempfile# 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>>>withtempfile.TemporaryFile()asfp:...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>>>withtempfile.NamedTemporaryFile(delete_on_close=False)asfp:...fp.write(b'Hello world!')...fp.close()...# the file is closed, but not removed...# open the file again by using its name...withopen(fp.name,mode='rb')asf:...f.read()b'Hello world!'>>># file is now removed# create a temporary directory using the context manager>>>withtempfile.TemporaryDirectory()astmpdirname:...print('created temporary directory',tmpdirname)>>># directory and contents have been removed