/Lib/tempfile.py

http://unladen-swallow.googlecode.com/ · Python · 603 lines · 477 code · 74 blank · 52 comment · 56 complexity · 1eca671f8c81e26d7a78da7c62270c5d MD5 · raw file

  1. """Temporary files.
  2. This module provides generic, low- and high-level interfaces for
  3. creating temporary files and directories. The interfaces listed
  4. as "safe" just below can be used without fear of race conditions.
  5. Those listed as "unsafe" cannot, and are provided for backward
  6. compatibility only.
  7. This module also provides some data items to the user:
  8. TMP_MAX - maximum number of names that will be tried before
  9. giving up.
  10. template - the default prefix for all temporary names.
  11. You may change this to control the default prefix.
  12. tempdir - If this is set to a string before the first use of
  13. any routine from this module, it will be considered as
  14. another candidate location to store temporary files.
  15. """
  16. __all__ = [
  17. "NamedTemporaryFile", "TemporaryFile", # high level safe interfaces
  18. "SpooledTemporaryFile",
  19. "mkstemp", "mkdtemp", # low level safe interfaces
  20. "mktemp", # deprecated unsafe interface
  21. "TMP_MAX", "gettempprefix", # constants
  22. "tempdir", "gettempdir"
  23. ]
  24. # Imports.
  25. import os as _os
  26. import errno as _errno
  27. from random import Random as _Random
  28. try:
  29. from cStringIO import StringIO as _StringIO
  30. except ImportError:
  31. from StringIO import StringIO as _StringIO
  32. try:
  33. import fcntl as _fcntl
  34. except ImportError:
  35. def _set_cloexec(fd):
  36. pass
  37. else:
  38. def _set_cloexec(fd):
  39. try:
  40. flags = _fcntl.fcntl(fd, _fcntl.F_GETFD, 0)
  41. except IOError:
  42. pass
  43. else:
  44. # flags read successfully, modify
  45. flags |= _fcntl.FD_CLOEXEC
  46. _fcntl.fcntl(fd, _fcntl.F_SETFD, flags)
  47. try:
  48. import thread as _thread
  49. except ImportError:
  50. import dummy_thread as _thread
  51. _allocate_lock = _thread.allocate_lock
  52. _text_openflags = _os.O_RDWR | _os.O_CREAT | _os.O_EXCL
  53. if hasattr(_os, 'O_NOINHERIT'):
  54. _text_openflags |= _os.O_NOINHERIT
  55. if hasattr(_os, 'O_NOFOLLOW'):
  56. _text_openflags |= _os.O_NOFOLLOW
  57. _bin_openflags = _text_openflags
  58. if hasattr(_os, 'O_BINARY'):
  59. _bin_openflags |= _os.O_BINARY
  60. if hasattr(_os, 'TMP_MAX'):
  61. TMP_MAX = _os.TMP_MAX
  62. else:
  63. TMP_MAX = 10000
  64. template = "tmp"
  65. # Internal routines.
  66. _once_lock = _allocate_lock()
  67. if hasattr(_os, "lstat"):
  68. _stat = _os.lstat
  69. elif hasattr(_os, "stat"):
  70. _stat = _os.stat
  71. else:
  72. # Fallback. All we need is something that raises os.error if the
  73. # file doesn't exist.
  74. def _stat(fn):
  75. try:
  76. f = open(fn)
  77. except IOError:
  78. raise _os.error
  79. f.close()
  80. def _exists(fn):
  81. try:
  82. _stat(fn)
  83. except _os.error:
  84. return False
  85. else:
  86. return True
  87. class _RandomNameSequence:
  88. """An instance of _RandomNameSequence generates an endless
  89. sequence of unpredictable strings which can safely be incorporated
  90. into file names. Each string is six characters long. Multiple
  91. threads can safely use the same instance at the same time.
  92. _RandomNameSequence is an iterator."""
  93. characters = ("abcdefghijklmnopqrstuvwxyz" +
  94. "ABCDEFGHIJKLMNOPQRSTUVWXYZ" +
  95. "0123456789_")
  96. def __init__(self):
  97. self.mutex = _allocate_lock()
  98. self.rng = _Random()
  99. self.normcase = _os.path.normcase
  100. def __iter__(self):
  101. return self
  102. def next(self):
  103. m = self.mutex
  104. c = self.characters
  105. choose = self.rng.choice
  106. m.acquire()
  107. try:
  108. letters = [choose(c) for dummy in "123456"]
  109. finally:
  110. m.release()
  111. return self.normcase(''.join(letters))
  112. def _candidate_tempdir_list():
  113. """Generate a list of candidate temporary directories which
  114. _get_default_tempdir will try."""
  115. dirlist = []
  116. # First, try the environment.
  117. for envname in 'TMPDIR', 'TEMP', 'TMP':
  118. dirname = _os.getenv(envname)
  119. if dirname: dirlist.append(dirname)
  120. # Failing that, try OS-specific locations.
  121. if _os.name == 'riscos':
  122. dirname = _os.getenv('Wimp$ScrapDir')
  123. if dirname: dirlist.append(dirname)
  124. elif _os.name == 'nt':
  125. dirlist.extend([ r'c:\temp', r'c:\tmp', r'\temp', r'\tmp' ])
  126. else:
  127. dirlist.extend([ '/tmp', '/var/tmp', '/usr/tmp' ])
  128. # As a last resort, the current directory.
  129. try:
  130. dirlist.append(_os.getcwd())
  131. except (AttributeError, _os.error):
  132. dirlist.append(_os.curdir)
  133. return dirlist
  134. def _get_default_tempdir():
  135. """Calculate the default directory to use for temporary files.
  136. This routine should be called exactly once.
  137. We determine whether or not a candidate temp dir is usable by
  138. trying to create and write to a file in that directory. If this
  139. is successful, the test file is deleted. To prevent denial of
  140. service, the name of the test file must be randomized."""
  141. namer = _RandomNameSequence()
  142. dirlist = _candidate_tempdir_list()
  143. flags = _text_openflags
  144. for dir in dirlist:
  145. if dir != _os.curdir:
  146. dir = _os.path.normcase(_os.path.abspath(dir))
  147. # Try only a few names per directory.
  148. for seq in xrange(100):
  149. name = namer.next()
  150. filename = _os.path.join(dir, name)
  151. try:
  152. fd = _os.open(filename, flags, 0600)
  153. fp = _os.fdopen(fd, 'w')
  154. fp.write('blat')
  155. fp.close()
  156. _os.unlink(filename)
  157. del fp, fd
  158. return dir
  159. except (OSError, IOError), e:
  160. if e[0] != _errno.EEXIST:
  161. break # no point trying more names in this directory
  162. pass
  163. raise IOError, (_errno.ENOENT,
  164. ("No usable temporary directory found in %s" % dirlist))
  165. _name_sequence = None
  166. def _get_candidate_names():
  167. """Common setup sequence for all user-callable interfaces."""
  168. global _name_sequence
  169. if _name_sequence is None:
  170. _once_lock.acquire()
  171. try:
  172. if _name_sequence is None:
  173. _name_sequence = _RandomNameSequence()
  174. finally:
  175. _once_lock.release()
  176. return _name_sequence
  177. def _mkstemp_inner(dir, pre, suf, flags):
  178. """Code common to mkstemp, TemporaryFile, and NamedTemporaryFile."""
  179. names = _get_candidate_names()
  180. for seq in xrange(TMP_MAX):
  181. name = names.next()
  182. file = _os.path.join(dir, pre + name + suf)
  183. try:
  184. fd = _os.open(file, flags, 0600)
  185. _set_cloexec(fd)
  186. return (fd, _os.path.abspath(file))
  187. except OSError, e:
  188. if e.errno == _errno.EEXIST:
  189. continue # try again
  190. raise
  191. raise IOError, (_errno.EEXIST, "No usable temporary file name found")
  192. # User visible interfaces.
  193. def gettempprefix():
  194. """Accessor for tempdir.template."""
  195. return template
  196. tempdir = None
  197. def gettempdir():
  198. """Accessor for tempfile.tempdir."""
  199. global tempdir
  200. if tempdir is None:
  201. _once_lock.acquire()
  202. try:
  203. if tempdir is None:
  204. tempdir = _get_default_tempdir()
  205. finally:
  206. _once_lock.release()
  207. return tempdir
  208. def mkstemp(suffix="", prefix=template, dir=None, text=False):
  209. """User-callable function to create and return a unique temporary
  210. file. The return value is a pair (fd, name) where fd is the
  211. file descriptor returned by os.open, and name is the filename.
  212. If 'suffix' is specified, the file name will end with that suffix,
  213. otherwise there will be no suffix.
  214. If 'prefix' is specified, the file name will begin with that prefix,
  215. otherwise a default prefix is used.
  216. If 'dir' is specified, the file will be created in that directory,
  217. otherwise a default directory is used.
  218. If 'text' is specified and true, the file is opened in text
  219. mode. Else (the default) the file is opened in binary mode. On
  220. some operating systems, this makes no difference.
  221. The file is readable and writable only by the creating user ID.
  222. If the operating system uses permission bits to indicate whether a
  223. file is executable, the file is executable by no one. The file
  224. descriptor is not inherited by children of this process.
  225. Caller is responsible for deleting the file when done with it.
  226. """
  227. if dir is None:
  228. dir = gettempdir()
  229. if text:
  230. flags = _text_openflags
  231. else:
  232. flags = _bin_openflags
  233. return _mkstemp_inner(dir, prefix, suffix, flags)
  234. def mkdtemp(suffix="", prefix=template, dir=None):
  235. """User-callable function to create and return a unique temporary
  236. directory. The return value is the pathname of the directory.
  237. Arguments are as for mkstemp, except that the 'text' argument is
  238. not accepted.
  239. The directory is readable, writable, and searchable only by the
  240. creating user.
  241. Caller is responsible for deleting the directory when done with it.
  242. """
  243. if dir is None:
  244. dir = gettempdir()
  245. names = _get_candidate_names()
  246. for seq in xrange(TMP_MAX):
  247. name = names.next()
  248. file = _os.path.join(dir, prefix + name + suffix)
  249. try:
  250. _os.mkdir(file, 0700)
  251. return file
  252. except OSError, e:
  253. if e.errno == _errno.EEXIST:
  254. continue # try again
  255. raise
  256. raise IOError, (_errno.EEXIST, "No usable temporary directory name found")
  257. def mktemp(suffix="", prefix=template, dir=None):
  258. """User-callable function to return a unique temporary file name. The
  259. file is not created.
  260. Arguments are as for mkstemp, except that the 'text' argument is
  261. not accepted.
  262. This function is unsafe and should not be used. The file name
  263. refers to a file that did not exist at some point, but by the time
  264. you get around to creating it, someone else may have beaten you to
  265. the punch.
  266. """
  267. ## from warnings import warn as _warn
  268. ## _warn("mktemp is a potential security risk to your program",
  269. ## RuntimeWarning, stacklevel=2)
  270. if dir is None:
  271. dir = gettempdir()
  272. names = _get_candidate_names()
  273. for seq in xrange(TMP_MAX):
  274. name = names.next()
  275. file = _os.path.join(dir, prefix + name + suffix)
  276. if not _exists(file):
  277. return file
  278. raise IOError, (_errno.EEXIST, "No usable temporary filename found")
  279. class _TemporaryFileWrapper:
  280. """Temporary file wrapper
  281. This class provides a wrapper around files opened for
  282. temporary use. In particular, it seeks to automatically
  283. remove the file when it is no longer needed.
  284. """
  285. def __init__(self, file, name, delete=True):
  286. self.file = file
  287. self.name = name
  288. self.close_called = False
  289. self.delete = delete
  290. def __getattr__(self, name):
  291. # Attribute lookups are delegated to the underlying file
  292. # and cached for non-numeric results
  293. # (i.e. methods are cached, closed and friends are not)
  294. file = self.__dict__['file']
  295. a = getattr(file, name)
  296. if not issubclass(type(a), type(0)):
  297. setattr(self, name, a)
  298. return a
  299. # The underlying __enter__ method returns the wrong object
  300. # (self.file) so override it to return the wrapper
  301. def __enter__(self):
  302. self.file.__enter__()
  303. return self
  304. # NT provides delete-on-close as a primitive, so we don't need
  305. # the wrapper to do anything special. We still use it so that
  306. # file.name is useful (i.e. not "(fdopen)") with NamedTemporaryFile.
  307. if _os.name != 'nt':
  308. # Cache the unlinker so we don't get spurious errors at
  309. # shutdown when the module-level "os" is None'd out. Note
  310. # that this must be referenced as self.unlink, because the
  311. # name TemporaryFileWrapper may also get None'd out before
  312. # __del__ is called.
  313. unlink = _os.unlink
  314. def close(self):
  315. if not self.close_called:
  316. self.close_called = True
  317. self.file.close()
  318. if self.delete:
  319. self.unlink(self.name)
  320. def __del__(self):
  321. self.close()
  322. # Need to trap __exit__ as well to ensure the file gets
  323. # deleted when used in a with statement
  324. def __exit__(self, exc, value, tb):
  325. result = self.file.__exit__(exc, value, tb)
  326. self.close()
  327. return result
  328. def NamedTemporaryFile(mode='w+b', bufsize=-1, suffix="",
  329. prefix=template, dir=None, delete=True):
  330. """Create and return a temporary file.
  331. Arguments:
  332. 'prefix', 'suffix', 'dir' -- as for mkstemp.
  333. 'mode' -- the mode argument to os.fdopen (default "w+b").
  334. 'bufsize' -- the buffer size argument to os.fdopen (default -1).
  335. 'delete' -- whether the file is deleted on close (default True).
  336. The file is created as mkstemp() would do it.
  337. Returns an object with a file-like interface; the name of the file
  338. is accessible as file.name. The file will be automatically deleted
  339. when it is closed unless the 'delete' argument is set to False.
  340. """
  341. if dir is None:
  342. dir = gettempdir()
  343. if 'b' in mode:
  344. flags = _bin_openflags
  345. else:
  346. flags = _text_openflags
  347. # Setting O_TEMPORARY in the flags causes the OS to delete
  348. # the file when it is closed. This is only supported by Windows.
  349. if _os.name == 'nt' and delete:
  350. flags |= _os.O_TEMPORARY
  351. (fd, name) = _mkstemp_inner(dir, prefix, suffix, flags)
  352. file = _os.fdopen(fd, mode, bufsize)
  353. return _TemporaryFileWrapper(file, name, delete)
  354. if _os.name != 'posix' or _os.sys.platform == 'cygwin':
  355. # On non-POSIX and Cygwin systems, assume that we cannot unlink a file
  356. # while it is open.
  357. TemporaryFile = NamedTemporaryFile
  358. else:
  359. def TemporaryFile(mode='w+b', bufsize=-1, suffix="",
  360. prefix=template, dir=None):
  361. """Create and return a temporary file.
  362. Arguments:
  363. 'prefix', 'suffix', 'dir' -- as for mkstemp.
  364. 'mode' -- the mode argument to os.fdopen (default "w+b").
  365. 'bufsize' -- the buffer size argument to os.fdopen (default -1).
  366. The file is created as mkstemp() would do it.
  367. Returns an object with a file-like interface. The file has no
  368. name, and will cease to exist when it is closed.
  369. """
  370. if dir is None:
  371. dir = gettempdir()
  372. if 'b' in mode:
  373. flags = _bin_openflags
  374. else:
  375. flags = _text_openflags
  376. (fd, name) = _mkstemp_inner(dir, prefix, suffix, flags)
  377. try:
  378. _os.unlink(name)
  379. return _os.fdopen(fd, mode, bufsize)
  380. except:
  381. _os.close(fd)
  382. raise
  383. class SpooledTemporaryFile:
  384. """Temporary file wrapper, specialized to switch from
  385. StringIO to a real file when it exceeds a certain size or
  386. when a fileno is needed.
  387. """
  388. _rolled = False
  389. def __init__(self, max_size=0, mode='w+b', bufsize=-1,
  390. suffix="", prefix=template, dir=None):
  391. self._file = _StringIO()
  392. self._max_size = max_size
  393. self._rolled = False
  394. self._TemporaryFileArgs = (mode, bufsize, suffix, prefix, dir)
  395. def _check(self, file):
  396. if self._rolled: return
  397. max_size = self._max_size
  398. if max_size and file.tell() > max_size:
  399. self.rollover()
  400. def rollover(self):
  401. if self._rolled: return
  402. file = self._file
  403. newfile = self._file = TemporaryFile(*self._TemporaryFileArgs)
  404. del self._TemporaryFileArgs
  405. newfile.write(file.getvalue())
  406. newfile.seek(file.tell(), 0)
  407. self._rolled = True
  408. # The method caching trick from NamedTemporaryFile
  409. # won't work here, because _file may change from a
  410. # _StringIO instance to a real file. So we list
  411. # all the methods directly.
  412. # Context management protocol
  413. def __enter__(self):
  414. if self._file.closed:
  415. raise ValueError("Cannot enter context with closed file")
  416. return self
  417. def __exit__(self, exc, value, tb):
  418. self._file.close()
  419. # file protocol
  420. def __iter__(self):
  421. return self._file.__iter__()
  422. def close(self):
  423. self._file.close()
  424. @property
  425. def closed(self):
  426. return self._file.closed
  427. @property
  428. def encoding(self):
  429. return self._file.encoding
  430. def fileno(self):
  431. self.rollover()
  432. return self._file.fileno()
  433. def flush(self):
  434. self._file.flush()
  435. def isatty(self):
  436. return self._file.isatty()
  437. @property
  438. def mode(self):
  439. return self._file.mode
  440. @property
  441. def name(self):
  442. return self._file.name
  443. @property
  444. def newlines(self):
  445. return self._file.newlines
  446. def next(self):
  447. return self._file.next
  448. def read(self, *args):
  449. return self._file.read(*args)
  450. def readline(self, *args):
  451. return self._file.readline(*args)
  452. def readlines(self, *args):
  453. return self._file.readlines(*args)
  454. def seek(self, *args):
  455. self._file.seek(*args)
  456. @property
  457. def softspace(self):
  458. return self._file.softspace
  459. def tell(self):
  460. return self._file.tell()
  461. def truncate(self):
  462. self._file.truncate()
  463. def write(self, s):
  464. file = self._file
  465. rv = file.write(s)
  466. self._check(file)
  467. return rv
  468. def writelines(self, iterable):
  469. file = self._file
  470. rv = file.writelines(iterable)
  471. self._check(file)
  472. return rv
  473. def xreadlines(self, *args):
  474. return self._file.xreadlines(*args)