blob: 5d3462102f19443faa6f1bd39b111c5bf695ff32 [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
Serhiy Storchaka7451a722013-02-09 22:25:49 +020034import errno as _errno
Guido van Rossum0e548712002-08-09 16:14:33 +000035from random import Random as _Random
36
Guido van Rossumd8faa362007-04-27 19:54:29 +000037try:
Georg Brandl2067bfd2008-05-25 13:05:15 +000038 import _thread
Brett Cannoncd171c82013-07-04 17:43:24 -040039except ImportError:
Georg Brandl2067bfd2008-05-25 13:05:15 +000040 import _dummy_thread as _thread
Guido van Rossuma0934242002-12-30 22:36:09 +000041_allocate_lock = _thread.allocate_lock
Guido van Rossum0e548712002-08-09 16:14:33 +000042
43_text_openflags = _os.O_RDWR | _os.O_CREAT | _os.O_EXCL
Tim Petersa0d55de2002-08-09 18:01:01 +000044if hasattr(_os, 'O_NOFOLLOW'):
45 _text_openflags |= _os.O_NOFOLLOW
Guido van Rossum0e548712002-08-09 16:14:33 +000046
47_bin_openflags = _text_openflags
Tim Petersa0d55de2002-08-09 18:01:01 +000048if hasattr(_os, 'O_BINARY'):
49 _bin_openflags |= _os.O_BINARY
Guido van Rossum0e548712002-08-09 16:14:33 +000050
51if hasattr(_os, 'TMP_MAX'):
52 TMP_MAX = _os.TMP_MAX
53else:
54 TMP_MAX = 10000
55
R David Murray3a420c72011-06-22 21:01:13 -040056# Although it does not have an underscore for historical reasons, this
57# variable is an internal implementation detail (see issue 10354).
Tim Petersbd7b4c72002-08-13 23:33:56 +000058template = "tmp"
Guido van Rossum0e548712002-08-09 16:14:33 +000059
Guido van Rossum0e548712002-08-09 16:14:33 +000060# Internal routines.
61
62_once_lock = _allocate_lock()
63
Guido van Rossumb256159392003-11-10 02:16:36 +000064if hasattr(_os, "lstat"):
65 _stat = _os.lstat
66elif hasattr(_os, "stat"):
67 _stat = _os.stat
68else:
Florent Xicluna68f71a32011-10-28 16:06:23 +020069 # Fallback. All we need is something that raises OSError if the
Guido van Rossumb256159392003-11-10 02:16:36 +000070 # file doesn't exist.
71 def _stat(fn):
Victor Stinnerdaf45552013-08-28 00:53:59 +020072 fd = _os.open(fn, _os.O_RDONLY)
73 os.close(fd)
Guido van Rossumb256159392003-11-10 02:16:36 +000074
75def _exists(fn):
76 try:
77 _stat(fn)
Florent Xicluna68f71a32011-10-28 16:06:23 +020078 except OSError:
Guido van Rossumb256159392003-11-10 02:16:36 +000079 return False
80 else:
81 return True
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
Raymond Hettinger572895b2010-11-09 03:43:58 +000091 characters = "abcdefghijklmnopqrstuvwxyz0123456789_"
Guido van Rossum0e548712002-08-09 16:14:33 +000092
Antoine Pitrou4558bad2011-11-25 21:28:15 +010093 @property
94 def rng(self):
95 cur_pid = _os.getpid()
96 if cur_pid != getattr(self, '_rng_pid', None):
97 self._rng = _Random()
98 self._rng_pid = cur_pid
99 return self._rng
Tim Peters97701b52002-11-21 15:59:59 +0000100
Guido van Rossum0e548712002-08-09 16:14:33 +0000101 def __iter__(self):
102 return self
103
Georg Brandla18af4e2007-04-21 15:47:16 +0000104 def __next__(self):
Guido van Rossum0e548712002-08-09 16:14:33 +0000105 c = self.characters
Tim Peters97701b52002-11-21 15:59:59 +0000106 choose = self.rng.choice
Victor Stinner97869102013-08-14 01:28:28 +0200107 letters = [choose(c) for dummy in range(8)]
Raymond Hettinger572895b2010-11-09 03:43:58 +0000108 return ''.join(letters)
Guido van Rossum0e548712002-08-09 16:14:33 +0000109
110def _candidate_tempdir_list():
111 """Generate a list of candidate temporary directories which
112 _get_default_tempdir will try."""
113
114 dirlist = []
115
116 # First, try the environment.
117 for envname in 'TMPDIR', 'TEMP', 'TMP':
118 dirname = _os.getenv(envname)
119 if dirname: dirlist.append(dirname)
120
121 # Failing that, try OS-specific locations.
Alexandre Vassalottieca20b62008-05-16 02:54:33 +0000122 if _os.name == 'nt':
Guido van Rossum0e548712002-08-09 16:14:33 +0000123 dirlist.extend([ r'c:\temp', r'c:\tmp', r'\temp', r'\tmp' ])
124 else:
125 dirlist.extend([ '/tmp', '/var/tmp', '/usr/tmp' ])
126
127 # As a last resort, the current directory.
128 try:
129 dirlist.append(_os.getcwd())
Florent Xicluna68f71a32011-10-28 16:06:23 +0200130 except (AttributeError, OSError):
Guido van Rossum0e548712002-08-09 16:14:33 +0000131 dirlist.append(_os.curdir)
132
133 return dirlist
Tim Petersa0d55de2002-08-09 18:01:01 +0000134
Guido van Rossum0e548712002-08-09 16:14:33 +0000135def _get_default_tempdir():
136 """Calculate the default directory to use for temporary files.
Guido van Rossume888cdc2002-08-17 14:50:24 +0000137 This routine should be called exactly once.
Guido van Rossum0e548712002-08-09 16:14:33 +0000138
139 We determine whether or not a candidate temp dir is usable by
140 trying to create and write to a file in that directory. If this
141 is successful, the test file is deleted. To prevent denial of
142 service, the name of the test file must be randomized."""
143
144 namer = _RandomNameSequence()
145 dirlist = _candidate_tempdir_list()
Guido van Rossum0e548712002-08-09 16:14:33 +0000146
147 for dir in dirlist:
148 if dir != _os.curdir:
Tim Golden6d09f092013-10-25 18:38:16 +0100149 dir = _os.path.abspath(dir)
Guido van Rossum0e548712002-08-09 16:14:33 +0000150 # Try only a few names per directory.
Guido van Rossum805365e2007-05-07 22:24:25 +0000151 for seq in range(100):
Georg Brandla18af4e2007-04-21 15:47:16 +0000152 name = next(namer)
Guido van Rossum0e548712002-08-09 16:14:33 +0000153 filename = _os.path.join(dir, name)
154 try:
Amaury Forgeot d'Arc7d0bddd2009-11-30 00:08:56 +0000155 fd = _os.open(filename, _bin_openflags, 0o600)
Serhiy Storchakaf6b361e2013-02-13 00:35:30 +0200156 try:
157 try:
Serhiy Storchaka76a2ed12013-02-13 00:59:26 +0200158 with _io.open(fd, 'wb', closefd=False) as fp:
159 fp.write(b'blat')
Serhiy Storchakaf6b361e2013-02-13 00:35:30 +0200160 finally:
161 _os.close(fd)
162 finally:
163 _os.unlink(filename)
Guido van Rossum0e548712002-08-09 16:14:33 +0000164 return dir
Florent Xicluna68f71a32011-10-28 16:06:23 +0200165 except FileExistsError:
Guido van Rossum0e548712002-08-09 16:14:33 +0000166 pass
Florent Xicluna68f71a32011-10-28 16:06:23 +0200167 except OSError:
168 break # no point trying more names in this directory
Serhiy Storchaka7451a722013-02-09 22:25:49 +0200169 raise FileNotFoundError(_errno.ENOENT,
170 "No usable temporary directory found in %s" %
171 dirlist)
Guido van Rossum0e548712002-08-09 16:14:33 +0000172
Guido van Rossume888cdc2002-08-17 14:50:24 +0000173_name_sequence = None
174
Guido van Rossum0e548712002-08-09 16:14:33 +0000175def _get_candidate_names():
176 """Common setup sequence for all user-callable interfaces."""
177
Guido van Rossume888cdc2002-08-17 14:50:24 +0000178 global _name_sequence
179 if _name_sequence is None:
180 _once_lock.acquire()
181 try:
182 if _name_sequence is None:
183 _name_sequence = _RandomNameSequence()
184 finally:
185 _once_lock.release()
Guido van Rossum0e548712002-08-09 16:14:33 +0000186 return _name_sequence
Guido van Rossum41f95031992-03-31 19:02:01 +0000187
188
Guido van Rossum0e548712002-08-09 16:14:33 +0000189def _mkstemp_inner(dir, pre, suf, flags):
190 """Code common to mkstemp, TemporaryFile, and NamedTemporaryFile."""
Tim Peters9fadfb02001-01-13 03:04:02 +0000191
Guido van Rossum0e548712002-08-09 16:14:33 +0000192 names = _get_candidate_names()
193
Guido van Rossum805365e2007-05-07 22:24:25 +0000194 for seq in range(TMP_MAX):
Georg Brandla18af4e2007-04-21 15:47:16 +0000195 name = next(names)
Guido van Rossum0e548712002-08-09 16:14:33 +0000196 file = _os.path.join(dir, pre + name + suf)
197 try:
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000198 fd = _os.open(file, flags, 0o600)
Martin v. Löwisd6625482003-10-12 17:37:01 +0000199 return (fd, _os.path.abspath(file))
Florent Xicluna68f71a32011-10-28 16:06:23 +0200200 except FileExistsError:
201 continue # try again
Eli Benderskyf315df32013-09-06 06:11:19 -0700202 except PermissionError:
203 # This exception is thrown when a directory with the chosen name
204 # already exists on windows.
205 if _os.name == 'nt':
206 continue
207 else:
208 raise
Guido van Rossum0e548712002-08-09 16:14:33 +0000209
Serhiy Storchaka7451a722013-02-09 22:25:49 +0200210 raise FileExistsError(_errno.EEXIST,
211 "No usable temporary file name found")
Tim Petersa0d55de2002-08-09 18:01:01 +0000212
Guido van Rossum0e548712002-08-09 16:14:33 +0000213
214# User visible interfaces.
Guido van Rossumb0e57181998-10-14 20:27:05 +0000215
Guido van Rossum41f95031992-03-31 19:02:01 +0000216def gettempprefix():
Guido van Rossum0e548712002-08-09 16:14:33 +0000217 """Accessor for tempdir.template."""
218 return template
Tim Peters9fadfb02001-01-13 03:04:02 +0000219
Guido van Rossume888cdc2002-08-17 14:50:24 +0000220tempdir = None
221
Guido van Rossum0e548712002-08-09 16:14:33 +0000222def gettempdir():
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000223 """Accessor for tempfile.tempdir."""
Guido van Rossume888cdc2002-08-17 14:50:24 +0000224 global tempdir
225 if tempdir is None:
226 _once_lock.acquire()
227 try:
228 if tempdir is None:
229 tempdir = _get_default_tempdir()
230 finally:
231 _once_lock.release()
Guido van Rossum0e548712002-08-09 16:14:33 +0000232 return tempdir
233
Guido van Rossume888cdc2002-08-17 14:50:24 +0000234def mkstemp(suffix="", prefix=template, dir=None, text=False):
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000235 """User-callable function to create and return a unique temporary
Guido van Rossum0e548712002-08-09 16:14:33 +0000236 file. The return value is a pair (fd, name) where fd is the
237 file descriptor returned by os.open, and name is the filename.
238
239 If 'suffix' is specified, the file name will end with that suffix,
240 otherwise there will be no suffix.
241
242 If 'prefix' is specified, the file name will begin with that prefix,
243 otherwise a default prefix is used.
244
245 If 'dir' is specified, the file will be created in that directory,
246 otherwise a default directory is used.
247
Tim Peters04490bf2002-08-14 15:41:26 +0000248 If 'text' is specified and true, the file is opened in text
249 mode. Else (the default) the file is opened in binary mode. On
250 some operating systems, this makes no difference.
Guido van Rossum0e548712002-08-09 16:14:33 +0000251
252 The file is readable and writable only by the creating user ID.
253 If the operating system uses permission bits to indicate whether a
254 file is executable, the file is executable by no one. The file
255 descriptor is not inherited by children of this process.
256
257 Caller is responsible for deleting the file when done with it.
Tim Peters9fadfb02001-01-13 03:04:02 +0000258 """
259
Guido van Rossume888cdc2002-08-17 14:50:24 +0000260 if dir is None:
261 dir = gettempdir()
262
Tim Peters04490bf2002-08-14 15:41:26 +0000263 if text:
Guido van Rossum0e548712002-08-09 16:14:33 +0000264 flags = _text_openflags
Tim Peters04490bf2002-08-14 15:41:26 +0000265 else:
266 flags = _bin_openflags
Guido van Rossum0e548712002-08-09 16:14:33 +0000267
268 return _mkstemp_inner(dir, prefix, suffix, flags)
Guido van Rossumcff34541992-01-14 18:31:56 +0000269
Guido van Rossumeee94981991-11-12 15:38:08 +0000270
Guido van Rossume888cdc2002-08-17 14:50:24 +0000271def mkdtemp(suffix="", prefix=template, dir=None):
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000272 """User-callable function to create and return a unique temporary
Guido van Rossum0e548712002-08-09 16:14:33 +0000273 directory. The return value is the pathname of the directory.
274
Tim Peters04490bf2002-08-14 15:41:26 +0000275 Arguments are as for mkstemp, except that the 'text' argument is
Guido van Rossum0e548712002-08-09 16:14:33 +0000276 not accepted.
277
278 The directory is readable, writable, and searchable only by the
279 creating user.
280
281 Caller is responsible for deleting the directory when done with it.
282 """
283
Guido van Rossume888cdc2002-08-17 14:50:24 +0000284 if dir is None:
285 dir = gettempdir()
286
Guido van Rossum0e548712002-08-09 16:14:33 +0000287 names = _get_candidate_names()
Tim Petersa0d55de2002-08-09 18:01:01 +0000288
Guido van Rossum805365e2007-05-07 22:24:25 +0000289 for seq in range(TMP_MAX):
Georg Brandla18af4e2007-04-21 15:47:16 +0000290 name = next(names)
Guido van Rossum0e548712002-08-09 16:14:33 +0000291 file = _os.path.join(dir, prefix + name + suffix)
292 try:
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000293 _os.mkdir(file, 0o700)
Guido van Rossum0e548712002-08-09 16:14:33 +0000294 return file
Florent Xicluna68f71a32011-10-28 16:06:23 +0200295 except FileExistsError:
296 continue # try again
Guido van Rossum0e548712002-08-09 16:14:33 +0000297
Serhiy Storchaka7451a722013-02-09 22:25:49 +0200298 raise FileExistsError(_errno.EEXIST,
299 "No usable temporary directory name found")
Guido van Rossum0e548712002-08-09 16:14:33 +0000300
Guido van Rossume888cdc2002-08-17 14:50:24 +0000301def mktemp(suffix="", prefix=template, dir=None):
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000302 """User-callable function to return a unique temporary file name. The
Guido van Rossum0e548712002-08-09 16:14:33 +0000303 file is not created.
304
Tim Peters04490bf2002-08-14 15:41:26 +0000305 Arguments are as for mkstemp, except that the 'text' argument is
Guido van Rossum0e548712002-08-09 16:14:33 +0000306 not accepted.
307
308 This function is unsafe and should not be used. The file name
309 refers to a file that did not exist at some point, but by the time
310 you get around to creating it, someone else may have beaten you to
311 the punch.
312 """
313
Guido van Rossum44f602d2002-11-22 15:56:29 +0000314## from warnings import warn as _warn
315## _warn("mktemp is a potential security risk to your program",
316## RuntimeWarning, stacklevel=2)
Guido van Rossum0e548712002-08-09 16:14:33 +0000317
Guido van Rossume888cdc2002-08-17 14:50:24 +0000318 if dir is None:
319 dir = gettempdir()
320
Guido van Rossum0e548712002-08-09 16:14:33 +0000321 names = _get_candidate_names()
Guido van Rossum805365e2007-05-07 22:24:25 +0000322 for seq in range(TMP_MAX):
Georg Brandla18af4e2007-04-21 15:47:16 +0000323 name = next(names)
Guido van Rossum0e548712002-08-09 16:14:33 +0000324 file = _os.path.join(dir, prefix + name + suffix)
Guido van Rossumb256159392003-11-10 02:16:36 +0000325 if not _exists(file):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000326 return file
Guido van Rossumca549821997-08-12 18:00:12 +0000327
Serhiy Storchaka7451a722013-02-09 22:25:49 +0200328 raise FileExistsError(_errno.EEXIST,
329 "No usable temporary filename found")
Guido van Rossumca549821997-08-12 18:00:12 +0000330
Christian Heimes3ecfea712008-02-09 20:51:34 +0000331
Guido van Rossum0e548712002-08-09 16:14:33 +0000332class _TemporaryFileWrapper:
Guido van Rossumca549821997-08-12 18:00:12 +0000333 """Temporary file wrapper
334
Guido van Rossum0e548712002-08-09 16:14:33 +0000335 This class provides a wrapper around files opened for
336 temporary use. In particular, it seeks to automatically
337 remove the file when it is no longer needed.
Guido van Rossumca549821997-08-12 18:00:12 +0000338 """
Tim Petersa255a722001-12-18 22:32:40 +0000339
Guido van Rossumd8faa362007-04-27 19:54:29 +0000340 def __init__(self, file, name, delete=True):
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000341 self.file = file
Guido van Rossum0e548712002-08-09 16:14:33 +0000342 self.name = name
Tim Peters6ef966e2002-11-21 15:48:33 +0000343 self.close_called = False
Guido van Rossumd8faa362007-04-27 19:54:29 +0000344 self.delete = delete
Guido van Rossumca549821997-08-12 18:00:12 +0000345
Guido van Rossumca549821997-08-12 18:00:12 +0000346 def __getattr__(self, name):
Christian Heimes3ecfea712008-02-09 20:51:34 +0000347 # Attribute lookups are delegated to the underlying file
348 # and cached for non-numeric results
349 # (i.e. methods are cached, closed and friends are not)
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000350 file = self.__dict__['file']
351 a = getattr(file, name)
Christian Heimes3ecfea712008-02-09 20:51:34 +0000352 if not isinstance(a, int):
Guido van Rossum6b708d51999-06-01 18:55:36 +0000353 setattr(self, name, a)
Guido van Rossum45e2fbc1998-03-26 21:13:24 +0000354 return a
Guido van Rossumca549821997-08-12 18:00:12 +0000355
Christian Heimes3ecfea712008-02-09 20:51:34 +0000356 # The underlying __enter__ method returns the wrong object
357 # (self.file) so override it to return the wrapper
358 def __enter__(self):
359 self.file.__enter__()
360 return self
361
Christian Heimes36d1f8e2008-02-28 22:21:11 +0000362 # iter() doesn't use __getattr__ to find the __iter__ method
Christian Heimesc83b6292008-02-28 21:10:17 +0000363 def __iter__(self):
Christian Heimes36d1f8e2008-02-28 22:21:11 +0000364 return iter(self.file)
Christian Heimesc83b6292008-02-28 21:10:17 +0000365
Guido van Rossum0e548712002-08-09 16:14:33 +0000366 # NT provides delete-on-close as a primitive, so we don't need
367 # the wrapper to do anything special. We still use it so that
368 # file.name is useful (i.e. not "(fdopen)") with NamedTemporaryFile.
369 if _os.name != 'nt':
Guido van Rossum0e548712002-08-09 16:14:33 +0000370 # Cache the unlinker so we don't get spurious errors at
371 # shutdown when the module-level "os" is None'd out. Note
372 # that this must be referenced as self.unlink, because the
373 # name TemporaryFileWrapper may also get None'd out before
374 # __del__ is called.
375 unlink = _os.unlink
Tim Peters1baa22a2001-01-12 10:02:46 +0000376
Guido van Rossum0e548712002-08-09 16:14:33 +0000377 def close(self):
378 if not self.close_called:
Tim Peters6ef966e2002-11-21 15:48:33 +0000379 self.close_called = True
Guido van Rossum0e548712002-08-09 16:14:33 +0000380 self.file.close()
Guido van Rossumd8faa362007-04-27 19:54:29 +0000381 if self.delete:
382 self.unlink(self.name)
Tim Peters1baa22a2001-01-12 10:02:46 +0000383
Guido van Rossum0e548712002-08-09 16:14:33 +0000384 def __del__(self):
385 self.close()
Tim Peters1baa22a2001-01-12 10:02:46 +0000386
Christian Heimes3ecfea712008-02-09 20:51:34 +0000387 # Need to trap __exit__ as well to ensure the file gets
388 # deleted when used in a with statement
389 def __exit__(self, exc, value, tb):
390 result = self.file.__exit__(exc, value, tb)
391 self.close()
392 return result
Benjamin Peterson98d23f22009-06-30 22:27:25 +0000393 else:
394 def __exit__(self, exc, value, tb):
Benjamin Peterson3f5de132009-07-01 15:47:07 +0000395 self.file.__exit__(exc, value, tb)
Christian Heimes3ecfea712008-02-09 20:51:34 +0000396
397
Guido van Rossumf0c74162007-08-28 03:29:45 +0000398def NamedTemporaryFile(mode='w+b', buffering=-1, encoding=None,
399 newline=None, suffix="", prefix=template,
400 dir=None, delete=True):
Guido van Rossum0e548712002-08-09 16:14:33 +0000401 """Create and return a temporary file.
402 Arguments:
403 'prefix', 'suffix', 'dir' -- as for mkstemp.
Guido van Rossumf0c74162007-08-28 03:29:45 +0000404 'mode' -- the mode argument to io.open (default "w+b").
405 'buffering' -- the buffer size argument to io.open (default -1).
406 'encoding' -- the encoding argument to io.open (default None)
407 'newline' -- the newline argument to io.open (default None)
Guido van Rossumd8faa362007-04-27 19:54:29 +0000408 'delete' -- whether the file is deleted on close (default True).
Guido van Rossum0e548712002-08-09 16:14:33 +0000409 The file is created as mkstemp() would do it.
Tim Peters1baa22a2001-01-12 10:02:46 +0000410
Raymond Hettingerfaa10eb2005-01-11 15:33:03 +0000411 Returns an object with a file-like interface; the name of the file
412 is accessible as file.name. The file will be automatically deleted
Guido van Rossumd8faa362007-04-27 19:54:29 +0000413 when it is closed unless the 'delete' argument is set to False.
Guido van Rossum0e548712002-08-09 16:14:33 +0000414 """
Tim Peters1baa22a2001-01-12 10:02:46 +0000415
Guido van Rossume888cdc2002-08-17 14:50:24 +0000416 if dir is None:
417 dir = gettempdir()
418
Amaury Forgeot d'Arc7d0bddd2009-11-30 00:08:56 +0000419 flags = _bin_openflags
Tim Peters1baa22a2001-01-12 10:02:46 +0000420
Guido van Rossum0e548712002-08-09 16:14:33 +0000421 # Setting O_TEMPORARY in the flags causes the OS to delete
422 # the file when it is closed. This is only supported by Windows.
Guido van Rossumd8faa362007-04-27 19:54:29 +0000423 if _os.name == 'nt' and delete:
Guido van Rossum0e548712002-08-09 16:14:33 +0000424 flags |= _os.O_TEMPORARY
Tim Peters1baa22a2001-01-12 10:02:46 +0000425
Guido van Rossum0e548712002-08-09 16:14:33 +0000426 (fd, name) = _mkstemp_inner(dir, prefix, suffix, flags)
Guido van Rossumf0c74162007-08-28 03:29:45 +0000427 file = _io.open(fd, mode, buffering=buffering,
428 newline=newline, encoding=encoding)
429
Guido van Rossumd8faa362007-04-27 19:54:29 +0000430 return _TemporaryFileWrapper(file, name, delete)
Guido van Rossum0e548712002-08-09 16:14:33 +0000431
Jason Tishler80c02af2002-08-14 15:10:09 +0000432if _os.name != 'posix' or _os.sys.platform == 'cygwin':
433 # On non-POSIX and Cygwin systems, assume that we cannot unlink a file
434 # while it is open.
Guido van Rossum0e548712002-08-09 16:14:33 +0000435 TemporaryFile = NamedTemporaryFile
Tim Peters1baa22a2001-01-12 10:02:46 +0000436
437else:
Guido van Rossumf0c74162007-08-28 03:29:45 +0000438 def TemporaryFile(mode='w+b', buffering=-1, encoding=None,
439 newline=None, suffix="", prefix=template,
440 dir=None):
Guido van Rossum0e548712002-08-09 16:14:33 +0000441 """Create and return a temporary file.
442 Arguments:
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000443 'prefix', 'suffix', 'dir' -- as for mkstemp.
Guido van Rossumf0c74162007-08-28 03:29:45 +0000444 'mode' -- the mode argument to io.open (default "w+b").
445 'buffering' -- the buffer size argument to io.open (default -1).
446 'encoding' -- the encoding argument to io.open (default None)
447 'newline' -- the newline argument to io.open (default None)
Guido van Rossum0e548712002-08-09 16:14:33 +0000448 The file is created as mkstemp() would do it.
Tim Peters1baa22a2001-01-12 10:02:46 +0000449
Raymond Hettingerfaa10eb2005-01-11 15:33:03 +0000450 Returns an object with a file-like interface. The file has no
451 name, and will cease to exist when it is closed.
Guido van Rossum0e548712002-08-09 16:14:33 +0000452 """
453
Guido van Rossume888cdc2002-08-17 14:50:24 +0000454 if dir is None:
455 dir = gettempdir()
456
Amaury Forgeot d'Arc7d0bddd2009-11-30 00:08:56 +0000457 flags = _bin_openflags
Guido van Rossum0e548712002-08-09 16:14:33 +0000458
459 (fd, name) = _mkstemp_inner(dir, prefix, suffix, flags)
460 try:
461 _os.unlink(name)
Guido van Rossumf0c74162007-08-28 03:29:45 +0000462 return _io.open(fd, mode, buffering=buffering,
463 newline=newline, encoding=encoding)
Guido van Rossum0e548712002-08-09 16:14:33 +0000464 except:
465 _os.close(fd)
466 raise
Guido van Rossumd8faa362007-04-27 19:54:29 +0000467
468class SpooledTemporaryFile:
Serhiy Storchaka4f169a72013-02-09 11:46:42 +0200469 """Temporary file wrapper, specialized to switch from BytesIO
470 or StringIO to a real file when it exceeds a certain size or
Guido van Rossumd8faa362007-04-27 19:54:29 +0000471 when a fileno is needed.
472 """
473 _rolled = False
474
Guido van Rossumf0c74162007-08-28 03:29:45 +0000475 def __init__(self, max_size=0, mode='w+b', buffering=-1,
476 encoding=None, newline=None,
Guido van Rossumd8faa362007-04-27 19:54:29 +0000477 suffix="", prefix=template, dir=None):
Guido van Rossum9a634702007-07-09 10:24:45 +0000478 if 'b' in mode:
479 self._file = _io.BytesIO()
480 else:
Guido van Rossum5d212552007-10-29 16:42:51 +0000481 # Setting newline="\n" avoids newline translation;
482 # this is important because otherwise on Windows we'd
Guido van Rossum98297ee2007-11-06 21:34:58 +0000483 # hget double newline translation upon rollover().
Alexandre Vassalotti3ade6f92008-06-12 01:13:54 +0000484 self._file = _io.StringIO(newline="\n")
Guido van Rossumd8faa362007-04-27 19:54:29 +0000485 self._max_size = max_size
486 self._rolled = False
Guido van Rossumf0c74162007-08-28 03:29:45 +0000487 self._TemporaryFileArgs = {'mode': mode, 'buffering': buffering,
488 'suffix': suffix, 'prefix': prefix,
489 'encoding': encoding, 'newline': newline,
490 'dir': dir}
Guido van Rossumd8faa362007-04-27 19:54:29 +0000491
492 def _check(self, file):
493 if self._rolled: return
494 max_size = self._max_size
495 if max_size and file.tell() > max_size:
496 self.rollover()
497
498 def rollover(self):
499 if self._rolled: return
500 file = self._file
Guido van Rossumf0c74162007-08-28 03:29:45 +0000501 newfile = self._file = TemporaryFile(**self._TemporaryFileArgs)
Guido van Rossumd8faa362007-04-27 19:54:29 +0000502 del self._TemporaryFileArgs
503
504 newfile.write(file.getvalue())
505 newfile.seek(file.tell(), 0)
506
507 self._rolled = True
508
Christian Heimes3ecfea712008-02-09 20:51:34 +0000509 # The method caching trick from NamedTemporaryFile
510 # won't work here, because _file may change from a
Serhiy Storchaka50254c52013-08-29 11:35:43 +0300511 # BytesIO/StringIO instance to a real file. So we list
Christian Heimes3ecfea712008-02-09 20:51:34 +0000512 # all the methods directly.
513
514 # Context management protocol
515 def __enter__(self):
516 if self._file.closed:
517 raise ValueError("Cannot enter context with closed file")
518 return self
519
520 def __exit__(self, exc, value, tb):
521 self._file.close()
522
Guido van Rossumd8faa362007-04-27 19:54:29 +0000523 # file protocol
524 def __iter__(self):
525 return self._file.__iter__()
526
527 def close(self):
528 self._file.close()
529
530 @property
531 def closed(self):
532 return self._file.closed
533
534 @property
535 def encoding(self):
Serhiy Storchakabbbbe8e2013-02-09 12:21:14 +0200536 try:
537 return self._file.encoding
538 except AttributeError:
539 if 'b' in self._TemporaryFileArgs['mode']:
540 raise
541 return self._TemporaryFileArgs['encoding']
Guido van Rossumd8faa362007-04-27 19:54:29 +0000542
543 def fileno(self):
544 self.rollover()
545 return self._file.fileno()
546
547 def flush(self):
548 self._file.flush()
549
550 def isatty(self):
551 return self._file.isatty()
552
553 @property
554 def mode(self):
Serhiy Storchakabbbbe8e2013-02-09 12:21:14 +0200555 try:
556 return self._file.mode
557 except AttributeError:
558 return self._TemporaryFileArgs['mode']
Guido van Rossumd8faa362007-04-27 19:54:29 +0000559
560 @property
561 def name(self):
Serhiy Storchakabbbbe8e2013-02-09 12:21:14 +0200562 try:
563 return self._file.name
564 except AttributeError:
565 return None
Guido van Rossumd8faa362007-04-27 19:54:29 +0000566
567 @property
568 def newlines(self):
Serhiy Storchakabbbbe8e2013-02-09 12:21:14 +0200569 try:
570 return self._file.newlines
571 except AttributeError:
572 if 'b' in self._TemporaryFileArgs['mode']:
573 raise
574 return self._TemporaryFileArgs['newline']
Guido van Rossumd8faa362007-04-27 19:54:29 +0000575
576 def read(self, *args):
577 return self._file.read(*args)
578
579 def readline(self, *args):
580 return self._file.readline(*args)
581
582 def readlines(self, *args):
583 return self._file.readlines(*args)
584
585 def seek(self, *args):
586 self._file.seek(*args)
587
588 @property
589 def softspace(self):
590 return self._file.softspace
591
592 def tell(self):
593 return self._file.tell()
594
Antoine Pitrou0e86a582011-11-25 18:03:09 +0100595 def truncate(self, size=None):
596 if size is None:
597 self._file.truncate()
598 else:
599 if size > self._max_size:
600 self.rollover()
601 self._file.truncate(size)
Guido van Rossumd8faa362007-04-27 19:54:29 +0000602
603 def write(self, s):
604 file = self._file
605 rv = file.write(s)
606 self._check(file)
607 return rv
608
609 def writelines(self, iterable):
610 file = self._file
611 rv = file.writelines(iterable)
612 self._check(file)
613 return rv
614
Nick Coghlan543af752010-10-24 11:23:25 +0000615
616class TemporaryDirectory(object):
617 """Create and return a temporary directory. This has the same
618 behavior as mkdtemp but can be used as a context manager. For
619 example:
620
621 with TemporaryDirectory() as tmpdir:
622 ...
623
Ezio Melotti30b9d5d2013-08-17 15:50:46 +0300624 Upon exiting the context, the directory and everything contained
Nick Coghlan543af752010-10-24 11:23:25 +0000625 in it are removed.
626 """
627
628 def __init__(self, suffix="", prefix=template, dir=None):
Nick Coghlan543af752010-10-24 11:23:25 +0000629 self._closed = False
Andrew Svetlov737fb892012-12-18 21:14:22 +0200630 self.name = None # Handle mkdtemp raising an exception
Nick Coghlan6b22f3f2010-12-12 15:24:21 +0000631 self.name = mkdtemp(suffix, prefix, dir)
632
633 def __repr__(self):
634 return "<{} {!r}>".format(self.__class__.__name__, self.name)
Nick Coghlan543af752010-10-24 11:23:25 +0000635
636 def __enter__(self):
637 return self.name
638
Nick Coghlan6b22f3f2010-12-12 15:24:21 +0000639 def cleanup(self, _warn=False):
640 if self.name and not self._closed:
641 try:
642 self._rmtree(self.name)
643 except (TypeError, AttributeError) as ex:
644 # Issue #10188: Emit a warning on stderr
645 # if the directory could not be cleaned
646 # up due to missing globals
647 if "None" not in str(ex):
648 raise
649 print("ERROR: {!r} while cleaning up {!r}".format(ex, self,),
650 file=_sys.stderr)
651 return
Nick Coghlan543af752010-10-24 11:23:25 +0000652 self._closed = True
Nick Coghlan6b22f3f2010-12-12 15:24:21 +0000653 if _warn:
654 self._warn("Implicitly cleaning up {!r}".format(self),
655 ResourceWarning)
Nick Coghlan543af752010-10-24 11:23:25 +0000656
657 def __exit__(self, exc, value, tb):
658 self.cleanup()
659
Nick Coghlan6b22f3f2010-12-12 15:24:21 +0000660 def __del__(self):
661 # Issue a ResourceWarning if implicit cleanup needed
662 self.cleanup(_warn=True)
Nick Coghlan543af752010-10-24 11:23:25 +0000663
664 # XXX (ncoghlan): The following code attempts to make
665 # this class tolerant of the module nulling out process
666 # that happens during CPython interpreter shutdown
667 # Alas, it doesn't actually manage it. See issue #10188
668 _listdir = staticmethod(_os.listdir)
669 _path_join = staticmethod(_os.path.join)
670 _isdir = staticmethod(_os.path.isdir)
Charles-François Natalidef35432011-07-29 18:59:24 +0200671 _islink = staticmethod(_os.path.islink)
Nick Coghlan543af752010-10-24 11:23:25 +0000672 _remove = staticmethod(_os.remove)
673 _rmdir = staticmethod(_os.rmdir)
Nick Coghlan6b22f3f2010-12-12 15:24:21 +0000674 _warn = _warnings.warn
Nick Coghlan543af752010-10-24 11:23:25 +0000675
676 def _rmtree(self, path):
677 # Essentially a stripped down version of shutil.rmtree. We can't
678 # use globals because they may be None'ed out at shutdown.
679 for name in self._listdir(path):
680 fullname = self._path_join(path, name)
681 try:
Charles-François Natalidef35432011-07-29 18:59:24 +0200682 isdir = self._isdir(fullname) and not self._islink(fullname)
Andrew Svetlovad28c7f2012-12-18 22:02:39 +0200683 except OSError:
Nick Coghlan543af752010-10-24 11:23:25 +0000684 isdir = False
685 if isdir:
686 self._rmtree(fullname)
687 else:
688 try:
689 self._remove(fullname)
Andrew Svetlovad28c7f2012-12-18 22:02:39 +0200690 except OSError:
Nick Coghlan543af752010-10-24 11:23:25 +0000691 pass
692 try:
693 self._rmdir(path)
Andrew Svetlovad28c7f2012-12-18 22:02:39 +0200694 except OSError:
Nick Coghlan543af752010-10-24 11:23:25 +0000695 pass