Debian Codegraph @

Doc/library/tempfile.rst

raw
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 <[email protected]>
8
9 **Source code:** :source:`Lib/tempfile.py`
10
11 .. index::
12 pair: temporary; file name
13 pair: temporary; file
14
15 --------------
16
17 This module creates temporary files and directories. It works on all
18 supported platforms. :class:`TemporaryFile`, :class:`NamedTemporaryFile`,
19 :class:`TemporaryDirectory`, and :class:`SpooledTemporaryFile` are high-level
20 interfaces which provide automatic cleanup and can be used as
21 :term:`context managers <context manager>`. :func:`mkstemp` and
22 :func:`mkdtemp` are lower-level functions which require manual cleanup.
23
24 All the user-callable functions and constructors take additional arguments which
25 allow direct control over the location and name of temporary files and
26 directories. Files names used by this module include a string of
27 random characters which allows those files to be securely created in
28 shared temporary directories.
29 To maintain backward compatibility, the argument order is somewhat odd; it
30 is recommended to use keyword arguments for clarity.
31
32 The 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 :term:`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:const:`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:const:`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, delete_on_close=True)
79
80 This function operates exactly as :func:`TemporaryFile` does, except the
81 following differences:
82
83 * This function returns a file that is guaranteed to have a visible name in
84 the file system.
85 * To manage the named file, it extends the parameters of
86 :func:`TemporaryFile` with *delete* and *delete_on_close* parameters that
87 determine whether and how the named file should be automatically deleted.
88
89 The returned object is always a :term:`file-like object` whose :attr:`!file`
90 attribute is the underlying true file object. This file-like object
91 can be used in a :keyword:`with` statement, just like a normal file. The
92 name of the temporary file can be retrieved from the :attr:`!name` attribute
93 of the returned file-like object. On Unix, unlike with the
94 :func:`TemporaryFile`, the directory entry does not get unlinked immediately
95 after the file creation.
96
97 If *delete* is true (the default) and *delete_on_close* is true (the
98 default), the file is deleted as soon as it is closed. If *delete* is true
99 and *delete_on_close* is false, the file is deleted on context manager exit
100 only, or else when the :term:`file-like object` is finalized. Deletion is not
101 always guaranteed in this case (see :meth:`object.__del__`). If *delete* is
102 false, the value of *delete_on_close* is ignored.
103
104 Therefore to use the name of the temporary file to reopen the file after
105 closing it, either make sure not to delete the file upon closure (set the
106 *delete* parameter to be false) or, in case the temporary file is created in
107 a :keyword:`with` statement, set the *delete_on_close* parameter to be false.
108 The latter approach is recommended as it provides assistance in automatic
109 cleaning of the temporary file upon the context manager exit.
110
111 Opening the temporary file again by its name while it is still open works as
112 follows:
113
114 * On POSIX the file can always be opened again.
115 * On Windows, make sure that at least one of the following conditions are
116 fulfilled:
117
118 * *delete* is false
119 * additional open shares delete access (e.g. by calling :func:`os.open`
120 with the flag ``O_TEMPORARY``)
121 * *delete* is true but *delete_on_close* is false. Note, that in this
122 case the additional opens that do not share delete access (e.g.
123 created via builtin :func:`open`) must be closed before exiting the
124 context manager, else the :func:`os.unlink` call on context manager
125 exit will fail with a :exc:`PermissionError`.
126
127 On Windows, if *delete_on_close* is false, and the file is created in a
128 directory for which the user lacks delete access, then the :func:`os.unlink`
129 call on exit of the context manager will fail with a :exc:`PermissionError`.
130 This cannot happen when *delete_on_close* is true because delete access is
131 requested by the open, which fails immediately if the requested access is not
132 granted.
133
134 On POSIX (only), a process that is terminated abruptly with SIGKILL
135 cannot automatically delete any NamedTemporaryFiles it created.
136
137 .. audit-event:: tempfile.mkstemp fullpath tempfile.NamedTemporaryFile
138
139 .. versionchanged:: 3.8
140 Added *errors* parameter.
141
142 .. versionchanged:: 3.12
143 Added *delete_on_close* parameter.
144
145
146 .. class:: SpooledTemporaryFile(max_size=0, mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)
147
148 This class operates exactly as :func:`TemporaryFile` does, except that
149 data is spooled in memory until the file size exceeds *max_size*, or
150 until the file's :func:`~io.IOBase.fileno` method is called, at which point the
151 contents are written to disk and operation proceeds as with
152 :func:`TemporaryFile`.
153
154 .. method:: SpooledTemporaryFile.rollover
155
156 The resulting file has one additional method, :meth:`!rollover`, which
157 causes the file to roll over to an on-disk file regardless of its size.
158
159 The returned object is a file-like object whose :attr:`!_file` attribute
160 is either an :class:`io.BytesIO` or :class:`io.TextIOWrapper` object
161 (depending on whether binary or text *mode* was specified) or a true file
162 object, depending on whether :meth:`rollover` has been called. This
163 file-like object can be used in a :keyword:`with` statement, just like
164 a normal file.
165
166 .. versionchanged:: 3.3
167 the truncate method now accepts a *size* argument.
168
169 .. versionchanged:: 3.8
170 Added *errors* parameter.
171
172 .. versionchanged:: 3.11
173 Fully implements the :class:`io.BufferedIOBase` and
174 :class:`io.TextIOBase` abstract base classes (depending on whether binary
175 or text *mode* was specified).
176
177
178 .. class:: TemporaryDirectory(suffix=None, prefix=None, dir=None, ignore_cleanup_errors=False, *, delete=True)
179
180 This class securely creates a temporary directory using the same rules as :func:`mkdtemp`.
181 The resulting object can be used as a :term:`context manager` (see
182 :ref:`tempfile-examples`). On completion of the context or destruction
183 of the temporary directory object, the newly created temporary directory
184 and all its contents are removed from the filesystem.
185
186 .. attribute:: TemporaryDirectory.name
187
188 The directory name can be retrieved from the :attr:`!name` attribute of the
189 returned object. When the returned object is used as a :term:`context manager`, the
190 :attr:`!name` will be assigned to the target of the :keyword:`!as` clause in
191 the :keyword:`with` statement, if there is one.
192
193 .. method:: TemporaryDirectory.cleanup
194
195 The directory can be explicitly cleaned up by calling the
196 :meth:`!cleanup` method. If *ignore_cleanup_errors* is true, any unhandled
197 exceptions during explicit or implicit cleanup (such as a
198 :exc:`PermissionError` removing open files on Windows) will be ignored,
199 and the remaining removable items deleted on a "best-effort" basis.
200 Otherwise, errors will be raised in whatever context cleanup occurs
201 (the :meth:`!cleanup` call, exiting the context manager, when the object
202 is garbage-collected or during interpreter shutdown).
203
204 The *delete* parameter can be used to disable cleanup of the directory tree
205 upon exiting the context. While it may seem unusual for a context manager
206 to disable the action taken when exiting the context, it can be useful during
207 debugging or when you need your cleanup behavior to be conditional based on
208 other logic.
209
210 .. audit-event:: tempfile.mkdtemp fullpath tempfile.TemporaryDirectory
211
212 .. versionadded:: 3.2
213
214 .. versionchanged:: 3.10
215 Added *ignore_cleanup_errors* parameter.
216
217 .. versionchanged:: 3.12
218 Added the *delete* parameter.
219
220
221 .. function:: mkstemp(suffix=None, prefix=None, dir=None, text=False)
222
223 Creates a temporary file in the most secure manner possible. There are
224 no race conditions in the file's creation, assuming that the platform
225 properly implements the :const:`os.O_EXCL` flag for :func:`os.open`. The
226 file is readable and writable only by the creating user ID. If the
227 platform uses permission bits to indicate whether a file is executable,
228 the file is executable by no one.
229
230 The file descriptor is :ref:`not inherited by child processes <fd_inheritance>`.
231
232 Unlike :func:`TemporaryFile`, the user of :func:`mkstemp` is responsible
233 for deleting the temporary file when done with it.
234
235 If *suffix* is not ``None``, the file name will end with that suffix,
236 otherwise there will be no suffix. :func:`mkstemp` does not put a dot
237 between the file name and the suffix; if you need one, put it at the
238 beginning of *suffix*.
239
240 If *prefix* is not ``None``, the file name will begin with that prefix;
241 otherwise, a default prefix is used. The default is the return value of
242 :func:`gettempprefix` or :func:`gettempprefixb`, as appropriate.
243
244 If *dir* is not ``None``, the file will be created in that directory;
245 otherwise, a default directory is used. The default directory is chosen
246 from a platform-dependent list, but the user of the application can
247 control the directory location by setting the *TMPDIR*, *TEMP* or *TMP*
248 environment variables. There is thus no guarantee that the generated
249 filename will have any nice properties, such as not requiring quoting
250 when passed to external commands via ``os.popen()``.
251
252 If any of *suffix*, *prefix*, and *dir* are not
253 ``None``, they must be the same type.
254 If they are bytes, the returned name will be bytes instead of str.
255 If you want to force a bytes return value with otherwise default behavior,
256 pass ``suffix=b''``.
257
258 If *text* is specified and true, the file is opened in text mode.
259 Otherwise, (the default) the file is opened in binary mode.
260
261 :func:`mkstemp` returns a tuple containing an OS-level handle to an open
262 file (as would be returned by :func:`os.open`) and the absolute pathname
263 of that file, in that order.
264
265 .. audit-event:: tempfile.mkstemp fullpath tempfile.mkstemp
266
267 .. versionchanged:: 3.5
268 *suffix*, *prefix*, and *dir* may now be supplied in bytes in order to
269 obtain a bytes return value. Prior to this, only str was allowed.
270 *suffix* and *prefix* now accept and default to ``None`` to cause
271 an appropriate default value to be used.
272
273 .. versionchanged:: 3.6
274 The *dir* parameter now accepts a :term:`path-like object`.
275
276
277 .. function:: mkdtemp(suffix=None, prefix=None, dir=None)
278
279 Creates a temporary directory in the most secure manner possible. There
280 are no race conditions in the directory's creation. The directory is
281 readable, writable, and searchable only by the creating user ID.
282
283 The user of :func:`mkdtemp` is responsible for deleting the temporary
284 directory and its contents when done with it.
285
286 The *prefix*, *suffix*, and *dir* arguments are the same as for
287 :func:`mkstemp`.
288
289 :func:`mkdtemp` returns the absolute pathname of the new directory.
290
291 .. audit-event:: tempfile.mkdtemp fullpath tempfile.mkdtemp
292
293 .. versionchanged:: 3.5
294 *suffix*, *prefix*, and *dir* may now be supplied in bytes in order to
295 obtain a bytes return value. Prior to this, only str was allowed.
296 *suffix* and *prefix* now accept and default to ``None`` to cause
297 an appropriate default value to be used.
298
299 .. versionchanged:: 3.6
300 The *dir* parameter now accepts a :term:`path-like object`.
301
302 .. versionchanged:: 3.12
303 :func:`mkdtemp` now always returns an absolute path, even if *dir* is relative.
304
305
306 .. function:: gettempdir()
307
308 Return the name of the directory used for temporary files. This
309 defines the default value for the *dir* argument to all functions
310 in this module.
311
312 Python searches a standard list of directories to find one which
313 the calling user can create files in. The list is:
314
315 #. The directory named by the :envvar:`TMPDIR` environment variable.
316
317 #. The directory named by the :envvar:`TEMP` environment variable.
318
319 #. The directory named by the :envvar:`TMP` environment variable.
320
321 #. A platform-specific location:
322
323 * On Windows, the directories :file:`C:\\TEMP`, :file:`C:\\TMP`,
324 :file:`\\TEMP`, and :file:`\\TMP`, in that order.
325
326 * On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and
327 :file:`/usr/tmp`, in that order.
328
329 #. As a last resort, the current working directory.
330
331 The result of this search is cached, see the description of
332 :data:`tempdir` below.
333
334 .. versionchanged:: 3.10
335
336 Always returns a str. Previously it would return any :data:`tempdir`
337 value regardless of type so long as it was not ``None``.
338
339 .. function:: gettempdirb()
340
341 Same as :func:`gettempdir` but the return value is in bytes.
342
343 .. versionadded:: 3.5
344
345 .. function:: gettempprefix()
346
347 Return the filename prefix used to create temporary files. This does not
348 contain the directory component.
349
350 .. function:: gettempprefixb()
351
352 Same as :func:`gettempprefix` but the return value is in bytes.
353
354 .. versionadded:: 3.5
355
356 The module uses a global variable to store the name of the directory
357 used for temporary files returned by :func:`gettempdir`. It can be
358 set directly to override the selection process, but this is discouraged.
359 All functions in this module take a *dir* argument which can be used
360 to specify the directory. This is the recommended approach that does
361 not surprise other unsuspecting code by changing global API behavior.
362
363 .. data:: tempdir
364
365 When set to a value other than ``None``, this variable defines the
366 default value for the *dir* argument to the functions defined in this
367 module, including its type, bytes or str. It cannot be a
368 :term:`path-like object`.
369
370 If ``tempdir`` is ``None`` (the default) at any call to any of the above
371 functions except :func:`gettempprefix` it is initialized following the
372 algorithm described in :func:`gettempdir`.
373
374 .. note::
375
376 Beware that if you set ``tempdir`` to a bytes value, there is a
377 nasty side effect: The global default return type of
378 :func:`mkstemp` and :func:`mkdtemp` changes to bytes when no
379 explicit ``prefix``, ``suffix``, or ``dir`` arguments of type
380 str are supplied. Please do not write code expecting or
381 depending on this. This awkward behavior is maintained for
382 compatibility with the historical implementation.
383
384 .. _tempfile-examples:
385
386 Examples
387 --------
388
389 Here are some examples of typical usage of the :mod:`!tempfile` module::
390
391 >>> import tempfile
392
393 # create a temporary file and write some data to it
394 >>> fp = tempfile.TemporaryFile()
395 >>> fp.write(b'Hello world!')
396 # read data from file
397 >>> fp.seek(0)
398 >>> fp.read()
399 b'Hello world!'
400 # close the file, it will be removed
401 >>> fp.close()
402
403 # create a temporary file using a context manager
404 >>> with tempfile.TemporaryFile() as fp:
405 ... fp.write(b'Hello world!')
406 ... fp.seek(0)
407 ... fp.read()
408 b'Hello world!'
409 >>>
410 # file is now closed and removed
411
412 # create a temporary file using a context manager
413 # close the file, use the name to open the file again
414 >>> with tempfile.NamedTemporaryFile(delete_on_close=False) as fp:
415 ... fp.write(b'Hello world!')
416 ... fp.close()
417 ... # the file is closed, but not removed
418 ... # open the file again by using its name
419 ... with open(fp.name, mode='rb') as f:
420 ... f.read()
421 b'Hello world!'
422 >>>
423 # file is now removed
424
425 # create a temporary directory using the context manager
426 >>> with tempfile.TemporaryDirectory() as tmpdirname:
427 ... print('created temporary directory', tmpdirname)
428 >>>
429 # directory and contents have been removed
430
431 .. _tempfile-mktemp-deprecated:
432
433 Deprecated functions and variables
434 ----------------------------------
435
436 A historical way to create temporary files was to first generate a
437 file name with the :func:`mktemp` function and then create a file
438 using this name. Unfortunately this is not secure, because a different
439 process may create a file with this name in the time between the call
440 to :func:`mktemp` and the subsequent attempt to create the file by the
441 first process. The solution is to combine the two steps and create the
442 file immediately. This approach is used by :func:`mkstemp` and the
443 other functions described above.
444
445 .. function:: mktemp(suffix='', prefix='tmp', dir=None)
446
447 .. deprecated:: 2.3
448 Use :func:`mkstemp` instead.
449
450 Return an absolute pathname of a file that did not exist at the time the
451 call is made. The *prefix*, *suffix*, and *dir* arguments are similar
452 to those of :func:`mkstemp`, except that bytes file names, ``suffix=None``
453 and ``prefix=None`` are not supported.
454
455 .. warning::
456
457 Use of this function may introduce a security hole in your program. By
458 the time you get around to doing anything with the file name it returns,
459 someone else may have beaten you to the punch. :func:`mktemp` usage can
460 be replaced easily with :func:`NamedTemporaryFile`, passing it the
461 ``delete=False`` parameter::
462
463 >>> f = NamedTemporaryFile(delete=False)
464 >>> f.name
465 '/tmp/tmptjujjt'
466 >>> f.write(b"Hello World!\n")
467 13
468 >>> f.close()
469 >>> os.unlink(f.name)
470 >>> os.path.exists(f.name)
471 False