blob: ed107f4ea88d8fde707318b78d472bb04be09221 [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.
Guido van Rossum0e548712002-08-09 16:14:33 +000013 tempdir - If this is set to a string before the first use of
14 any routine from this module, it will be considered as
15 another candidate location to store temporary files.
16"""
Skip Montanaro40fc1602001-03-01 04:27:19 +000017
Guido van Rossum0e548712002-08-09 16:14:33 +000018__all__ = [
19 "NamedTemporaryFile", "TemporaryFile", # high level safe interfaces
Nick Coghlan543af752010-10-24 11:23:25 +000020 "SpooledTemporaryFile", "TemporaryDirectory",
Guido van Rossum0e548712002-08-09 16:14:33 +000021 "mkstemp", "mkdtemp", # low level safe interfaces
22 "mktemp", # deprecated unsafe interface
23 "TMP_MAX", "gettempprefix", # constants
24 "tempdir", "gettempdir"
25 ]
Guido van Rossum41f95031992-03-31 19:02:01 +000026
Tim Peters4fd5a062002-01-28 23:11:23 +000027
Guido van Rossum0e548712002-08-09 16:14:33 +000028# Imports.
Tim Peters4fd5a062002-01-28 23:11:23 +000029
Nick Coghlan6b22f3f2010-12-12 15:24:21 +000030import warnings as _warnings
31import sys as _sys
Guido van Rossum9a634702007-07-09 10:24:45 +000032import io as _io
Guido van Rossum0e548712002-08-09 16:14:33 +000033import os as _os
Guido van Rossum0e548712002-08-09 16:14:33 +000034from random import Random as _Random
35
Guido van Rossumd8faa362007-04-27 19:54:29 +000036try:
Guido van Rossum0e548712002-08-09 16:14:33 +000037 import fcntl as _fcntl
Tim Peters90ee7eb2004-07-18 23:58:17 +000038except ImportError:
Tim Peters291f14e2003-07-22 02:50:01 +000039 def _set_cloexec(fd):
40 pass
41else:
Guido van Rossum0e548712002-08-09 16:14:33 +000042 def _set_cloexec(fd):
Tim Peters90ee7eb2004-07-18 23:58:17 +000043 try:
44 flags = _fcntl.fcntl(fd, _fcntl.F_GETFD, 0)
Florent Xicluna68f71a32011-10-28 16:06:23 +020045 except OSError:
Tim Peters90ee7eb2004-07-18 23:58:17 +000046 pass
Alex Martellif09994e2003-11-09 16:44:09 +000047 else:
Guido van Rossum0e548712002-08-09 16:14:33 +000048 # flags read successfully, modify
49 flags |= _fcntl.FD_CLOEXEC
50 _fcntl.fcntl(fd, _fcntl.F_SETFD, flags)
Tim Peters291f14e2003-07-22 02:50:01 +000051
Guido van Rossum0e548712002-08-09 16:14:33 +000052
53try:
Georg Brandl2067bfd2008-05-25 13:05:15 +000054 import _thread
Guido van Rossuma0934242002-12-30 22:36:09 +000055except ImportError:
Georg Brandl2067bfd2008-05-25 13:05:15 +000056 import _dummy_thread as _thread
Guido van Rossuma0934242002-12-30 22:36:09 +000057_allocate_lock = _thread.allocate_lock
Guido van Rossum0e548712002-08-09 16:14:33 +000058
59_text_openflags = _os.O_RDWR | _os.O_CREAT | _os.O_EXCL
Tim Petersa0d55de2002-08-09 18:01:01 +000060if hasattr(_os, 'O_NOINHERIT'):
61 _text_openflags |= _os.O_NOINHERIT
62if hasattr(_os, 'O_NOFOLLOW'):
63 _text_openflags |= _os.O_NOFOLLOW
Guido van Rossum0e548712002-08-09 16:14:33 +000064
65_bin_openflags = _text_openflags
Tim Petersa0d55de2002-08-09 18:01:01 +000066if hasattr(_os, 'O_BINARY'):
67 _bin_openflags |= _os.O_BINARY
Guido van Rossum0e548712002-08-09 16:14:33 +000068
69if hasattr(_os, 'TMP_MAX'):
70 TMP_MAX = _os.TMP_MAX
71else:
72 TMP_MAX = 10000
73
R David Murray3a420c72011-06-22 21:01:13 -040074# Although it does not have an underscore for historical reasons, this
75# variable is an internal implementation detail (see issue 10354).
Tim Petersbd7b4c72002-08-13 23:33:56 +000076template = "tmp"
Guido van Rossum0e548712002-08-09 16:14:33 +000077
Guido van Rossum0e548712002-08-09 16:14:33 +000078# Internal routines.
79
80_once_lock = _allocate_lock()
81
Guido van Rossumb256159392003-11-10 02:16:36 +000082if hasattr(_os, "lstat"):
83 _stat = _os.lstat
84elif hasattr(_os, "stat"):
85 _stat = _os.stat
86else:
Florent Xicluna68f71a32011-10-28 16:06:23 +020087 # Fallback. All we need is something that raises OSError if the
Guido van Rossumb256159392003-11-10 02:16:36 +000088 # file doesn't exist.
89 def _stat(fn):
90 try:
91 f = open(fn)
Florent Xicluna68f71a32011-10-28 16:06:23 +020092 except OSError:
93 raise OSError
Guido van Rossumb256159392003-11-10 02:16:36 +000094 f.close()
95
96def _exists(fn):
97 try:
98 _stat(fn)
Florent Xicluna68f71a32011-10-28 16:06:23 +020099 except OSError:
Guido van Rossumb256159392003-11-10 02:16:36 +0000100 return False
101 else:
102 return True
103
Guido van Rossum0e548712002-08-09 16:14:33 +0000104class _RandomNameSequence:
105 """An instance of _RandomNameSequence generates an endless
106 sequence of unpredictable strings which can safely be incorporated
107 into file names. Each string is six characters long. Multiple
108 threads can safely use the same instance at the same time.
109
110 _RandomNameSequence is an iterator."""
111
Raymond Hettinger572895b2010-11-09 03:43:58 +0000112 characters = "abcdefghijklmnopqrstuvwxyz0123456789_"
Guido van Rossum0e548712002-08-09 16:14:33 +0000113
114 def __init__(self):
Guido van Rossum0e548712002-08-09 16:14:33 +0000115 self.rng = _Random()
Tim Peters97701b52002-11-21 15:59:59 +0000116
Guido van Rossum0e548712002-08-09 16:14:33 +0000117 def __iter__(self):
118 return self
119
Georg Brandla18af4e2007-04-21 15:47:16 +0000120 def __next__(self):
Guido van Rossum0e548712002-08-09 16:14:33 +0000121 c = self.characters
Tim Peters97701b52002-11-21 15:59:59 +0000122 choose = self.rng.choice
Raymond Hettinger572895b2010-11-09 03:43:58 +0000123 letters = [choose(c) for dummy in "123456"]
124 return ''.join(letters)
Guido van Rossum0e548712002-08-09 16:14:33 +0000125
126def _candidate_tempdir_list():
127 """Generate a list of candidate temporary directories which
128 _get_default_tempdir will try."""
129
130 dirlist = []
131
132 # First, try the environment.
133 for envname in 'TMPDIR', 'TEMP', 'TMP':
134 dirname = _os.getenv(envname)
135 if dirname: dirlist.append(dirname)
136
137 # Failing that, try OS-specific locations.
Alexandre Vassalottieca20b62008-05-16 02:54:33 +0000138 if _os.name == 'nt':
Guido van Rossum0e548712002-08-09 16:14:33 +0000139 dirlist.extend([ r'c:\temp', r'c:\tmp', r'\temp', r'\tmp' ])
140 else:
141 dirlist.extend([ '/tmp', '/var/tmp', '/usr/tmp' ])
142
143 # As a last resort, the current directory.
144 try:
145 dirlist.append(_os.getcwd())
Florent Xicluna68f71a32011-10-28 16:06:23 +0200146 except (AttributeError, OSError):
Guido van Rossum0e548712002-08-09 16:14:33 +0000147 dirlist.append(_os.curdir)
148
149 return dirlist
Tim Petersa0d55de2002-08-09 18:01:01 +0000150
Guido van Rossum0e548712002-08-09 16:14:33 +0000151def _get_default_tempdir():
152 """Calculate the default directory to use for temporary files.
Guido van Rossume888cdc2002-08-17 14:50:24 +0000153 This routine should be called exactly once.
Guido van Rossum0e548712002-08-09 16:14:33 +0000154
155 We determine whether or not a candidate temp dir is usable by
156 trying to create and write to a file in that directory. If this
157 is successful, the test file is deleted. To prevent denial of
158 service, the name of the test file must be randomized."""
159
160 namer = _RandomNameSequence()
161 dirlist = _candidate_tempdir_list()
Guido van Rossum0e548712002-08-09 16:14:33 +0000162
163 for dir in dirlist:
164 if dir != _os.curdir:
165 dir = _os.path.normcase(_os.path.abspath(dir))
166 # Try only a few names per directory.
Guido van Rossum805365e2007-05-07 22:24:25 +0000167 for seq in range(100):
Georg Brandla18af4e2007-04-21 15:47:16 +0000168 name = next(namer)
Guido van Rossum0e548712002-08-09 16:14:33 +0000169 filename = _os.path.join(dir, name)
170 try:
Amaury Forgeot d'Arc7d0bddd2009-11-30 00:08:56 +0000171 fd = _os.open(filename, _bin_openflags, 0o600)
Guido van Rossum5424df22007-08-13 19:06:38 +0000172 fp = _io.open(fd, 'wb')
173 fp.write(b'blat')
Tim Petersb90f89a2001-01-15 03:26:36 +0000174 fp.close()
Guido van Rossum0e548712002-08-09 16:14:33 +0000175 _os.unlink(filename)
176 del fp, fd
177 return dir
Florent Xicluna68f71a32011-10-28 16:06:23 +0200178 except FileExistsError:
Guido van Rossum0e548712002-08-09 16:14:33 +0000179 pass
Florent Xicluna68f71a32011-10-28 16:06:23 +0200180 except OSError:
181 break # no point trying more names in this directory
182 raise FileNotFoundError("No usable temporary directory found in %s" % dirlist)
Guido van Rossum0e548712002-08-09 16:14:33 +0000183
Guido van Rossume888cdc2002-08-17 14:50:24 +0000184_name_sequence = None
185
Guido van Rossum0e548712002-08-09 16:14:33 +0000186def _get_candidate_names():
187 """Common setup sequence for all user-callable interfaces."""
188
Guido van Rossume888cdc2002-08-17 14:50:24 +0000189 global _name_sequence
190 if _name_sequence is None:
191 _once_lock.acquire()
192 try:
193 if _name_sequence is None:
194 _name_sequence = _RandomNameSequence()
195 finally:
196 _once_lock.release()
Guido van Rossum0e548712002-08-09 16:14:33 +0000197 return _name_sequence
Guido van Rossum41f95031992-03-31 19:02:01 +0000198
199
Guido van Rossum0e548712002-08-09 16:14:33 +0000200def _mkstemp_inner(dir, pre, suf, flags):
201 """Code common to mkstemp, TemporaryFile, and NamedTemporaryFile."""
Tim Peters9fadfb02001-01-13 03:04:02 +0000202
Guido van Rossum0e548712002-08-09 16:14:33 +0000203 names = _get_candidate_names()
204
Guido van Rossum805365e2007-05-07 22:24:25 +0000205 for seq in range(TMP_MAX):
Georg Brandla18af4e2007-04-21 15:47:16 +0000206 name = next(names)
Guido van Rossum0e548712002-08-09 16:14:33 +0000207 file = _os.path.join(dir, pre + name + suf)
208 try:
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000209 fd = _os.open(file, flags, 0o600)
Guido van Rossum0e548712002-08-09 16:14:33 +0000210 _set_cloexec(fd)
Martin v. Löwisd6625482003-10-12 17:37:01 +0000211 return (fd, _os.path.abspath(file))
Florent Xicluna68f71a32011-10-28 16:06:23 +0200212 except FileExistsError:
213 continue # try again
Guido van Rossum0e548712002-08-09 16:14:33 +0000214
Florent Xicluna68f71a32011-10-28 16:06:23 +0200215 raise FileExistsError("No usable temporary file name found")
Tim Petersa0d55de2002-08-09 18:01:01 +0000216
Guido van Rossum0e548712002-08-09 16:14:33 +0000217
218# User visible interfaces.
Guido van Rossumb0e57181998-10-14 20:27:05 +0000219
Guido van Rossum41f95031992-03-31 19:02:01 +0000220def gettempprefix():
Guido van Rossum0e548712002-08-09 16:14:33 +0000221 """Accessor for tempdir.template."""
222 return template
Tim Peters9fadfb02001-01-13 03:04:02 +0000223
Guido van Rossume888cdc2002-08-17 14:50:24 +0000224tempdir = None
225
Guido van Rossum0e548712002-08-09 16:14:33 +0000226def gettempdir():
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000227 """Accessor for tempfile.tempdir."""
Guido van Rossume888cdc2002-08-17 14:50:24 +0000228 global tempdir
229 if tempdir is None:
230 _once_lock.acquire()
231 try:
232 if tempdir is None:
233 tempdir = _get_default_tempdir()
234 finally:
235 _once_lock.release()
Guido van Rossum0e548712002-08-09 16:14:33 +0000236 return tempdir
237
Guido van Rossume888cdc2002-08-17 14:50:24 +0000238def mkstemp(suffix="", prefix=template, dir=None, text=False):
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000239 """User-callable function to create and return a unique temporary
Guido van Rossum0e548712002-08-09 16:14:33 +0000240 file. The return value is a pair (fd, name) where fd is the
241 file descriptor returned by os.open, and name is the filename.
242
243 If 'suffix' is specified, the file name will end with that suffix,
244 otherwise there will be no suffix.
245
246 If 'prefix' is specified, the file name will begin with that prefix,
247 otherwise a default prefix is used.
248
249 If 'dir' is specified, the file will be created in that directory,
250 otherwise a default directory is used.
251
Tim Peters04490bf2002-08-14 15:41:26 +0000252 If 'text' is specified and true, the file is opened in text
253 mode. Else (the default) the file is opened in binary mode. On
254 some operating systems, this makes no difference.
Guido van Rossum0e548712002-08-09 16:14:33 +0000255
256 The file is readable and writable only by the creating user ID.
257 If the operating system uses permission bits to indicate whether a
258 file is executable, the file is executable by no one. The file
259 descriptor is not inherited by children of this process.
260
261 Caller is responsible for deleting the file when done with it.
Tim Peters9fadfb02001-01-13 03:04:02 +0000262 """
263
Guido van Rossume888cdc2002-08-17 14:50:24 +0000264 if dir is None:
265 dir = gettempdir()
266
Tim Peters04490bf2002-08-14 15:41:26 +0000267 if text:
Guido van Rossum0e548712002-08-09 16:14:33 +0000268 flags = _text_openflags
Tim Peters04490bf2002-08-14 15:41:26 +0000269 else:
270 flags = _bin_openflags
Guido van Rossum0e548712002-08-09 16:14:33 +0000271
272 return _mkstemp_inner(dir, prefix, suffix, flags)
Guido van Rossumcff34541992-01-14 18:31:56 +0000273
Guido van Rossumeee94981991-11-12 15:38:08 +0000274
Guido van Rossume888cdc2002-08-17 14:50:24 +0000275def mkdtemp(suffix="", prefix=template, dir=None):
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000276 """User-callable function to create and return a unique temporary
Guido van Rossum0e548712002-08-09 16:14:33 +0000277 directory. The return value is the pathname of the directory.
278
Tim Peters04490bf2002-08-14 15:41:26 +0000279 Arguments are as for mkstemp, except that the 'text' argument is
Guido van Rossum0e548712002-08-09 16:14:33 +0000280 not accepted.
281
282 The directory is readable, writable, and searchable only by the
283 creating user.
284
285 Caller is responsible for deleting the directory when done with it.
286 """
287
Guido van Rossume888cdc2002-08-17 14:50:24 +0000288 if dir is None:
289 dir = gettempdir()
290
Guido van Rossum0e548712002-08-09 16:14:33 +0000291 names = _get_candidate_names()
Tim Petersa0d55de2002-08-09 18:01:01 +0000292
Guido van Rossum805365e2007-05-07 22:24:25 +0000293 for seq in range(TMP_MAX):
Georg Brandla18af4e2007-04-21 15:47:16 +0000294 name = next(names)
Guido van Rossum0e548712002-08-09 16:14:33 +0000295 file = _os.path.join(dir, prefix + name + suffix)
296 try:
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000297 _os.mkdir(file, 0o700)
Guido van Rossum0e548712002-08-09 16:14:33 +0000298 return file
Florent Xicluna68f71a32011-10-28 16:06:23 +0200299 except FileExistsError:
300 continue # try again
Guido van Rossum0e548712002-08-09 16:14:33 +0000301
Florent Xicluna68f71a32011-10-28 16:06:23 +0200302 raise FileExistsError("No usable temporary directory name found")
Guido van Rossum0e548712002-08-09 16:14:33 +0000303
Guido van Rossume888cdc2002-08-17 14:50:24 +0000304def mktemp(suffix="", prefix=template, dir=None):
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000305 """User-callable function to return a unique temporary file name. The
Guido van Rossum0e548712002-08-09 16:14:33 +0000306 file is not created.
307
Tim Peters04490bf2002-08-14 15:41:26 +0000308 Arguments are as for mkstemp, except that the 'text' argument is
Guido van Rossum0e548712002-08-09 16:14:33 +0000309 not accepted.
310
311 This function is unsafe and should not be used. The file name
312 refers to a file that did not exist at some point, but by the time
313 you get around to creating it, someone else may have beaten you to
314 the punch.
315 """
316
Guido van Rossum44f602d2002-11-22 15:56:29 +0000317## from warnings import warn as _warn
318## _warn("mktemp is a potential security risk to your program",
319## RuntimeWarning, stacklevel=2)
Guido van Rossum0e548712002-08-09 16:14:33 +0000320
Guido van Rossume888cdc2002-08-17 14:50:24 +0000321 if dir is None:
322 dir = gettempdir()
323
Guido van Rossum0e548712002-08-09 16:14:33 +0000324 names = _get_candidate_names()
Guido van Rossum805365e2007-05-07 22:24:25 +0000325 for seq in range(TMP_MAX):
Georg Brandla18af4e2007-04-21 15:47:16 +0000326 name = next(names)
Guido van Rossum0e548712002-08-09 16:14:33 +0000327 file = _os.path.join(dir, prefix + name + suffix)
Guido van Rossumb256159392003-11-10 02:16:36 +0000328 if not _exists(file):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000329 return file
Guido van Rossumca549821997-08-12 18:00:12 +0000330
Florent Xicluna68f71a32011-10-28 16:06:23 +0200331 raise FileExistsError("No usable temporary filename found")
Guido van Rossumca549821997-08-12 18:00:12 +0000332
Christian Heimes3ecfea712008-02-09 20:51:34 +0000333
Guido van Rossum0e548712002-08-09 16:14:33 +0000334class _TemporaryFileWrapper:
Guido van Rossumca549821997-08-12 18:00:12 +0000335 """Temporary file wrapper
336
Guido van Rossum0e548712002-08-09 16:14:33 +0000337 This class provides a wrapper around files opened for
338 temporary use. In particular, it seeks to automatically
339 remove the file when it is no longer needed.
Guido van Rossumca549821997-08-12 18:00:12 +0000340 """
Tim Petersa255a722001-12-18 22:32:40 +0000341
Guido van Rossumd8faa362007-04-27 19:54:29 +0000342 def __init__(self, file, name, delete=True):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000343 self.file = file
Guido van Rossum0e548712002-08-09 16:14:33 +0000344 self.name = name
Tim Peters6ef966e2002-11-21 15:48:33 +0000345 self.close_called = False
Guido van Rossumd8faa362007-04-27 19:54:29 +0000346 self.delete = delete
Guido van Rossumca549821997-08-12 18:00:12 +0000347
Guido van Rossumca549821997-08-12 18:00:12 +0000348 def __getattr__(self, name):
Christian Heimes3ecfea712008-02-09 20:51:34 +0000349 # Attribute lookups are delegated to the underlying file
350 # and cached for non-numeric results
351 # (i.e. methods are cached, closed and friends are not)
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000352 file = self.__dict__['file']
353 a = getattr(file, name)
Christian Heimes3ecfea712008-02-09 20:51:34 +0000354 if not isinstance(a, int):
Guido van Rossum6b708d51999-06-01 18:55:36 +0000355 setattr(self, name, a)
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000356 return a
Guido van Rossumca549821997-08-12 18:00:12 +0000357
Christian Heimes3ecfea712008-02-09 20:51:34 +0000358 # The underlying __enter__ method returns the wrong object
359 # (self.file) so override it to return the wrapper
360 def __enter__(self):
361 self.file.__enter__()
362 return self
363
Christian Heimes36d1f8e2008-02-28 22:21:11 +0000364 # iter() doesn't use __getattr__ to find the __iter__ method
Christian Heimesc83b6292008-02-28 21:10:17 +0000365 def __iter__(self):
Christian Heimes36d1f8e2008-02-28 22:21:11 +0000366 return iter(self.file)
Christian Heimesc83b6292008-02-28 21:10:17 +0000367
Guido van Rossum0e548712002-08-09 16:14:33 +0000368 # NT provides delete-on-close as a primitive, so we don't need
369 # the wrapper to do anything special. We still use it so that
370 # file.name is useful (i.e. not "(fdopen)") with NamedTemporaryFile.
371 if _os.name != 'nt':
Guido van Rossum0e548712002-08-09 16:14:33 +0000372 # Cache the unlinker so we don't get spurious errors at
373 # shutdown when the module-level "os" is None'd out. Note
374 # that this must be referenced as self.unlink, because the
375 # name TemporaryFileWrapper may also get None'd out before
376 # __del__ is called.
377 unlink = _os.unlink
Tim Peters1baa22a2001-01-12 10:02:46 +0000378
Guido van Rossum0e548712002-08-09 16:14:33 +0000379 def close(self):
380 if not self.close_called:
Tim Peters6ef966e2002-11-21 15:48:33 +0000381 self.close_called = True
Guido van Rossum0e548712002-08-09 16:14:33 +0000382 self.file.close()
Guido van Rossumd8faa362007-04-27 19:54:29 +0000383 if self.delete:
384 self.unlink(self.name)
Tim Peters1baa22a2001-01-12 10:02:46 +0000385
Guido van Rossum0e548712002-08-09 16:14:33 +0000386 def __del__(self):
387 self.close()
Tim Peters1baa22a2001-01-12 10:02:46 +0000388
Christian Heimes3ecfea712008-02-09 20:51:34 +0000389 # Need to trap __exit__ as well to ensure the file gets
390 # deleted when used in a with statement
391 def __exit__(self, exc, value, tb):
392 result = self.file.__exit__(exc, value, tb)
393 self.close()
394 return result
Benjamin Peterson98d23f22009-06-30 22:27:25 +0000395 else:
396 def __exit__(self, exc, value, tb):
Benjamin Peterson3f5de132009-07-01 15:47:07 +0000397 self.file.__exit__(exc, value, tb)
Christian Heimes3ecfea712008-02-09 20:51:34 +0000398
399
Guido van Rossumf0c74162007-08-28 03:29:45 +0000400def NamedTemporaryFile(mode='w+b', buffering=-1, encoding=None,
401 newline=None, suffix="", prefix=template,
402 dir=None, delete=True):
Guido van Rossum0e548712002-08-09 16:14:33 +0000403 """Create and return a temporary file.
404 Arguments:
405 'prefix', 'suffix', 'dir' -- as for mkstemp.
Guido van Rossumf0c74162007-08-28 03:29:45 +0000406 'mode' -- the mode argument to io.open (default "w+b").
407 'buffering' -- the buffer size argument to io.open (default -1).
408 'encoding' -- the encoding argument to io.open (default None)
409 'newline' -- the newline argument to io.open (default None)
Guido van Rossumd8faa362007-04-27 19:54:29 +0000410 'delete' -- whether the file is deleted on close (default True).
Guido van Rossum0e548712002-08-09 16:14:33 +0000411 The file is created as mkstemp() would do it.
Tim Peters1baa22a2001-01-12 10:02:46 +0000412
Raymond Hettingerfaa10eb2005-01-11 15:33:03 +0000413 Returns an object with a file-like interface; the name of the file
414 is accessible as file.name. The file will be automatically deleted
Guido van Rossumd8faa362007-04-27 19:54:29 +0000415 when it is closed unless the 'delete' argument is set to False.
Guido van Rossum0e548712002-08-09 16:14:33 +0000416 """
Tim Peters1baa22a2001-01-12 10:02:46 +0000417
Guido van Rossume888cdc2002-08-17 14:50:24 +0000418 if dir is None:
419 dir = gettempdir()
420
Amaury Forgeot d'Arc7d0bddd2009-11-30 00:08:56 +0000421 flags = _bin_openflags
Tim Peters1baa22a2001-01-12 10:02:46 +0000422
Guido van Rossum0e548712002-08-09 16:14:33 +0000423 # Setting O_TEMPORARY in the flags causes the OS to delete
424 # the file when it is closed. This is only supported by Windows.
Guido van Rossumd8faa362007-04-27 19:54:29 +0000425 if _os.name == 'nt' and delete:
Guido van Rossum0e548712002-08-09 16:14:33 +0000426 flags |= _os.O_TEMPORARY
Tim Peters1baa22a2001-01-12 10:02:46 +0000427
Guido van Rossum0e548712002-08-09 16:14:33 +0000428 (fd, name) = _mkstemp_inner(dir, prefix, suffix, flags)
Guido van Rossumf0c74162007-08-28 03:29:45 +0000429 file = _io.open(fd, mode, buffering=buffering,
430 newline=newline, encoding=encoding)
431
Guido van Rossumd8faa362007-04-27 19:54:29 +0000432 return _TemporaryFileWrapper(file, name, delete)
Guido van Rossum0e548712002-08-09 16:14:33 +0000433
Jason Tishler80c02af2002-08-14 15:10:09 +0000434if _os.name != 'posix' or _os.sys.platform == 'cygwin':
435 # On non-POSIX and Cygwin systems, assume that we cannot unlink a file
436 # while it is open.
Guido van Rossum0e548712002-08-09 16:14:33 +0000437 TemporaryFile = NamedTemporaryFile
Tim Peters1baa22a2001-01-12 10:02:46 +0000438
439else:
Guido van Rossumf0c74162007-08-28 03:29:45 +0000440 def TemporaryFile(mode='w+b', buffering=-1, encoding=None,
441 newline=None, suffix="", prefix=template,
442 dir=None):
Guido van Rossum0e548712002-08-09 16:14:33 +0000443 """Create and return a temporary file.
444 Arguments:
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000445 'prefix', 'suffix', 'dir' -- as for mkstemp.
Guido van Rossumf0c74162007-08-28 03:29:45 +0000446 'mode' -- the mode argument to io.open (default "w+b").
447 'buffering' -- the buffer size argument to io.open (default -1).
448 'encoding' -- the encoding argument to io.open (default None)
449 'newline' -- the newline argument to io.open (default None)
Guido van Rossum0e548712002-08-09 16:14:33 +0000450 The file is created as mkstemp() would do it.
Tim Peters1baa22a2001-01-12 10:02:46 +0000451
Raymond Hettingerfaa10eb2005-01-11 15:33:03 +0000452 Returns an object with a file-like interface. The file has no
453 name, and will cease to exist when it is closed.
Guido van Rossum0e548712002-08-09 16:14:33 +0000454 """
455
Guido van Rossume888cdc2002-08-17 14:50:24 +0000456 if dir is None:
457 dir = gettempdir()
458
Amaury Forgeot d'Arc7d0bddd2009-11-30 00:08:56 +0000459 flags = _bin_openflags
Guido van Rossum0e548712002-08-09 16:14:33 +0000460
461 (fd, name) = _mkstemp_inner(dir, prefix, suffix, flags)
462 try:
463 _os.unlink(name)
Guido van Rossumf0c74162007-08-28 03:29:45 +0000464 return _io.open(fd, mode, buffering=buffering,
465 newline=newline, encoding=encoding)
Guido van Rossum0e548712002-08-09 16:14:33 +0000466 except:
467 _os.close(fd)
468 raise
Guido van Rossumd8faa362007-04-27 19:54:29 +0000469
470class SpooledTemporaryFile:
471 """Temporary file wrapper, specialized to switch from
472 StringIO to a real file when it exceeds a certain size or
473 when a fileno is needed.
474 """
475 _rolled = False
476
Guido van Rossumf0c74162007-08-28 03:29:45 +0000477 def __init__(self, max_size=0, mode='w+b', buffering=-1,
478 encoding=None, newline=None,
Guido van Rossumd8faa362007-04-27 19:54:29 +0000479 suffix="", prefix=template, dir=None):
Guido van Rossum9a634702007-07-09 10:24:45 +0000480 if 'b' in mode:
481 self._file = _io.BytesIO()
482 else:
Guido van Rossum5d212552007-10-29 16:42:51 +0000483 # Setting newline="\n" avoids newline translation;
484 # this is important because otherwise on Windows we'd
Guido van Rossum98297ee2007-11-06 21:34:58 +0000485 # hget double newline translation upon rollover().
Alexandre Vassalotti3ade6f92008-06-12 01:13:54 +0000486 self._file = _io.StringIO(newline="\n")
Guido van Rossumd8faa362007-04-27 19:54:29 +0000487 self._max_size = max_size
488 self._rolled = False
Guido van Rossumf0c74162007-08-28 03:29:45 +0000489 self._TemporaryFileArgs = {'mode': mode, 'buffering': buffering,
490 'suffix': suffix, 'prefix': prefix,
491 'encoding': encoding, 'newline': newline,
492 'dir': dir}
Guido van Rossumd8faa362007-04-27 19:54:29 +0000493
494 def _check(self, file):
495 if self._rolled: return
496 max_size = self._max_size
497 if max_size and file.tell() > max_size:
498 self.rollover()
499
500 def rollover(self):
501 if self._rolled: return
502 file = self._file
Guido van Rossumf0c74162007-08-28 03:29:45 +0000503 newfile = self._file = TemporaryFile(**self._TemporaryFileArgs)
Guido van Rossumd8faa362007-04-27 19:54:29 +0000504 del self._TemporaryFileArgs
505
506 newfile.write(file.getvalue())
507 newfile.seek(file.tell(), 0)
508
509 self._rolled = True
510
Christian Heimes3ecfea712008-02-09 20:51:34 +0000511 # The method caching trick from NamedTemporaryFile
512 # won't work here, because _file may change from a
513 # _StringIO instance to a real file. So we list
514 # all the methods directly.
515
516 # Context management protocol
517 def __enter__(self):
518 if self._file.closed:
519 raise ValueError("Cannot enter context with closed file")
520 return self
521
522 def __exit__(self, exc, value, tb):
523 self._file.close()
524
Guido van Rossumd8faa362007-04-27 19:54:29 +0000525 # file protocol
526 def __iter__(self):
527 return self._file.__iter__()
528
529 def close(self):
530 self._file.close()
531
532 @property
533 def closed(self):
534 return self._file.closed
535
536 @property
537 def encoding(self):
538 return self._file.encoding
539
540 def fileno(self):
541 self.rollover()
542 return self._file.fileno()
543
544 def flush(self):
545 self._file.flush()
546
547 def isatty(self):
548 return self._file.isatty()
549
550 @property
551 def mode(self):
552 return self._file.mode
553
554 @property
555 def name(self):
556 return self._file.name
557
558 @property
559 def newlines(self):
560 return self._file.newlines
561
562 def next(self):
563 return self._file.next
564
565 def read(self, *args):
566 return self._file.read(*args)
567
568 def readline(self, *args):
569 return self._file.readline(*args)
570
571 def readlines(self, *args):
572 return self._file.readlines(*args)
573
574 def seek(self, *args):
575 self._file.seek(*args)
576
577 @property
578 def softspace(self):
579 return self._file.softspace
580
581 def tell(self):
582 return self._file.tell()
583
584 def truncate(self):
585 self._file.truncate()
586
587 def write(self, s):
588 file = self._file
589 rv = file.write(s)
590 self._check(file)
591 return rv
592
593 def writelines(self, iterable):
594 file = self._file
595 rv = file.writelines(iterable)
596 self._check(file)
597 return rv
598
599 def xreadlines(self, *args):
600 return self._file.xreadlines(*args)
Nick Coghlan543af752010-10-24 11:23:25 +0000601
602
603class TemporaryDirectory(object):
604 """Create and return a temporary directory. This has the same
605 behavior as mkdtemp but can be used as a context manager. For
606 example:
607
608 with TemporaryDirectory() as tmpdir:
609 ...
610
611 Upon exiting the context, the directory and everthing contained
612 in it are removed.
613 """
614
615 def __init__(self, suffix="", prefix=template, dir=None):
Nick Coghlan543af752010-10-24 11:23:25 +0000616 self._closed = False
Nick Coghlan6b22f3f2010-12-12 15:24:21 +0000617 self.name = None # Handle mkdtemp throwing an exception
618 self.name = mkdtemp(suffix, prefix, dir)
619
620 def __repr__(self):
621 return "<{} {!r}>".format(self.__class__.__name__, self.name)
Nick Coghlan543af752010-10-24 11:23:25 +0000622
623 def __enter__(self):
624 return self.name
625
Nick Coghlan6b22f3f2010-12-12 15:24:21 +0000626 def cleanup(self, _warn=False):
627 if self.name and not self._closed:
628 try:
629 self._rmtree(self.name)
630 except (TypeError, AttributeError) as ex:
631 # Issue #10188: Emit a warning on stderr
632 # if the directory could not be cleaned
633 # up due to missing globals
634 if "None" not in str(ex):
635 raise
636 print("ERROR: {!r} while cleaning up {!r}".format(ex, self,),
637 file=_sys.stderr)
638 return
Nick Coghlan543af752010-10-24 11:23:25 +0000639 self._closed = True
Nick Coghlan6b22f3f2010-12-12 15:24:21 +0000640 if _warn:
641 self._warn("Implicitly cleaning up {!r}".format(self),
642 ResourceWarning)
Nick Coghlan543af752010-10-24 11:23:25 +0000643
644 def __exit__(self, exc, value, tb):
645 self.cleanup()
646
Nick Coghlan6b22f3f2010-12-12 15:24:21 +0000647 def __del__(self):
648 # Issue a ResourceWarning if implicit cleanup needed
649 self.cleanup(_warn=True)
Nick Coghlan543af752010-10-24 11:23:25 +0000650
651 # XXX (ncoghlan): The following code attempts to make
652 # this class tolerant of the module nulling out process
653 # that happens during CPython interpreter shutdown
654 # Alas, it doesn't actually manage it. See issue #10188
655 _listdir = staticmethod(_os.listdir)
656 _path_join = staticmethod(_os.path.join)
657 _isdir = staticmethod(_os.path.isdir)
Charles-François Natalidef35432011-07-29 18:59:24 +0200658 _islink = staticmethod(_os.path.islink)
Nick Coghlan543af752010-10-24 11:23:25 +0000659 _remove = staticmethod(_os.remove)
660 _rmdir = staticmethod(_os.rmdir)
Florent Xicluna68f71a32011-10-28 16:06:23 +0200661 _os_error = OSError
Nick Coghlan6b22f3f2010-12-12 15:24:21 +0000662 _warn = _warnings.warn
Nick Coghlan543af752010-10-24 11:23:25 +0000663
664 def _rmtree(self, path):
665 # Essentially a stripped down version of shutil.rmtree. We can't
666 # use globals because they may be None'ed out at shutdown.
667 for name in self._listdir(path):
668 fullname = self._path_join(path, name)
669 try:
Charles-François Natalidef35432011-07-29 18:59:24 +0200670 isdir = self._isdir(fullname) and not self._islink(fullname)
Nick Coghlan543af752010-10-24 11:23:25 +0000671 except self._os_error:
672 isdir = False
673 if isdir:
674 self._rmtree(fullname)
675 else:
676 try:
677 self._remove(fullname)
678 except self._os_error:
679 pass
680 try:
681 self._rmdir(path)
682 except self._os_error:
683 pass