blob: 97f125250b68e389e883a092d2c782d2db08c57a [file] [log] [blame]
Guido van Rossum0e548712002-08-09 16:14:33 +00001"""Temporary files.
Guido van Rossume7b146f2000-02-04 15:28:42 +00002
Guido van Rossum0e548712002-08-09 16:14:33 +00003This module provides generic, low- and high-level interfaces for
4creating temporary files and directories. The interfaces listed
5as "safe" just below can be used without fear of race conditions.
6Those listed as "unsafe" cannot, and are provided for backward
7compatibility only.
Guido van Rossumeee94981991-11-12 15:38:08 +00008
Guido van Rossum0e548712002-08-09 16:14:33 +00009This module also provides some data items to the user:
Guido van Rossumeee94981991-11-12 15:38:08 +000010
Guido van Rossum0e548712002-08-09 16:14:33 +000011 TMP_MAX - maximum number of names that will be tried before
12 giving up.
13 template - the default prefix for all temporary names.
14 You may change this to control the default prefix.
15 tempdir - If this is set to a string before the first use of
16 any routine from this module, it will be considered as
17 another candidate location to store temporary files.
18"""
Skip Montanaro40fc1602001-03-01 04:27:19 +000019
Guido van Rossum0e548712002-08-09 16:14:33 +000020__all__ = [
21 "NamedTemporaryFile", "TemporaryFile", # high level safe interfaces
22 "mkstemp", "mkdtemp", # low level safe interfaces
23 "mktemp", # deprecated unsafe interface
24 "TMP_MAX", "gettempprefix", # constants
25 "tempdir", "gettempdir"
26 ]
Guido van Rossum41f95031992-03-31 19:02:01 +000027
Tim Peters4fd5a062002-01-28 23:11:23 +000028
Guido van Rossum0e548712002-08-09 16:14:33 +000029# Imports.
Tim Peters4fd5a062002-01-28 23:11:23 +000030
Guido van Rossum0e548712002-08-09 16:14:33 +000031import os as _os
32import errno as _errno
33from random import Random as _Random
34
35if _os.name == 'mac':
36 import macfs as _macfs
37 import MACFS as _MACFS
38
39try:
40 import fcntl as _fcntl
41 def _set_cloexec(fd):
42 flags = _fcntl.fcntl(fd, _fcntl.F_GETFD, 0)
43 if flags >= 0:
44 # flags read successfully, modify
45 flags |= _fcntl.FD_CLOEXEC
46 _fcntl.fcntl(fd, _fcntl.F_SETFD, flags)
47except (ImportError, AttributeError):
48 def _set_cloexec(fd):
49 pass
50
51try:
52 import thread as _thread
53 _allocate_lock = _thread.allocate_lock
54except (ImportError, AttributeError):
55 class _allocate_lock:
56 def acquire(self):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +000057 pass
Guido van Rossum0e548712002-08-09 16:14:33 +000058 release = acquire
59
60_text_openflags = _os.O_RDWR | _os.O_CREAT | _os.O_EXCL
Tim Petersa0d55de2002-08-09 18:01:01 +000061if hasattr(_os, 'O_NOINHERIT'):
62 _text_openflags |= _os.O_NOINHERIT
63if hasattr(_os, 'O_NOFOLLOW'):
64 _text_openflags |= _os.O_NOFOLLOW
Guido van Rossum0e548712002-08-09 16:14:33 +000065
66_bin_openflags = _text_openflags
Tim Petersa0d55de2002-08-09 18:01:01 +000067if hasattr(_os, 'O_BINARY'):
68 _bin_openflags |= _os.O_BINARY
Guido van Rossum0e548712002-08-09 16:14:33 +000069
70if hasattr(_os, 'TMP_MAX'):
71 TMP_MAX = _os.TMP_MAX
72else:
73 TMP_MAX = 10000
74
Tim Petersbd7b4c72002-08-13 23:33:56 +000075template = "tmp"
Guido van Rossum0e548712002-08-09 16:14:33 +000076
77tempdir = None
78
79# Internal routines.
80
81_once_lock = _allocate_lock()
82
Guido van Rossum0e548712002-08-09 16:14:33 +000083class _RandomNameSequence:
84 """An instance of _RandomNameSequence generates an endless
85 sequence of unpredictable strings which can safely be incorporated
86 into file names. Each string is six characters long. Multiple
87 threads can safely use the same instance at the same time.
88
89 _RandomNameSequence is an iterator."""
90
Tim Peters97701b52002-11-21 15:59:59 +000091 characters = ("abcdefghijklmnopqrstuvwxyz" +
92 "ABCDEFGHIJKLMNOPQRSTUVWXYZ" +
93 "0123456789-_")
Guido van Rossum0e548712002-08-09 16:14:33 +000094
95 def __init__(self):
96 self.mutex = _allocate_lock()
97 self.rng = _Random()
98 self.normcase = _os.path.normcase
Tim Peters97701b52002-11-21 15:59:59 +000099
Guido van Rossum0e548712002-08-09 16:14:33 +0000100 def __iter__(self):
101 return self
102
103 def next(self):
104 m = self.mutex
105 c = self.characters
Tim Peters97701b52002-11-21 15:59:59 +0000106 choose = self.rng.choice
Guido van Rossum0e548712002-08-09 16:14:33 +0000107
Tim Peters97701b52002-11-21 15:59:59 +0000108 m.acquire()
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000109 try:
Tim Peters97701b52002-11-21 15:59:59 +0000110 letters = [choose(c) for dummy in "123456"]
Guido van Rossum0e548712002-08-09 16:14:33 +0000111 finally:
112 m.release()
113
Tim Peters97701b52002-11-21 15:59:59 +0000114 return self.normcase(''.join(letters))
Guido van Rossum0e548712002-08-09 16:14:33 +0000115
116def _candidate_tempdir_list():
117 """Generate a list of candidate temporary directories which
118 _get_default_tempdir will try."""
119
120 dirlist = []
121
122 # First, try the environment.
123 for envname in 'TMPDIR', 'TEMP', 'TMP':
124 dirname = _os.getenv(envname)
125 if dirname: dirlist.append(dirname)
126
127 # Failing that, try OS-specific locations.
128 if _os.name == 'mac':
129 try:
130 refnum, dirid = _macfs.FindFolder(_MACFS.kOnSystemDisk,
131 _MACFS.kTemporaryFolderType, 1)
132 dirname = _macfs.FSSpec((refnum, dirid, '')).as_pathname()
133 dirlist.append(dirname)
134 except _macfs.error:
135 pass
136 elif _os.name == 'riscos':
137 dirname = _os.getenv('Wimp$ScrapDir')
138 if dirname: dirlist.append(dirname)
139 elif _os.name == 'nt':
140 dirlist.extend([ r'c:\temp', r'c:\tmp', r'\temp', r'\tmp' ])
141 else:
142 dirlist.extend([ '/tmp', '/var/tmp', '/usr/tmp' ])
143
144 # As a last resort, the current directory.
145 try:
146 dirlist.append(_os.getcwd())
147 except (AttributeError, _os.error):
148 dirlist.append(_os.curdir)
149
150 return dirlist
Tim Petersa0d55de2002-08-09 18:01:01 +0000151
Guido van Rossum0e548712002-08-09 16:14:33 +0000152def _get_default_tempdir():
153 """Calculate the default directory to use for temporary files.
Guido van Rossume888cdc2002-08-17 14:50:24 +0000154 This routine should be called exactly once.
Guido van Rossum0e548712002-08-09 16:14:33 +0000155
156 We determine whether or not a candidate temp dir is usable by
157 trying to create and write to a file in that directory. If this
158 is successful, the test file is deleted. To prevent denial of
159 service, the name of the test file must be randomized."""
160
161 namer = _RandomNameSequence()
162 dirlist = _candidate_tempdir_list()
163 flags = _text_openflags
164
165 for dir in dirlist:
166 if dir != _os.curdir:
167 dir = _os.path.normcase(_os.path.abspath(dir))
168 # Try only a few names per directory.
169 for seq in xrange(100):
170 name = namer.next()
171 filename = _os.path.join(dir, name)
172 try:
173 fd = _os.open(filename, flags, 0600)
174 fp = _os.fdopen(fd, 'w')
Tim Petersb90f89a2001-01-15 03:26:36 +0000175 fp.write('blat')
176 fp.close()
Guido van Rossum0e548712002-08-09 16:14:33 +0000177 _os.unlink(filename)
178 del fp, fd
179 return dir
180 except (OSError, IOError), e:
181 if e[0] != _errno.EEXIST:
182 break # no point trying more names in this directory
183 pass
184 raise IOError, (_errno.ENOENT,
185 ("No usable temporary directory found in %s" % dirlist))
186
Guido van Rossume888cdc2002-08-17 14:50:24 +0000187_name_sequence = None
188
Guido van Rossum0e548712002-08-09 16:14:33 +0000189def _get_candidate_names():
190 """Common setup sequence for all user-callable interfaces."""
191
Guido van Rossume888cdc2002-08-17 14:50:24 +0000192 global _name_sequence
193 if _name_sequence is None:
194 _once_lock.acquire()
195 try:
196 if _name_sequence is None:
197 _name_sequence = _RandomNameSequence()
198 finally:
199 _once_lock.release()
Guido van Rossum0e548712002-08-09 16:14:33 +0000200 return _name_sequence
Guido van Rossum41f95031992-03-31 19:02:01 +0000201
202
Guido van Rossum0e548712002-08-09 16:14:33 +0000203def _mkstemp_inner(dir, pre, suf, flags):
204 """Code common to mkstemp, TemporaryFile, and NamedTemporaryFile."""
Tim Peters9fadfb02001-01-13 03:04:02 +0000205
Guido van Rossum0e548712002-08-09 16:14:33 +0000206 names = _get_candidate_names()
207
208 for seq in xrange(TMP_MAX):
209 name = names.next()
210 file = _os.path.join(dir, pre + name + suf)
211 try:
212 fd = _os.open(file, flags, 0600)
213 _set_cloexec(fd)
214 return (fd, file)
215 except OSError, e:
216 if e.errno == _errno.EEXIST:
217 continue # try again
218 raise
219
220 raise IOError, (_errno.EEXIST, "No usable temporary file name found")
Tim Petersa0d55de2002-08-09 18:01:01 +0000221
Guido van Rossum0e548712002-08-09 16:14:33 +0000222
223# User visible interfaces.
Guido van Rossumb0e57181998-10-14 20:27:05 +0000224
Guido van Rossum41f95031992-03-31 19:02:01 +0000225def gettempprefix():
Guido van Rossum0e548712002-08-09 16:14:33 +0000226 """Accessor for tempdir.template."""
227 return template
Tim Peters9fadfb02001-01-13 03:04:02 +0000228
Guido van Rossume888cdc2002-08-17 14:50:24 +0000229tempdir = None
230
Guido van Rossum0e548712002-08-09 16:14:33 +0000231def gettempdir():
232 """Accessor for tempdir.tempdir."""
Guido van Rossume888cdc2002-08-17 14:50:24 +0000233 global tempdir
234 if tempdir is None:
235 _once_lock.acquire()
236 try:
237 if tempdir is None:
238 tempdir = _get_default_tempdir()
239 finally:
240 _once_lock.release()
Guido van Rossum0e548712002-08-09 16:14:33 +0000241 return tempdir
242
Guido van Rossume888cdc2002-08-17 14:50:24 +0000243def mkstemp(suffix="", prefix=template, dir=None, text=False):
Tim Peters04490bf2002-08-14 15:41:26 +0000244 """mkstemp([suffix, [prefix, [dir, [text]]]])
Guido van Rossum0e548712002-08-09 16:14:33 +0000245 User-callable function to create and return a unique temporary
246 file. The return value is a pair (fd, name) where fd is the
247 file descriptor returned by os.open, and name is the filename.
248
249 If 'suffix' is specified, the file name will end with that suffix,
250 otherwise there will be no suffix.
251
252 If 'prefix' is specified, the file name will begin with that prefix,
253 otherwise a default prefix is used.
254
255 If 'dir' is specified, the file will be created in that directory,
256 otherwise a default directory is used.
257
Tim Peters04490bf2002-08-14 15:41:26 +0000258 If 'text' is specified and true, the file is opened in text
259 mode. Else (the default) the file is opened in binary mode. On
260 some operating systems, this makes no difference.
Guido van Rossum0e548712002-08-09 16:14:33 +0000261
262 The file is readable and writable only by the creating user ID.
263 If the operating system uses permission bits to indicate whether a
264 file is executable, the file is executable by no one. The file
265 descriptor is not inherited by children of this process.
266
267 Caller is responsible for deleting the file when done with it.
Tim Peters9fadfb02001-01-13 03:04:02 +0000268 """
269
Guido van Rossume888cdc2002-08-17 14:50:24 +0000270 if dir is None:
271 dir = gettempdir()
272
Tim Peters04490bf2002-08-14 15:41:26 +0000273 if text:
Guido van Rossum0e548712002-08-09 16:14:33 +0000274 flags = _text_openflags
Tim Peters04490bf2002-08-14 15:41:26 +0000275 else:
276 flags = _bin_openflags
Guido van Rossum0e548712002-08-09 16:14:33 +0000277
278 return _mkstemp_inner(dir, prefix, suffix, flags)
Guido van Rossumcff34541992-01-14 18:31:56 +0000279
Guido van Rossumeee94981991-11-12 15:38:08 +0000280
Guido van Rossume888cdc2002-08-17 14:50:24 +0000281def mkdtemp(suffix="", prefix=template, dir=None):
Guido van Rossum0e548712002-08-09 16:14:33 +0000282 """mkdtemp([suffix, [prefix, [dir]]])
283 User-callable function to create and return a unique temporary
284 directory. The return value is the pathname of the directory.
285
Tim Peters04490bf2002-08-14 15:41:26 +0000286 Arguments are as for mkstemp, except that the 'text' argument is
Guido van Rossum0e548712002-08-09 16:14:33 +0000287 not accepted.
288
289 The directory is readable, writable, and searchable only by the
290 creating user.
291
292 Caller is responsible for deleting the directory when done with it.
293 """
294
Guido van Rossume888cdc2002-08-17 14:50:24 +0000295 if dir is None:
296 dir = gettempdir()
297
Guido van Rossum0e548712002-08-09 16:14:33 +0000298 names = _get_candidate_names()
Tim Petersa0d55de2002-08-09 18:01:01 +0000299
Guido van Rossum0e548712002-08-09 16:14:33 +0000300 for seq in xrange(TMP_MAX):
301 name = names.next()
302 file = _os.path.join(dir, prefix + name + suffix)
303 try:
304 _os.mkdir(file, 0700)
305 return file
306 except OSError, e:
307 if e.errno == _errno.EEXIST:
308 continue # try again
309 raise
310
311 raise IOError, (_errno.EEXIST, "No usable temporary directory name found")
312
Guido van Rossume888cdc2002-08-17 14:50:24 +0000313def mktemp(suffix="", prefix=template, dir=None):
Guido van Rossum0e548712002-08-09 16:14:33 +0000314 """mktemp([suffix, [prefix, [dir]]])
315 User-callable function to return a unique temporary file name. The
316 file is not created.
317
Tim Peters04490bf2002-08-14 15:41:26 +0000318 Arguments are as for mkstemp, except that the 'text' argument is
Guido van Rossum0e548712002-08-09 16:14:33 +0000319 not accepted.
320
321 This function is unsafe and should not be used. The file name
322 refers to a file that did not exist at some point, but by the time
323 you get around to creating it, someone else may have beaten you to
324 the punch.
325 """
326
327 from warnings import warn as _warn
328 _warn("mktemp is a potential security risk to your program",
329 RuntimeWarning, stacklevel=2)
330
Guido van Rossume888cdc2002-08-17 14:50:24 +0000331 if dir is None:
332 dir = gettempdir()
333
Guido van Rossum0e548712002-08-09 16:14:33 +0000334 names = _get_candidate_names()
335 for seq in xrange(TMP_MAX):
336 name = names.next()
337 file = _os.path.join(dir, prefix + name + suffix)
338 if not _os.path.exists(file):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000339 return file
Guido van Rossumca549821997-08-12 18:00:12 +0000340
Guido van Rossum0e548712002-08-09 16:14:33 +0000341 raise IOError, (_errno.EEXIST, "No usable temporary filename found")
Guido van Rossumca549821997-08-12 18:00:12 +0000342
Guido van Rossum0e548712002-08-09 16:14:33 +0000343class _TemporaryFileWrapper:
Guido van Rossumca549821997-08-12 18:00:12 +0000344 """Temporary file wrapper
345
Guido van Rossum0e548712002-08-09 16:14:33 +0000346 This class provides a wrapper around files opened for
347 temporary use. In particular, it seeks to automatically
348 remove the file when it is no longer needed.
Guido van Rossumca549821997-08-12 18:00:12 +0000349 """
Tim Petersa255a722001-12-18 22:32:40 +0000350
Guido van Rossum0e548712002-08-09 16:14:33 +0000351 def __init__(self, file, name):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000352 self.file = file
Guido van Rossum0e548712002-08-09 16:14:33 +0000353 self.name = name
Tim Peters6ef966e2002-11-21 15:48:33 +0000354 self.close_called = False
Guido van Rossumca549821997-08-12 18:00:12 +0000355
Guido van Rossumca549821997-08-12 18:00:12 +0000356 def __getattr__(self, name):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000357 file = self.__dict__['file']
358 a = getattr(file, name)
Guido van Rossum6b708d51999-06-01 18:55:36 +0000359 if type(a) != type(0):
360 setattr(self, name, a)
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000361 return a
Guido van Rossumca549821997-08-12 18:00:12 +0000362
Guido van Rossum0e548712002-08-09 16:14:33 +0000363 # NT provides delete-on-close as a primitive, so we don't need
364 # the wrapper to do anything special. We still use it so that
365 # file.name is useful (i.e. not "(fdopen)") with NamedTemporaryFile.
366 if _os.name != 'nt':
Guido van Rossumca549821997-08-12 18:00:12 +0000367
Guido van Rossum0e548712002-08-09 16:14:33 +0000368 # Cache the unlinker so we don't get spurious errors at
369 # shutdown when the module-level "os" is None'd out. Note
370 # that this must be referenced as self.unlink, because the
371 # name TemporaryFileWrapper may also get None'd out before
372 # __del__ is called.
373 unlink = _os.unlink
Tim Peters1baa22a2001-01-12 10:02:46 +0000374
Guido van Rossum0e548712002-08-09 16:14:33 +0000375 def close(self):
376 if not self.close_called:
Tim Peters6ef966e2002-11-21 15:48:33 +0000377 self.close_called = True
Guido van Rossum0e548712002-08-09 16:14:33 +0000378 self.file.close()
379 self.unlink(self.name)
Tim Peters1baa22a2001-01-12 10:02:46 +0000380
Guido van Rossum0e548712002-08-09 16:14:33 +0000381 def __del__(self):
382 self.close()
Tim Peters1baa22a2001-01-12 10:02:46 +0000383
Guido van Rossum0e548712002-08-09 16:14:33 +0000384def NamedTemporaryFile(mode='w+b', bufsize=-1, suffix="",
Guido van Rossume888cdc2002-08-17 14:50:24 +0000385 prefix=template, dir=None):
Guido van Rossum0e548712002-08-09 16:14:33 +0000386 """Create and return a temporary file.
387 Arguments:
388 'prefix', 'suffix', 'dir' -- as for mkstemp.
389 'mode' -- the mode argument to os.fdopen (default "w+b").
390 'bufsize' -- the buffer size argument to os.fdopen (default -1).
391 The file is created as mkstemp() would do it.
Tim Peters1baa22a2001-01-12 10:02:46 +0000392
Guido van Rossum0e548712002-08-09 16:14:33 +0000393 Returns a file object; the name of the file is accessible as
394 file.name. The file will be automatically deleted when it is
395 closed.
396 """
Tim Peters1baa22a2001-01-12 10:02:46 +0000397
Guido van Rossume888cdc2002-08-17 14:50:24 +0000398 if dir is None:
399 dir = gettempdir()
400
Tim Petersc21ea742002-08-13 23:36:01 +0000401 if 'b' in mode:
402 flags = _bin_openflags
403 else:
404 flags = _text_openflags
Tim Peters1baa22a2001-01-12 10:02:46 +0000405
Guido van Rossum0e548712002-08-09 16:14:33 +0000406 # Setting O_TEMPORARY in the flags causes the OS to delete
407 # the file when it is closed. This is only supported by Windows.
408 if _os.name == 'nt':
409 flags |= _os.O_TEMPORARY
Tim Peters1baa22a2001-01-12 10:02:46 +0000410
Guido van Rossum0e548712002-08-09 16:14:33 +0000411 (fd, name) = _mkstemp_inner(dir, prefix, suffix, flags)
412 file = _os.fdopen(fd, mode, bufsize)
413 return _TemporaryFileWrapper(file, name)
414
Jason Tishler80c02af2002-08-14 15:10:09 +0000415if _os.name != 'posix' or _os.sys.platform == 'cygwin':
416 # On non-POSIX and Cygwin systems, assume that we cannot unlink a file
417 # while it is open.
Guido van Rossum0e548712002-08-09 16:14:33 +0000418 TemporaryFile = NamedTemporaryFile
Tim Peters1baa22a2001-01-12 10:02:46 +0000419
420else:
Guido van Rossum0e548712002-08-09 16:14:33 +0000421 def TemporaryFile(mode='w+b', bufsize=-1, suffix="",
Guido van Rossume888cdc2002-08-17 14:50:24 +0000422 prefix=template, dir=None):
Guido van Rossum0e548712002-08-09 16:14:33 +0000423 """Create and return a temporary file.
424 Arguments:
425 'prefix', 'suffix', 'directory' -- as for mkstemp.
426 'mode' -- the mode argument to os.fdopen (default "w+b").
427 'bufsize' -- the buffer size argument to os.fdopen (default -1).
428 The file is created as mkstemp() would do it.
Tim Peters1baa22a2001-01-12 10:02:46 +0000429
Guido van Rossum0e548712002-08-09 16:14:33 +0000430 Returns a file object. The file has no name, and will cease to
431 exist when it is closed.
432 """
433
Guido van Rossume888cdc2002-08-17 14:50:24 +0000434 if dir is None:
435 dir = gettempdir()
436
Tim Petersc21ea742002-08-13 23:36:01 +0000437 if 'b' in mode:
438 flags = _bin_openflags
439 else:
440 flags = _text_openflags
Guido van Rossum0e548712002-08-09 16:14:33 +0000441
442 (fd, name) = _mkstemp_inner(dir, prefix, suffix, flags)
443 try:
444 _os.unlink(name)
445 return _os.fdopen(fd, mode, bufsize)
446 except:
447 _os.close(fd)
448 raise