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