1: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 15**Source code:** :source:`Lib/tempfile.py` 16 17-------------- 18 19This module generates temporary files and directories. It works on all 20supported platforms. 21 22In version 2.3 of Python, this module was overhauled for enhanced security. It 23now provides three new functions, :func:`NamedTemporaryFile`, :func:`mkstemp`, 24and :func:`mkdtemp`, which should eliminate all remaining need to use the 25insecure :func:`mktemp` function. Temporary file names created by this module 26no longer contain the process ID; instead a string of six random characters is 27used. 28 29Also, all the user-callable functions now take additional arguments which 30allow direct control over the location and name of temporary files. It is 31no longer necessary to use the global *tempdir* and *template* variables. 32To maintain backward compatibility, the argument order is somewhat odd; it 33is recommended to use keyword arguments for clarity. 34 35The module defines the following user-callable functions: 36 37 38.. function:: TemporaryFile([mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None]]]]]) 39 40 Return a file-like object that can be used as a temporary storage area. 41 The file is created using :func:`mkstemp`. It will be destroyed as soon 42 as it is closed (including an implicit close when the object is garbage 43 collected). Under Unix, the directory entry for the file is removed 44 immediately after the file is created. Other platforms do not support 45 this; your code should not rely on a temporary file created using this 46 function having or not having a visible name in the file system. 47 48 The *mode* parameter defaults to ``'w+b'`` so that the file created can 49 be read and written without being closed. Binary mode is used so that it 50 behaves consistently on all platforms without regard for the data that is 51 stored. *bufsize* defaults to ``-1``, meaning that the operating system 52 default is used. 53 54 The *dir*, *prefix* and *suffix* parameters are passed to :func:`mkstemp`. 55 56 The returned object is a true file object on POSIX platforms. On other 57 platforms, it is a file-like object whose :attr:`!file` attribute is the 58 underlying true file object. This file-like object can be used in a 59 :keyword:`with` statement, just like a normal file. 60 61 62.. function:: NamedTemporaryFile([mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None[, delete=True]]]]]]) 63 64 This function operates exactly as :func:`TemporaryFile` does, except that 65 the file is guaranteed to have a visible name in the file system (on 66 Unix, the directory entry is not unlinked). That name can be retrieved 67 from the :attr:`name` attribute of the returned 68 file-like object. Whether the name can be 69 used to open the file a second time, while the named temporary file is 70 still open, varies across platforms (it can be so used on Unix; it cannot 71 on Windows NT or later). If *delete* is true (the default), the file is 72 deleted as soon as it is closed. 73 74 The returned object is always a file-like object whose :attr:`!file` 75 attribute is the underlying true file object. This file-like object can 76 be used in a :keyword:`with` statement, just like a normal file. 77 78 .. versionadded:: 2.3 79 80 .. versionadded:: 2.6 81 The *delete* parameter. 82 83 84.. function:: SpooledTemporaryFile([max_size=0, [mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None]]]]]]) 85 86 This function operates exactly as :func:`TemporaryFile` does, except that 87 data is spooled in memory until the file size exceeds *max_size*, or 88 until the file's :func:`fileno` method is called, at which point the 89 contents are written to disk and operation proceeds as with 90 :func:`TemporaryFile`. Also, it's ``truncate`` method does not 91 accept a ``size`` argument. 92 93 The resulting file has one additional method, :func:`rollover`, which 94 causes the file to roll over to an on-disk file regardless of its size. 95 96 The returned object is a file-like object whose :attr:`_file` attribute 97 is either a :class:`~StringIO.StringIO` object or a true file object, depending on 98 whether :func:`rollover` has been called. This file-like object can be 99 used in a :keyword:`with` statement, just like a normal file. 100 101 .. versionadded:: 2.6 102 103 104.. function:: mkstemp([suffix=''[, prefix='tmp'[, dir=None[, text=False]]]]) 105 106 Creates a temporary file in the most secure manner possible. There are 107 no race conditions in the file's creation, assuming that the platform 108 properly implements the :const:`os.O_EXCL` flag for :func:`os.open`. The 109 file is readable and writable only by the creating user ID. If the 110 platform uses permission bits to indicate whether a file is executable, 111 the file is executable by no one. The file descriptor is not inherited 112 by child processes. 113 114 Unlike :func:`TemporaryFile`, the user of :func:`mkstemp` is responsible 115 for deleting the temporary file when done with it. 116 117 If *suffix* is specified, the file name will end with that suffix, 118 otherwise there will be no suffix. :func:`mkstemp` does not put a dot 119 between the file name and the suffix; if you need one, put it at the 120 beginning of *suffix*. 121 122 If *prefix* is specified, the file name will begin with that prefix; 123 otherwise, a default prefix is used. 124 125 If *dir* is specified, the file will be created in that directory; 126 otherwise, a default directory is used. The default directory is chosen 127 from a platform-dependent list, but the user of the application can 128 control the directory location by setting the *TMPDIR*, *TEMP* or *TMP* 129 environment variables. There is thus no guarantee that the generated 130 filename will have any nice properties, such as not requiring quoting 131 when passed to external commands via ``os.popen()``. 132 133 If *text* is specified, it indicates whether to open the file in binary 134 mode (the default) or text mode. On some platforms, this makes no 135 difference. 136 137 :func:`mkstemp` returns a tuple containing an OS-level handle to an open 138 file (as would be returned by :func:`os.open`) and the absolute pathname 139 of that file, in that order. 140 141 .. versionadded:: 2.3 142 143 144.. function:: mkdtemp([suffix=''[, prefix='tmp'[, dir=None]]]) 145 146 Creates a temporary directory in the most secure manner possible. There 147 are no race conditions in the directory's creation. The directory is 148 readable, writable, and searchable only by the creating user ID. 149 150 The user of :func:`mkdtemp` is responsible for deleting the temporary 151 directory and its contents when done with it. 152 153 The *prefix*, *suffix*, and *dir* arguments are the same as for 154 :func:`mkstemp`. 155 156 :func:`mkdtemp` returns the absolute pathname of the new directory. 157 158 .. versionadded:: 2.3 159 160 161.. function:: mktemp([suffix=''[, prefix='tmp'[, dir=None]]]) 162 163 .. deprecated:: 2.3 164 Use :func:`mkstemp` instead. 165 166 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`. 169 170 .. warning:: 171 172 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:: 177 178 >>> f = NamedTemporaryFile(delete=False) 179 >>> 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 188 189The module uses a global variable 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. 193 194 195.. data:: tempdir 196 197 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. 200 201 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: 205 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 214 * On RiscOS, the directory named by the :envvar:`Wimp$ScrapDir` environment 215 variable. 216 217 * On Windows, the directories :file:`C:\\TEMP`, :file:`C:\\TMP`, 218 :file:`\\TEMP`, and :file:`\\TMP`, in that order. 219 220 * On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and 221 :file:`/usr/tmp`, in that order. 222 223 #. As a last resort, the current working directory. 224 225 226.. function:: gettempdir() 227 228 Return the directory currently selected to create temporary files in. If 229 :data:`tempdir` is not ``None``, this simply returns its contents; otherwise, 230 the search described above is performed, and the result returned. 231 232 .. versionadded:: 2.3 233 234 235.. data:: template 236 237 .. deprecated:: 2.0 238 Use :func:`gettempprefix` instead. 239 240 When set to a value other than ``None``, this variable defines the prefix of the 241 final component of the filenames returned by :func:`mktemp`. A string of six 242 random letters and digits is appended to the prefix to make the filename unique. 243 The default prefix is :file:`tmp`. 244 245 Older versions of this module used to require that ``template`` be set to 246 ``None`` after a call to :func:`os.fork`; this has not been necessary since 247 version 1.5.2. 248 249 250.. function:: gettempprefix() 251 252 Return the filename prefix used to create temporary files. This does not 253 contain the directory component. Using this function is preferred over reading 254 the *template* variable directly. 255 256 .. versionadded:: 1.5.2 257 258