blob: fff6c4eb57251c167b4a64c7b575915ef5011800 [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`tempfile` --- Generate temporary files and directories
2============================================================
3
4.. sectionauthor:: Zack Weinberg <zack@codesourcery.com>
5
6
7.. module:: tempfile
8 :synopsis: Generate temporary files and directories.
9
10
11.. index::
12 pair: temporary; file name
13 pair: temporary; file
14
Raymond Hettingera1993682011-01-27 01:20:32 +000015**Source code:** :source:`Lib/tempfile.py`
16
17--------------
18
Georg Brandl116aa622007-08-15 14:28:22 +000019This module generates temporary files and directories. It works on all
Georg Brandle6bcc912008-05-12 18:05:20 +000020supported platforms. It provides three new functions,
21:func:`NamedTemporaryFile`, :func:`mkstemp`, and :func:`mkdtemp`, which should
22eliminate all remaining need to use the insecure :func:`mktemp` function.
23Temporary file names created by this module no longer contain the process ID;
24instead a string of six random characters is used.
Georg Brandl116aa622007-08-15 14:28:22 +000025
Christian Heimes81ee3ef2008-05-04 22:42:01 +000026Also, all the user-callable functions now take additional arguments which
27allow direct control over the location and name of temporary files. It is
28no longer necessary to use the global *tempdir* and *template* variables.
29To maintain backward compatibility, the argument order is somewhat odd; it
30is recommended to use keyword arguments for clarity.
Georg Brandl116aa622007-08-15 14:28:22 +000031
Nick Coghlan543af752010-10-24 11:23:25 +000032The module defines the following user-callable items:
Georg Brandl116aa622007-08-15 14:28:22 +000033
Georg Brandl14dfede2010-05-21 21:12:07 +000034.. function:: TemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix='', prefix='tmp', dir=None)
Georg Brandl116aa622007-08-15 14:28:22 +000035
Antoine Pitrou11cb9612010-09-15 11:11:28 +000036 Return a :term:`file-like object` that can be used as a temporary storage area.
Christian Heimes81ee3ef2008-05-04 22:42:01 +000037 The file is created using :func:`mkstemp`. It will be destroyed as soon
Georg Brandl116aa622007-08-15 14:28:22 +000038 as it is closed (including an implicit close when the object is garbage
Christian Heimes81ee3ef2008-05-04 22:42:01 +000039 collected). Under Unix, the directory entry for the file 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.
Georg Brandl116aa622007-08-15 14:28:22 +000043
Christian Heimes81ee3ef2008-05-04 22:42:01 +000044 The *mode* parameter defaults to ``'w+b'`` so that the file created can
45 be read and written without being closed. Binary mode is used so that it
46 behaves consistently on all platforms without regard for the data that is
Georg Brandl14dfede2010-05-21 21:12:07 +000047 stored. *buffering*, *encoding* and *newline* are interpreted as for
48 :func:`open`.
Georg Brandl116aa622007-08-15 14:28:22 +000049
50 The *dir*, *prefix* and *suffix* parameters are passed to :func:`mkstemp`.
51
Christian Heimes7f044312008-01-06 17:05:40 +000052 The returned object is a true file object on POSIX platforms. On other
Georg Brandl502d9a52009-07-26 15:02:41 +000053 platforms, it is a file-like object whose :attr:`!file` attribute is the
Christian Heimes81ee3ef2008-05-04 22:42:01 +000054 underlying true file object. This file-like object can be used in a
Christian Heimes3ecfea712008-02-09 20:51:34 +000055 :keyword:`with` statement, just like a normal file.
Christian Heimes7f044312008-01-06 17:05:40 +000056
Georg Brandl116aa622007-08-15 14:28:22 +000057
Georg Brandl14dfede2010-05-21 21:12:07 +000058.. function:: NamedTemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix='', prefix='tmp', dir=None, delete=True)
Georg Brandl116aa622007-08-15 14:28:22 +000059
Christian Heimes81ee3ef2008-05-04 22:42:01 +000060 This function operates exactly as :func:`TemporaryFile` does, except that
61 the file is guaranteed to have a visible name in the file system (on
62 Unix, the directory entry is not unlinked). That name can be retrieved
Senthil Kumarana6bac952011-07-04 11:28:30 -070063 from the :attr:`name` attribute of the file object. Whether the name can be
Christian Heimes81ee3ef2008-05-04 22:42:01 +000064 used to open the file a second time, while the named temporary file is
65 still open, varies across platforms (it can be so used on Unix; it cannot
66 on Windows NT or later). If *delete* is true (the default), the file is
67 deleted as soon as it is closed.
Georg Brandl502d9a52009-07-26 15:02:41 +000068 The returned object is always a file-like object whose :attr:`!file`
Christian Heimes81ee3ef2008-05-04 22:42:01 +000069 attribute is the underlying true file object. This file-like object can
70 be used in a :keyword:`with` statement, just like a normal file.
Georg Brandl116aa622007-08-15 14:28:22 +000071
Georg Brandl116aa622007-08-15 14:28:22 +000072
Georg Brandl14dfede2010-05-21 21:12:07 +000073.. function:: SpooledTemporaryFile(max_size=0, mode='w+b', buffering=None, encoding=None, newline=None, suffix='', prefix='tmp', dir=None)
Georg Brandl116aa622007-08-15 14:28:22 +000074
Christian Heimes81ee3ef2008-05-04 22:42:01 +000075 This function operates exactly as :func:`TemporaryFile` does, except that
76 data is spooled in memory until the file size exceeds *max_size*, or
77 until the file's :func:`fileno` method is called, at which point the
78 contents are written to disk and operation proceeds as with
79 :func:`TemporaryFile`.
Georg Brandl116aa622007-08-15 14:28:22 +000080
Christian Heimes81ee3ef2008-05-04 22:42:01 +000081 The resulting file has one additional method, :func:`rollover`, which
82 causes the file to roll over to an on-disk file regardless of its size.
Georg Brandl116aa622007-08-15 14:28:22 +000083
Christian Heimes81ee3ef2008-05-04 22:42:01 +000084 The returned object is a file-like object whose :attr:`_file` attribute
85 is either a :class:`StringIO` object or a true file object, depending on
86 whether :func:`rollover` has been called. This file-like object can be
87 used in a :keyword:`with` statement, just like a normal file.
88
89
Nick Coghlan543af752010-10-24 11:23:25 +000090.. function:: TemporaryDirectory(suffix='', prefix='tmp', dir=None)
91
92 This function creates a temporary directory using :func:`mkdtemp`
93 (the supplied arguments are passed directly to the underlying function).
94 The resulting object can be used as a context manager (see
95 :ref:`context-managers`). On completion of the context (or destruction
96 of the temporary directory object), the newly created temporary directory
97 and all its contents are removed from the filesystem.
98
Senthil Kumarana6bac952011-07-04 11:28:30 -070099 The directory name can be retrieved from the :attr:`name` attribute
Nick Coghlan543af752010-10-24 11:23:25 +0000100 of the returned object.
101
102 The directory can be explicitly cleaned up by calling the
103 :func:`cleanup` method.
104
105 .. versionadded:: 3.2
106
107
Georg Brandl7f01a132009-09-16 15:58:14 +0000108.. function:: mkstemp(suffix='', prefix='tmp', dir=None, text=False)
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000109
110 Creates a temporary file in the most secure manner possible. There are
111 no race conditions in the file's creation, assuming that the platform
112 properly implements the :const:`os.O_EXCL` flag for :func:`os.open`. The
113 file is readable and writable only by the creating user ID. If the
114 platform uses permission bits to indicate whether a file is executable,
115 the file is executable by no one. The file descriptor is not inherited
116 by child processes.
117
118 Unlike :func:`TemporaryFile`, the user of :func:`mkstemp` is responsible
119 for deleting the temporary file when done with it.
120
121 If *suffix* is specified, the file name will end with that suffix,
122 otherwise there will be no suffix. :func:`mkstemp` does not put a dot
123 between the file name and the suffix; if you need one, put it at the
124 beginning of *suffix*.
125
126 If *prefix* is specified, the file name will begin with that prefix;
127 otherwise, a default prefix is used.
128
129 If *dir* is specified, the file will be created in that directory;
130 otherwise, a default directory is used. The default directory is chosen
131 from a platform-dependent list, but the user of the application can
132 control the directory location by setting the *TMPDIR*, *TEMP* or *TMP*
133 environment variables. There is thus no guarantee that the generated
134 filename will have any nice properties, such as not requiring quoting
135 when passed to external commands via ``os.popen()``.
136
137 If *text* is specified, it indicates whether to open the file in binary
138 mode (the default) or text mode. On some platforms, this makes no
139 difference.
140
141 :func:`mkstemp` returns a tuple containing an OS-level handle to an open
142 file (as would be returned by :func:`os.open`) and the absolute pathname
143 of that file, in that order.
144
145
Georg Brandl7f01a132009-09-16 15:58:14 +0000146.. function:: mkdtemp(suffix='', prefix='tmp', dir=None)
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000147
148 Creates a temporary directory in the most secure manner possible. There
149 are no race conditions in the directory's creation. The directory is
150 readable, writable, and searchable only by the creating user ID.
151
152 The user of :func:`mkdtemp` is responsible for deleting the temporary
153 directory and its contents when done with it.
154
155 The *prefix*, *suffix*, and *dir* arguments are the same as for
156 :func:`mkstemp`.
Georg Brandl116aa622007-08-15 14:28:22 +0000157
158 :func:`mkdtemp` returns the absolute pathname of the new directory.
159
Georg Brandl116aa622007-08-15 14:28:22 +0000160
Georg Brandl7f01a132009-09-16 15:58:14 +0000161.. function:: mktemp(suffix='', prefix='tmp', dir=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000162
163 .. deprecated:: 2.3
164 Use :func:`mkstemp` instead.
165
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000166 Return an absolute pathname of a file that did not exist at the time the
167 call is made. The *prefix*, *suffix*, and *dir* arguments are the same
168 as for :func:`mkstemp`.
Georg Brandl116aa622007-08-15 14:28:22 +0000169
170 .. warning::
171
Georg Brandl36ab1ef2009-01-03 21:17:04 +0000172 Use of this function may introduce a security hole in your program. By
173 the time you get around to doing anything with the file name it returns,
174 someone else may have beaten you to the punch. :func:`mktemp` usage can
175 be replaced easily with :func:`NamedTemporaryFile`, passing it the
176 ``delete=False`` parameter::
Alexandre Vassalotti6461e102008-05-15 22:09:29 +0000177
178 >>> f = NamedTemporaryFile(delete=False)
Alexandre Vassalotti6461e102008-05-15 22:09:29 +0000179 >>> f
180 <open file '<fdopen>', mode 'w+b' at 0x384698>
181 >>> f.name
182 '/var/folders/5q/5qTPn6xq2RaWqk+1Ytw3-U+++TI/-Tmp-/tmpG7V1Y0'
183 >>> f.write("Hello World!\n")
184 >>> f.close()
185 >>> os.unlink(f.name)
186 >>> os.path.exists(f.name)
187 False
Georg Brandl116aa622007-08-15 14:28:22 +0000188
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000189The module uses two global variables that tell it how to construct a
190temporary name. They are initialized at the first call to any of the
191functions above. The caller may change them, but this is discouraged; use
192the appropriate function arguments, instead.
Georg Brandl116aa622007-08-15 14:28:22 +0000193
194
195.. data:: tempdir
196
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000197 When set to a value other than ``None``, this variable defines the
198 default value for the *dir* argument to all the functions defined in this
199 module.
Georg Brandl116aa622007-08-15 14:28:22 +0000200
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000201 If ``tempdir`` is unset or ``None`` at any call to any of the above
202 functions, Python searches a standard list of directories and sets
203 *tempdir* to the first one which the calling user can create files in.
204 The list is:
Georg Brandl116aa622007-08-15 14:28:22 +0000205
206 #. The directory named by the :envvar:`TMPDIR` environment variable.
207
208 #. The directory named by the :envvar:`TEMP` environment variable.
209
210 #. The directory named by the :envvar:`TMP` environment variable.
211
212 #. A platform-specific location:
213
Georg Brandl116aa622007-08-15 14:28:22 +0000214 * On Windows, the directories :file:`C:\\TEMP`, :file:`C:\\TMP`,
215 :file:`\\TEMP`, and :file:`\\TMP`, in that order.
216
217 * On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and
218 :file:`/usr/tmp`, in that order.
219
220 #. As a last resort, the current working directory.
221
222
223.. function:: gettempdir()
224
225 Return the directory currently selected to create temporary files in. If
226 :data:`tempdir` is not ``None``, this simply returns its contents; otherwise,
227 the search described above is performed, and the result returned.
228
229
Georg Brandl116aa622007-08-15 14:28:22 +0000230.. function:: gettempprefix()
231
232 Return the filename prefix used to create temporary files. This does not
Georg Brandl4b26ff82008-08-04 07:24:52 +0000233 contain the directory component.
Georg Brandl116aa622007-08-15 14:28:22 +0000234
Nick Coghlan543af752010-10-24 11:23:25 +0000235
236Examples
237--------
238
239Here are some examples of typical usage of the :mod:`tempfile` module::
240
241 >>> import tempfile
242
243 # create a temporary file and write some data to it
244 >>> fp = tempfile.TemporaryFile()
Ross Lagerwall810b94a2011-04-10 09:30:04 +0200245 >>> fp.write(b'Hello world!')
Nick Coghlan543af752010-10-24 11:23:25 +0000246 # read data from file
247 >>> fp.seek(0)
248 >>> fp.read()
Ross Lagerwall810b94a2011-04-10 09:30:04 +0200249 b'Hello world!'
Nick Coghlan543af752010-10-24 11:23:25 +0000250 # close the file, it will be removed
251 >>> fp.close()
252
253 # create a temporary file using a context manager
254 >>> with tempfile.TemporaryFile() as fp:
Ross Lagerwall810b94a2011-04-10 09:30:04 +0200255 ... fp.write(b'Hello world!')
Nick Coghlan543af752010-10-24 11:23:25 +0000256 ... fp.seek(0)
257 ... fp.read()
Ross Lagerwall810b94a2011-04-10 09:30:04 +0200258 b'Hello world!'
Nick Coghlan543af752010-10-24 11:23:25 +0000259 >>>
260 # file is now closed and removed
261
262 # create a temporary directory using the context manager
263 >>> with tempfile.TemporaryDirectory() as tmpdirname:
Ross Lagerwall810b94a2011-04-10 09:30:04 +0200264 ... print('created temporary directory', tmpdirname)
Nick Coghlan543af752010-10-24 11:23:25 +0000265 >>>
266 # directory and contents have been removed
267