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 closing the file descriptor (for example, using :func:`os.close`) and
234 deleting the temporary file (for example, using :func:`os.remove`).
235
236 If *suffix* is not ``None``, the file name will end with that suffix,
237 otherwise there will be no suffix. :func:`mkstemp` does not put a dot
238 between the file name and the suffix; if you need one, put it at the
239 beginning of *suffix*.
240
241 If *prefix* is not ``None``, the file name will begin with that prefix;
242 otherwise, a default prefix is used. The default is the return value of
243 :func:`gettempprefix` or :func:`gettempprefixb`, as appropriate.
244
245 If *dir* is not ``None``, the file will be created in that directory;
246 otherwise, a default directory is used. The default directory is chosen
247 from a platform-dependent list, but the user of the application can
248 control the directory location by setting the *TMPDIR*, *TEMP* or *TMP*
249 environment variables. There is thus no guarantee that the generated
250 filename will have any nice properties, such as not requiring quoting
251 when passed to external commands via ``os.popen()``.
252
253 If any of *suffix*, *prefix*, and *dir* are not
254 ``None``, they must be the same type.
255 If they are bytes, the returned name will be bytes instead of str.
256 If you want to force a bytes return value with otherwise default behavior,
257 pass ``suffix=b''``.
258
259 If *text* is specified and true, the file is opened in text mode.
260 Otherwise, (the default) the file is opened in binary mode.
261
262 :func:`mkstemp` returns a tuple containing an OS-level handle to an open
263 file (as would be returned by :func:`os.open`) and the absolute pathname
264 of that file, in that order.
265
266 .. audit-event:: tempfile.mkstemp fullpath tempfile.mkstemp
267
268 .. versionchanged:: 3.5
269 *suffix*, *prefix*, and *dir* may now be supplied in bytes in order to
270 obtain a bytes return value. Prior to this, only str was allowed.
271 *suffix* and *prefix* now accept and default to ``None`` to cause
272 an appropriate default value to be used.
273
274 .. versionchanged:: 3.6
275 The *dir* parameter now accepts a :term:`path-like object`.
276
277
278 .. function:: mkdtemp(suffix=None, prefix=None, dir=None)
279
280 Creates a temporary directory in the most secure manner possible. There
281 are no race conditions in the directory's creation. The directory is
282 readable, writable, and searchable only by the creating user ID.
283
284 The user of :func:`mkdtemp` is responsible for deleting the temporary
285 directory and its contents when done with it.
286
287 The *prefix*, *suffix*, and *dir* arguments are the same as for
288 :func:`mkstemp`.
289
290 :func:`mkdtemp` returns the absolute pathname of the new directory.
291
292 .. audit-event:: tempfile.mkdtemp fullpath tempfile.mkdtemp
293
294 .. versionchanged:: 3.5
295 *suffix*, *prefix*, and *dir* may now be supplied in bytes in order to
296 obtain a bytes return value. Prior to this, only str was allowed.
297 *suffix* and *prefix* now accept and default to ``None`` to cause
298 an appropriate default value to be used.
299
300 .. versionchanged:: 3.6
301 The *dir* parameter now accepts a :term:`path-like object`.
302
303 .. versionchanged:: 3.12
304 :func:`mkdtemp` now always returns an absolute path, even if *dir* is relative.
305
306
307 .. function:: gettempdir()
308
309 Return the name of the directory used for temporary files. This
310 defines the default value for the *dir* argument to all functions
311 in this module.
312
313 Python searches a standard list of directories to find one which
314 the calling user can create files in. The list is:
315
316 #. The directory named by the :envvar:`TMPDIR` environment variable.
317
318 #. The directory named by the :envvar:`TEMP` environment variable.
319
320 #. The directory named by the :envvar:`TMP` environment variable.
321
322 #. A platform-specific location:
323
324 * On Windows, the directories :file:`C:\\TEMP`, :file:`C:\\TMP`,
325 :file:`\\TEMP`, and :file:`\\TMP`, in that order.
326
327 * On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and
328 :file:`/usr/tmp`, in that order.
329
330 #. As a last resort, the current working directory.
331
332 The result of this search is cached, see the description of
333 :data:`tempdir` below.
334
335 .. versionchanged:: 3.10
336
337 Always returns a str. Previously it would return any :data:`tempdir`
338 value regardless of type so long as it was not ``None``.
339
340 .. function:: gettempdirb()
341
342 Same as :func:`gettempdir` but the return value is in bytes.
343
344 .. versionadded:: 3.5
345
346 .. function:: gettempprefix()
347
348 Return the filename prefix used to create temporary files. This does not
349 contain the directory component.
350
351 .. function:: gettempprefixb()
352
353 Same as :func:`gettempprefix` but the return value is in bytes.
354
355 .. versionadded:: 3.5
356
357 The module uses a global variable to store the name of the directory
358 used for temporary files returned by :func:`gettempdir`. It can be
359 set directly to override the selection process, but this is discouraged.
360 All functions in this module take a *dir* argument which can be used
361 to specify the directory. This is the recommended approach that does
362 not surprise other unsuspecting code by changing global API behavior.
363
364 .. data:: tempdir
365
366 When set to a value other than ``None``, this variable defines the
367 default value for the *dir* argument to the functions defined in this
368 module, including its type, bytes or str. It cannot be a
369 :term:`path-like object`.
370
371 If ``tempdir`` is ``None`` (the default) at any call to any of the above
372 functions except :func:`gettempprefix` it is initialized following the
373 algorithm described in :func:`gettempdir`.
374
375 .. note::
376
377 Beware that if you set ``tempdir`` to a bytes value, there is a
378 nasty side effect: The global default return type of
379 :func:`mkstemp` and :func:`mkdtemp` changes to bytes when no
380 explicit ``prefix``, ``suffix``, or ``dir`` arguments of type
381 str are supplied. Please do not write code expecting or
382 depending on this. This awkward behavior is maintained for
383 compatibility with the historical implementation.
384
385 .. _tempfile-examples:
386
387 Examples
388 --------
389
390 Here are some examples of typical usage of the :mod:`tempfile` module::
391
392 >>> import tempfile
393
394 # create a temporary file and write some data to it
395 >>> fp = tempfile.TemporaryFile()
396 >>> fp.write(b'Hello world!')
397 # read data from file
398 >>> fp.seek(0)
399 >>> fp.read()
400 b'Hello world!'
401 # close the file, it will be removed
402 >>> fp.close()
403
404 # create a temporary file using a context manager
405 >>> with tempfile.TemporaryFile() as fp:
406 ... fp.write(b'Hello world!')
407 ... fp.seek(0)
408 ... fp.read()
409 b'Hello world!'
410 >>>
411 # file is now closed and removed
412
413 # create a temporary file using a context manager
414 # close the file, use the name to open the file again
415 >>> with tempfile.NamedTemporaryFile(delete_on_close=False) as fp:
416 ... fp.write(b'Hello world!')
417 ... fp.close()
418 ... # the file is closed, but not removed
419 ... # open the file again by using its name
420 ... with open(fp.name, mode='rb') as f:
421 ... f.read()
422 b'Hello world!'
423 >>>
424 # file is now removed
425
426 # create a temporary directory using the context manager
427 >>> with tempfile.TemporaryDirectory() as tmpdirname:
428 ... print('created temporary directory', tmpdirname)
429 >>>
430 # directory and contents have been removed
431
432 .. _tempfile-mktemp-deprecated:
433
434 Deprecated functions and variables
435 ----------------------------------
436
437 A historical way to create temporary files was to first generate a
438 file name with the :func:`mktemp` function and then create a file
439 using this name. Unfortunately this is not secure, because a different
440 process may create a file with this name in the time between the call
441 to :func:`mktemp` and the subsequent attempt to create the file by the
442 first process. The solution is to combine the two steps and create the
443 file immediately. This approach is used by :func:`mkstemp` and the
444 other functions described above.
445
446 .. function:: mktemp(suffix='', prefix='tmp', dir=None)
447
448 .. deprecated:: 2.3
449 Use :func:`mkstemp` instead.
450
451 Return an absolute pathname of a file that did not exist at the time the
452 call is made. The *prefix*, *suffix*, and *dir* arguments are similar
453 to those of :func:`mkstemp`, except that bytes file names, ``suffix=None``
454 and ``prefix=None`` are not supported.
455
456 .. warning::
457
458 Use of this function may introduce a security hole in your program. By
459 the time you get around to doing anything with the file name it returns,
460 someone else may have beaten you to the punch. :func:`mktemp` usage can
461 be replaced easily with :func:`NamedTemporaryFile`, passing it the
462 ``delete=False`` parameter::
463
464 >>> f = NamedTemporaryFile(delete=False)
465 >>> f.name
466 '/tmp/tmptjujjt'
467 >>> f.write(b"Hello World!\n")
468 13
469 >>> f.close()
470 >>> os.unlink(f.name)
471 >>> os.path.exists(f.name)
472 False