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 a context 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).

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)

This function operates exactly asTemporaryFile() does, except thatthe file is guaranteed to have a visible name in the file system (onUnix, the directory entry is not unlinked). That name can be retrievedfrom thename attribute of the returnedfile-like object. Whether the name can beused to open the file a second time, while the named temporary file isstill open, varies across platforms (it can be so used on Unix; it cannoton Windows NT or later). Ifdelete is true (the default), the file isdeleted as soon as it is closed.The returned object is always a file-like object whosefileattribute is the underlying true file object. This file-like object canbe used in awith statement, just like a normal file.

Raises anauditing eventtempfile.mkstemp with argumentfullpath.

Changed in version 3.8:Addederrors parameter.

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

This function 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().

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.

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

This function securely creates a temporary directory using the same rules asmkdtemp().The resulting object can be used as a context 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.

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

The directory can be explicitly cleaned up by calling thecleanup() method.

Raises anauditing eventtempfile.mkdtemp with argumentfullpath.

New in version 3.2.

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.

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.

tempfile.gettempdirb()

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

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

New 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 and this is the recommended approach.

tempfile.tempdir

When set to a value other thanNone, this variable defines thedefault value for thedir argument to the functions defined in thismodule.

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

Examples

Here are some examples of typical usage of thetempfile module:

>>>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 directory using the context manager>>>withtempfile.TemporaryDirectory()astmpdirname:...print('created temporary directory',tmpdirname)>>># directory and contents have been removed

Deprecated functions and variables

A historical way to create temporary files was to first generate afile name with themktemp() function and then create a fileusing this name. Unfortunately this is not secure, because a differentprocess may create a file with this name in the time between the calltomktemp() and the subsequent attempt to create the file by thefirst process. The solution is to combine the two steps and create thefile immediately. This approach is used bymkstemp() and theother functions described above.

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

Deprecated since version 2.3:Usemkstemp() instead.

Return an absolute pathname of a file that did not exist at the time thecall is made. Theprefix,suffix, anddir arguments are similarto those ofmkstemp(), except that bytes file names,suffix=Noneandprefix=None are not supported.

Warning

Use of this function may introduce a security hole in your program. Bythe time you get around to doing anything with the file name it returns,someone else may have beaten you to the punch.mktemp() usage canbe replaced easily withNamedTemporaryFile(), passing it thedelete=False parameter:

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