1:mod:`tempfile` --- Generate temporary files and directories 2============================================================ 3 4.. module:: tempfile 5 :synopsis: Generate temporary files and directories. 6 7.. sectionauthor:: Zack Weinberg <zack@codesourcery.com> 8 9**Source code:** :source:`Lib/tempfile.py` 10 11.. index:: 12 pair: temporary; file name 13 pair: temporary; file 14 15-------------- 16 17This module creates temporary files and directories. It works on all 18supported platforms. :class:`TemporaryFile`, :class:`NamedTemporaryFile`, 19:class:`TemporaryDirectory`, and :class:`SpooledTemporaryFile` are high-level 20interfaces which provide automatic cleanup and can be used as 21context managers. :func:`mkstemp` and 22:func:`mkdtemp` are lower-level functions which require manual cleanup. 23 24All the user-callable functions and constructors take additional arguments which 25allow direct control over the location and name of temporary files and 26directories. Files names used by this module include a string of 27random characters which allows those files to be securely created in 28shared temporary directories. 29To maintain backward compatibility, the argument order is somewhat odd; it 30is recommended to use keyword arguments for clarity. 31 32The module defines the following user-callable items: 33 34.. function:: TemporaryFile(mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None) 35 36 Return a :term:`file-like object` that can be used as a temporary storage area. 37 The file is created securely, using the same rules as :func:`mkstemp`. It will be destroyed as soon 38 as it is closed (including an implicit close when the object is garbage 39 collected). Under Unix, the directory entry for the file is either not created at all or is removed 40 immediately after the file is created. Other platforms do not support 41 this; your code should not rely on a temporary file created using this 42 function having or not having a visible name in the file system. 43 44 The resulting object can be used as a context manager (see 45 :ref:`tempfile-examples`). On completion of the context or 46 destruction of the file object the temporary file will be removed 47 from the filesystem. 48 49 The *mode* parameter defaults to ``'w+b'`` so that the file created can 50 be read and written without being closed. Binary mode is used so that it 51 behaves consistently on all platforms without regard for the data that is 52 stored. *buffering*, *encoding*, *errors* and *newline* are interpreted as for 53 :func:`open`. 54 55 The *dir*, *prefix* and *suffix* parameters have the same meaning and 56 defaults as with :func:`mkstemp`. 57 58 The returned object is a true file object on POSIX platforms. On other 59 platforms, it is a file-like object whose :attr:`!file` attribute is the 60 underlying true file object. 61 62 The :py:data:`os.O_TMPFILE` flag is used if it is available and works 63 (Linux-specific, requires Linux kernel 3.11 or later). 64 65 On platforms that are neither Posix nor Cygwin, TemporaryFile is an alias 66 for NamedTemporaryFile. 67 68 .. audit-event:: tempfile.mkstemp fullpath tempfile.TemporaryFile 69 70 .. versionchanged:: 3.5 71 72 The :py:data:`os.O_TMPFILE` flag is now used if available. 73 74 .. versionchanged:: 3.8 75 Added *errors* parameter. 76 77 78.. function:: NamedTemporaryFile(mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, delete=True, *, errors=None) 79 80 This function operates exactly as :func:`TemporaryFile` does, except that 81 the file is guaranteed to have a visible name in the file system (on 82 Unix, the directory entry is not unlinked). That name can be retrieved 83 from the :attr:`name` attribute of the returned 84 file-like object. Whether the name can be 85 used to open the file a second time, while the named temporary file is 86 still open, varies across platforms (it can be so used on Unix; it cannot 87 on Windows NT or later). If *delete* is true (the default), the file is 88 deleted as soon as it is closed. 89 The returned object is always a file-like object whose :attr:`!file` 90 attribute is the underlying true file object. This file-like object can 91 be used in a :keyword:`with` statement, just like a normal file. 92 93 .. audit-event:: tempfile.mkstemp fullpath tempfile.NamedTemporaryFile 94 95 .. versionchanged:: 3.8 96 Added *errors* parameter. 97 98 99.. function:: SpooledTemporaryFile(max_size=0, mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None) 100 101 This function operates exactly as :func:`TemporaryFile` does, except that 102 data is spooled in memory until the file size exceeds *max_size*, or 103 until the file's :func:`fileno` method is called, at which point the 104 contents are written to disk and operation proceeds as with 105 :func:`TemporaryFile`. 106 107 The resulting file has one additional method, :func:`rollover`, which 108 causes the file to roll over to an on-disk file regardless of its size. 109 110 The returned object is a file-like object whose :attr:`_file` attribute 111 is either an :class:`io.BytesIO` or :class:`io.TextIOWrapper` object 112 (depending on whether binary or text *mode* was specified) or a true file 113 object, depending on whether :func:`rollover` has been called. This 114 file-like object can be used in a :keyword:`with` statement, just like 115 a normal file. 116 117 .. versionchanged:: 3.3 118 the truncate method now accepts a ``size`` argument. 119 120 .. versionchanged:: 3.8 121 Added *errors* parameter. 122 123 124.. function:: TemporaryDirectory(suffix=None, prefix=None, dir=None, ignore_cleanup_errors=False) 125 126 This function securely creates a temporary directory using the same rules as :func:`mkdtemp`. 127 The resulting object can be used as a context manager (see 128 :ref:`tempfile-examples`). On completion of the context or destruction 129 of the temporary directory object, the newly created temporary directory 130 and all its contents are removed from the filesystem. 131 132 The directory name can be retrieved from the :attr:`name` attribute of the 133 returned object. When the returned object is used as a context manager, the 134 :attr:`name` will be assigned to the target of the :keyword:`!as` clause in 135 the :keyword:`with` statement, if there is one. 136 137 The directory can be explicitly cleaned up by calling the 138 :func:`cleanup` method. If *ignore_cleanup_errors* is true, any unhandled 139 exceptions during explicit or implicit cleanup (such as a 140 :exc:`PermissionError` removing open files on Windows) will be ignored, 141 and the remaining removable items deleted on a "best-effort" basis. 142 Otherwise, errors will be raised in whatever context cleanup occurs 143 (the :func:`cleanup` call, exiting the context manager, when the object 144 is garbage-collected or during interpreter shutdown). 145 146 .. audit-event:: tempfile.mkdtemp fullpath tempfile.TemporaryDirectory 147 148 .. versionadded:: 3.2 149 150 .. versionchanged:: 3.10 151 Added *ignore_cleanup_errors* parameter. 152 153 154.. function:: mkstemp(suffix=None, prefix=None, dir=None, text=False) 155 156 Creates a temporary file in the most secure manner possible. There are 157 no race conditions in the file's creation, assuming that the platform 158 properly implements the :const:`os.O_EXCL` flag for :func:`os.open`. The 159 file is readable and writable only by the creating user ID. If the 160 platform uses permission bits to indicate whether a file is executable, 161 the file is executable by no one. The file descriptor is not inherited 162 by child processes. 163 164 Unlike :func:`TemporaryFile`, the user of :func:`mkstemp` is responsible 165 for deleting the temporary file when done with it. 166 167 If *suffix* is not ``None``, the file name will end with that suffix, 168 otherwise there will be no suffix. :func:`mkstemp` does not put a dot 169 between the file name and the suffix; if you need one, put it at the 170 beginning of *suffix*. 171 172 If *prefix* is not ``None``, the file name will begin with that prefix; 173 otherwise, a default prefix is used. The default is the return value of 174 :func:`gettempprefix` or :func:`gettempprefixb`, as appropriate. 175 176 If *dir* is not ``None``, the file will be created in that directory; 177 otherwise, a default directory is used. The default directory is chosen 178 from a platform-dependent list, but the user of the application can 179 control the directory location by setting the *TMPDIR*, *TEMP* or *TMP* 180 environment variables. There is thus no guarantee that the generated 181 filename will have any nice properties, such as not requiring quoting 182 when passed to external commands via ``os.popen()``. 183 184 If any of *suffix*, *prefix*, and *dir* are not 185 ``None``, they must be the same type. 186 If they are bytes, the returned name will be bytes instead of str. 187 If you want to force a bytes return value with otherwise default behavior, 188 pass ``suffix=b''``. 189 190 If *text* is specified and true, the file is opened in text mode. 191 Otherwise, (the default) the file is opened in binary mode. 192 193 :func:`mkstemp` returns a tuple containing an OS-level handle to an open 194 file (as would be returned by :func:`os.open`) and the absolute pathname 195 of that file, in that order. 196 197 .. audit-event:: tempfile.mkstemp fullpath tempfile.mkstemp 198 199 .. versionchanged:: 3.5 200 *suffix*, *prefix*, and *dir* may now be supplied in bytes in order to 201 obtain a bytes return value. Prior to this, only str was allowed. 202 *suffix* and *prefix* now accept and default to ``None`` to cause 203 an appropriate default value to be used. 204 205 .. versionchanged:: 3.6 206 The *dir* parameter now accepts a :term:`path-like object`. 207 208 209.. function:: mkdtemp(suffix=None, prefix=None, dir=None) 210 211 Creates a temporary directory in the most secure manner possible. There 212 are no race conditions in the directory's creation. The directory is 213 readable, writable, and searchable only by the creating user ID. 214 215 The user of :func:`mkdtemp` is responsible for deleting the temporary 216 directory and its contents when done with it. 217 218 The *prefix*, *suffix*, and *dir* arguments are the same as for 219 :func:`mkstemp`. 220 221 :func:`mkdtemp` returns the absolute pathname of the new directory. 222 223 .. audit-event:: tempfile.mkdtemp fullpath tempfile.mkdtemp 224 225 .. versionchanged:: 3.5 226 *suffix*, *prefix*, and *dir* may now be supplied in bytes in order to 227 obtain a bytes return value. Prior to this, only str was allowed. 228 *suffix* and *prefix* now accept and default to ``None`` to cause 229 an appropriate default value to be used. 230 231 .. versionchanged:: 3.6 232 The *dir* parameter now accepts a :term:`path-like object`. 233 234 235.. function:: gettempdir() 236 237 Return the name of the directory used for temporary files. This 238 defines the default value for the *dir* argument to all functions 239 in this module. 240 241 Python searches a standard list of directories to find one which 242 the calling user can create files in. The list is: 243 244 #. The directory named by the :envvar:`TMPDIR` environment variable. 245 246 #. The directory named by the :envvar:`TEMP` environment variable. 247 248 #. The directory named by the :envvar:`TMP` environment variable. 249 250 #. A platform-specific location: 251 252 * On Windows, the directories :file:`C:\\TEMP`, :file:`C:\\TMP`, 253 :file:`\\TEMP`, and :file:`\\TMP`, in that order. 254 255 * On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and 256 :file:`/usr/tmp`, in that order. 257 258 #. As a last resort, the current working directory. 259 260 The result of this search is cached, see the description of 261 :data:`tempdir` below. 262 263 .. versionchanged:: 3.10 264 265 Always returns a str. Previously it would return any :data:`tempdir` 266 value regardless of type so long as it was not ``None``. 267 268.. function:: gettempdirb() 269 270 Same as :func:`gettempdir` but the return value is in bytes. 271 272 .. versionadded:: 3.5 273 274.. function:: gettempprefix() 275 276 Return the filename prefix used to create temporary files. This does not 277 contain the directory component. 278 279.. function:: gettempprefixb() 280 281 Same as :func:`gettempprefix` but the return value is in bytes. 282 283 .. versionadded:: 3.5 284 285The module uses a global variable to store the name of the directory 286used for temporary files returned by :func:`gettempdir`. It can be 287set directly to override the selection process, but this is discouraged. 288All functions in this module take a *dir* argument which can be used 289to specify the directory. This is the recommended approach that does 290not surprise other unsuspecting code by changing global API behavior. 291 292.. data:: tempdir 293 294 When set to a value other than ``None``, this variable defines the 295 default value for the *dir* argument to the functions defined in this 296 module, including its type, bytes or str. It cannot be a 297 :term:`path-like object`. 298 299 If ``tempdir`` is ``None`` (the default) at any call to any of the above 300 functions except :func:`gettempprefix` it is initialized following the 301 algorithm described in :func:`gettempdir`. 302 303 .. note:: 304 305 Beware that if you set ``tempdir`` to a bytes value, there is a 306 nasty side effect: The global default return type of 307 :func:`mkstemp` and :func:`mkdtemp` changes to bytes when no 308 explicit ``prefix``, ``suffix``, or ``dir`` arguments of type 309 str are supplied. Please do not write code expecting or 310 depending on this. This awkward behavior is maintained for 311 compatibility with the historical implementation. 312 313.. _tempfile-examples: 314 315Examples 316-------- 317 318Here are some examples of typical usage of the :mod:`tempfile` module:: 319 320 >>> import tempfile 321 322 # create a temporary file and write some data to it 323 >>> fp = tempfile.TemporaryFile() 324 >>> fp.write(b'Hello world!') 325 # read data from file 326 >>> fp.seek(0) 327 >>> fp.read() 328 b'Hello world!' 329 # close the file, it will be removed 330 >>> fp.close() 331 332 # create a temporary file using a context manager 333 >>> with tempfile.TemporaryFile() as fp: 334 ... fp.write(b'Hello world!') 335 ... fp.seek(0) 336 ... fp.read() 337 b'Hello world!' 338 >>> 339 # file is now closed and removed 340 341 # create a temporary directory using the context manager 342 >>> with tempfile.TemporaryDirectory() as tmpdirname: 343 ... print('created temporary directory', tmpdirname) 344 >>> 345 # directory and contents have been removed 346 347.. _tempfile-mktemp-deprecated: 348 349Deprecated functions and variables 350---------------------------------- 351 352A historical way to create temporary files was to first generate a 353file name with the :func:`mktemp` function and then create a file 354using this name. Unfortunately this is not secure, because a different 355process may create a file with this name in the time between the call 356to :func:`mktemp` and the subsequent attempt to create the file by the 357first process. The solution is to combine the two steps and create the 358file immediately. This approach is used by :func:`mkstemp` and the 359other functions described above. 360 361.. function:: mktemp(suffix='', prefix='tmp', dir=None) 362 363 .. deprecated:: 2.3 364 Use :func:`mkstemp` instead. 365 366 Return an absolute pathname of a file that did not exist at the time the 367 call is made. The *prefix*, *suffix*, and *dir* arguments are similar 368 to those of :func:`mkstemp`, except that bytes file names, ``suffix=None`` 369 and ``prefix=None`` are not supported. 370 371 .. warning:: 372 373 Use of this function may introduce a security hole in your program. By 374 the time you get around to doing anything with the file name it returns, 375 someone else may have beaten you to the punch. :func:`mktemp` usage can 376 be replaced easily with :func:`NamedTemporaryFile`, passing it the 377 ``delete=False`` parameter:: 378 379 >>> f = NamedTemporaryFile(delete=False) 380 >>> f.name 381 '/tmp/tmptjujjt' 382 >>> f.write(b"Hello World!\n") 383 13 384 >>> f.close() 385 >>> os.unlink(f.name) 386 >>> os.path.exists(f.name) 387 False 388