Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`tempfile` --- Generate temporary files and directories |
| 2 | ============================================================ |
| 3 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 4 | .. module:: tempfile |
| 5 | :synopsis: Generate temporary files and directories. |
| 6 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 7 | .. sectionauthor:: Zack Weinberg <zack@codesourcery.com> |
| 8 | |
| 9 | **Source code:** :source:`Lib/tempfile.py` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | |
| 11 | .. index:: |
| 12 | pair: temporary; file name |
| 13 | pair: temporary; file |
| 14 | |
Raymond Hettinger | a199368 | 2011-01-27 01:20:32 +0000 | [diff] [blame] | 15 | -------------- |
| 16 | |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 17 | This module creates temporary files and directories. It works on all |
| 18 | supported platforms. :class:`TemporaryFile`, :class:`NamedTemporaryFile`, |
| 19 | :class:`TemporaryDirectory`, and :class:`SpooledTemporaryFile` are high-level |
| 20 | interfaces which provide automatic cleanup and can be used as |
| 21 | context managers. :func:`mkstemp` and |
| 22 | :func:`mkdtemp` are lower-level functions which require manual cleanup. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 23 | |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 24 | All the user-callable functions and constructors take additional arguments which |
| 25 | allow direct control over the location and name of temporary files and |
| 26 | directories. Files names used by this module include a string of |
| 27 | random characters which allows those files to be securely created in |
| 28 | shared temporary directories. |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 29 | To maintain backward compatibility, the argument order is somewhat odd; it |
| 30 | is recommended to use keyword arguments for clarity. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 31 | |
Nick Coghlan | 543af75 | 2010-10-24 11:23:25 +0000 | [diff] [blame] | 32 | The module defines the following user-callable items: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 33 | |
sth | 825aab9 | 2018-05-23 07:07:01 +0200 | [diff] [blame] | 34 | .. function:: TemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 35 | |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 36 | Return a :term:`file-like object` that can be used as a temporary storage area. |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 37 | The file is created securely, using the same rules as :func:`mkstemp`. It will be destroyed as soon |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 38 | as it is closed (including an implicit close when the object is garbage |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 39 | collected). Under Unix, the directory entry for the file is either not created at all or is removed |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 40 | immediately after the file is created. Other platforms do not support |
| 41 | this; your code should not rely on a temporary file created using this |
| 42 | function having or not having a visible name in the file system. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 43 | |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 44 | The resulting object can be used as a context manager (see |
| 45 | :ref:`tempfile-examples`). On completion of the context or |
| 46 | destruction of the file object the temporary file will be removed |
| 47 | from the filesystem. |
| 48 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 49 | The *mode* parameter defaults to ``'w+b'`` so that the file created can |
| 50 | be read and written without being closed. Binary mode is used so that it |
| 51 | behaves consistently on all platforms without regard for the data that is |
sth | 825aab9 | 2018-05-23 07:07:01 +0200 | [diff] [blame] | 52 | stored. *buffering*, *encoding*, *errors* and *newline* are interpreted as for |
Georg Brandl | 14dfede | 2010-05-21 21:12:07 +0000 | [diff] [blame] | 53 | :func:`open`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 54 | |
Martin Panter | 9b566c3 | 2015-11-07 00:32:50 +0000 | [diff] [blame] | 55 | The *dir*, *prefix* and *suffix* parameters have the same meaning and |
| 56 | defaults as with :func:`mkstemp`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 58 | The returned object is a true file object on POSIX platforms. On other |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 59 | platforms, it is a file-like object whose :attr:`!file` attribute is the |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 60 | underlying true file object. |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 61 | |
Victor Stinner | d967fc9 | 2014-06-05 14:27:45 +0200 | [diff] [blame] | 62 | The :py:data:`os.O_TMPFILE` flag is used if it is available and works |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 63 | (Linux-specific, requires Linux kernel 3.11 or later). |
Victor Stinner | d967fc9 | 2014-06-05 14:27:45 +0200 | [diff] [blame] | 64 | |
| 65 | .. versionchanged:: 3.5 |
| 66 | |
| 67 | The :py:data:`os.O_TMPFILE` flag is now used if available. |
| 68 | |
sth | 825aab9 | 2018-05-23 07:07:01 +0200 | [diff] [blame] | 69 | .. versionchanged:: 3.8 |
| 70 | Added *errors* parameter. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
sth | 825aab9 | 2018-05-23 07:07:01 +0200 | [diff] [blame] | 72 | |
| 73 | .. function:: NamedTemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=None, delete=True, *, errors=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 74 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 75 | This function operates exactly as :func:`TemporaryFile` does, except that |
| 76 | the file is guaranteed to have a visible name in the file system (on |
| 77 | Unix, the directory entry is not unlinked). That name can be retrieved |
Martin Panter | 1f0e1f3 | 2016-02-22 10:10:00 +0000 | [diff] [blame] | 78 | from the :attr:`name` attribute of the returned |
| 79 | file-like object. Whether the name can be |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 80 | used to open the file a second time, while the named temporary file is |
| 81 | still open, varies across platforms (it can be so used on Unix; it cannot |
| 82 | on Windows NT or later). If *delete* is true (the default), the file is |
| 83 | deleted as soon as it is closed. |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 84 | The returned object is always a file-like object whose :attr:`!file` |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 85 | attribute is the underlying true file object. This file-like object can |
| 86 | be used in a :keyword:`with` statement, just like a normal file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 87 | |
sth | 825aab9 | 2018-05-23 07:07:01 +0200 | [diff] [blame] | 88 | .. versionchanged:: 3.8 |
| 89 | Added *errors* parameter. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 90 | |
sth | 825aab9 | 2018-05-23 07:07:01 +0200 | [diff] [blame] | 91 | |
| 92 | .. function:: SpooledTemporaryFile(max_size=0, mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 93 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 94 | This function operates exactly as :func:`TemporaryFile` does, except that |
| 95 | data is spooled in memory until the file size exceeds *max_size*, or |
| 96 | until the file's :func:`fileno` method is called, at which point the |
| 97 | contents are written to disk and operation proceeds as with |
| 98 | :func:`TemporaryFile`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 99 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 100 | The resulting file has one additional method, :func:`rollover`, which |
| 101 | causes the file to roll over to an on-disk file regardless of its size. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 102 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 103 | The returned object is a file-like object whose :attr:`_file` attribute |
Martin Panter | 7462b649 | 2015-11-02 03:37:02 +0000 | [diff] [blame] | 104 | is either an :class:`io.BytesIO` or :class:`io.StringIO` object (depending on |
Serhiy Storchaka | 4b109cb | 2013-02-09 11:51:21 +0200 | [diff] [blame] | 105 | whether binary or text *mode* was specified) or a true file |
Serhiy Storchaka | 4f169a7 | 2013-02-09 11:46:42 +0200 | [diff] [blame] | 106 | object, depending on whether :func:`rollover` has been called. This |
| 107 | file-like object can be used in a :keyword:`with` statement, just like |
| 108 | a normal file. |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 109 | |
R David Murray | ca76ea1 | 2012-10-06 18:32:39 -0400 | [diff] [blame] | 110 | .. versionchanged:: 3.3 |
| 111 | the truncate method now accepts a ``size`` argument. |
| 112 | |
sth | 825aab9 | 2018-05-23 07:07:01 +0200 | [diff] [blame] | 113 | .. versionchanged:: 3.8 |
| 114 | Added *errors* parameter. |
| 115 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 116 | |
Martin Panter | 9b566c3 | 2015-11-07 00:32:50 +0000 | [diff] [blame] | 117 | .. function:: TemporaryDirectory(suffix=None, prefix=None, dir=None) |
Nick Coghlan | 543af75 | 2010-10-24 11:23:25 +0000 | [diff] [blame] | 118 | |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 119 | This function securely creates a temporary directory using the same rules as :func:`mkdtemp`. |
Nick Coghlan | 543af75 | 2010-10-24 11:23:25 +0000 | [diff] [blame] | 120 | The resulting object can be used as a context manager (see |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 121 | :ref:`tempfile-examples`). On completion of the context or destruction |
R David Murray | 2368607 | 2014-02-05 14:53:40 -0500 | [diff] [blame] | 122 | of the temporary directory object the newly created temporary directory |
Nick Coghlan | 543af75 | 2010-10-24 11:23:25 +0000 | [diff] [blame] | 123 | and all its contents are removed from the filesystem. |
| 124 | |
R David Murray | 2368607 | 2014-02-05 14:53:40 -0500 | [diff] [blame] | 125 | The directory name can be retrieved from the :attr:`name` attribute of the |
| 126 | returned object. When the returned object is used as a context manager, the |
| 127 | :attr:`name` will be assigned to the target of the :keyword:`as` clause in |
| 128 | the :keyword:`with` statement, if there is one. |
Nick Coghlan | 543af75 | 2010-10-24 11:23:25 +0000 | [diff] [blame] | 129 | |
| 130 | The directory can be explicitly cleaned up by calling the |
| 131 | :func:`cleanup` method. |
| 132 | |
| 133 | .. versionadded:: 3.2 |
| 134 | |
| 135 | |
Gregory P. Smith | ad577b9 | 2015-05-22 16:18:14 -0700 | [diff] [blame] | 136 | .. function:: mkstemp(suffix=None, prefix=None, dir=None, text=False) |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 137 | |
| 138 | Creates a temporary file in the most secure manner possible. There are |
| 139 | no race conditions in the file's creation, assuming that the platform |
| 140 | properly implements the :const:`os.O_EXCL` flag for :func:`os.open`. The |
| 141 | file is readable and writable only by the creating user ID. If the |
| 142 | platform uses permission bits to indicate whether a file is executable, |
| 143 | the file is executable by no one. The file descriptor is not inherited |
| 144 | by child processes. |
| 145 | |
| 146 | Unlike :func:`TemporaryFile`, the user of :func:`mkstemp` is responsible |
| 147 | for deleting the temporary file when done with it. |
| 148 | |
Martin Panter | 9b566c3 | 2015-11-07 00:32:50 +0000 | [diff] [blame] | 149 | If *suffix* is not ``None``, the file name will end with that suffix, |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 150 | otherwise there will be no suffix. :func:`mkstemp` does not put a dot |
| 151 | between the file name and the suffix; if you need one, put it at the |
| 152 | beginning of *suffix*. |
| 153 | |
Martin Panter | 9b566c3 | 2015-11-07 00:32:50 +0000 | [diff] [blame] | 154 | If *prefix* is not ``None``, the file name will begin with that prefix; |
| 155 | otherwise, a default prefix is used. The default is the return value of |
| 156 | :func:`gettempprefix` or :func:`gettempprefixb`, as appropriate. |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 157 | |
Martin Panter | 9b566c3 | 2015-11-07 00:32:50 +0000 | [diff] [blame] | 158 | If *dir* is not ``None``, the file will be created in that directory; |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 159 | otherwise, a default directory is used. The default directory is chosen |
| 160 | from a platform-dependent list, but the user of the application can |
| 161 | control the directory location by setting the *TMPDIR*, *TEMP* or *TMP* |
| 162 | environment variables. There is thus no guarantee that the generated |
| 163 | filename will have any nice properties, such as not requiring quoting |
| 164 | when passed to external commands via ``os.popen()``. |
| 165 | |
Martin Panter | 9b566c3 | 2015-11-07 00:32:50 +0000 | [diff] [blame] | 166 | If any of *suffix*, *prefix*, and *dir* are not |
| 167 | ``None``, they must be the same type. |
Gregory P. Smith | ad577b9 | 2015-05-22 16:18:14 -0700 | [diff] [blame] | 168 | If they are bytes, the returned name will be bytes instead of str. |
| 169 | If you want to force a bytes return value with otherwise default behavior, |
| 170 | pass ``suffix=b''``. |
| 171 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 172 | If *text* is specified, it indicates whether to open the file in binary |
| 173 | mode (the default) or text mode. On some platforms, this makes no |
| 174 | difference. |
| 175 | |
| 176 | :func:`mkstemp` returns a tuple containing an OS-level handle to an open |
| 177 | file (as would be returned by :func:`os.open`) and the absolute pathname |
| 178 | of that file, in that order. |
| 179 | |
Gregory P. Smith | ad577b9 | 2015-05-22 16:18:14 -0700 | [diff] [blame] | 180 | .. versionchanged:: 3.5 |
| 181 | *suffix*, *prefix*, and *dir* may now be supplied in bytes in order to |
| 182 | obtain a bytes return value. Prior to this, only str was allowed. |
| 183 | *suffix* and *prefix* now accept and default to ``None`` to cause |
| 184 | an appropriate default value to be used. |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 185 | |
Gregory P. Smith | ad577b9 | 2015-05-22 16:18:14 -0700 | [diff] [blame] | 186 | |
| 187 | .. function:: mkdtemp(suffix=None, prefix=None, dir=None) |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 188 | |
| 189 | Creates a temporary directory in the most secure manner possible. There |
| 190 | are no race conditions in the directory's creation. The directory is |
| 191 | readable, writable, and searchable only by the creating user ID. |
| 192 | |
| 193 | The user of :func:`mkdtemp` is responsible for deleting the temporary |
| 194 | directory and its contents when done with it. |
| 195 | |
| 196 | The *prefix*, *suffix*, and *dir* arguments are the same as for |
| 197 | :func:`mkstemp`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 198 | |
| 199 | :func:`mkdtemp` returns the absolute pathname of the new directory. |
| 200 | |
Gregory P. Smith | ad577b9 | 2015-05-22 16:18:14 -0700 | [diff] [blame] | 201 | .. versionchanged:: 3.5 |
| 202 | *suffix*, *prefix*, and *dir* may now be supplied in bytes in order to |
| 203 | obtain a bytes return value. Prior to this, only str was allowed. |
| 204 | *suffix* and *prefix* now accept and default to ``None`` to cause |
| 205 | an appropriate default value to be used. |
| 206 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 207 | |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 208 | .. function:: gettempdir() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 209 | |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 210 | Return the name of the directory used for temporary files. This |
| 211 | defines the default value for the *dir* argument to all functions |
| 212 | in this module. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 213 | |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 214 | Python searches a standard list of directories to find one which |
| 215 | the calling user can create files in. The list is: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 216 | |
| 217 | #. The directory named by the :envvar:`TMPDIR` environment variable. |
| 218 | |
| 219 | #. The directory named by the :envvar:`TEMP` environment variable. |
| 220 | |
| 221 | #. The directory named by the :envvar:`TMP` environment variable. |
| 222 | |
| 223 | #. A platform-specific location: |
| 224 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 225 | * On Windows, the directories :file:`C:\\TEMP`, :file:`C:\\TMP`, |
| 226 | :file:`\\TEMP`, and :file:`\\TMP`, in that order. |
| 227 | |
| 228 | * On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and |
| 229 | :file:`/usr/tmp`, in that order. |
| 230 | |
| 231 | #. As a last resort, the current working directory. |
| 232 | |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 233 | The result of this search is cached, see the description of |
| 234 | :data:`tempdir` below. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 235 | |
Gregory P. Smith | ad577b9 | 2015-05-22 16:18:14 -0700 | [diff] [blame] | 236 | .. function:: gettempdirb() |
| 237 | |
| 238 | Same as :func:`gettempdir` but the return value is in bytes. |
| 239 | |
| 240 | .. versionadded:: 3.5 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 241 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 242 | .. function:: gettempprefix() |
| 243 | |
| 244 | Return the filename prefix used to create temporary files. This does not |
Georg Brandl | 4b26ff8 | 2008-08-04 07:24:52 +0000 | [diff] [blame] | 245 | contain the directory component. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 246 | |
Gregory P. Smith | ad577b9 | 2015-05-22 16:18:14 -0700 | [diff] [blame] | 247 | .. function:: gettempprefixb() |
| 248 | |
Martin Panter | 9b566c3 | 2015-11-07 00:32:50 +0000 | [diff] [blame] | 249 | Same as :func:`gettempprefix` but the return value is in bytes. |
Gregory P. Smith | ad577b9 | 2015-05-22 16:18:14 -0700 | [diff] [blame] | 250 | |
| 251 | .. versionadded:: 3.5 |
| 252 | |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 253 | The module uses a global variable to store the name of the directory |
| 254 | used for temporary files returned by :func:`gettempdir`. It can be |
| 255 | set directly to override the selection process, but this is discouraged. |
| 256 | All functions in this module take a *dir* argument which can be used |
Jelle Zijlstra | d3b8f98 | 2017-03-11 09:34:55 -0800 | [diff] [blame] | 257 | to specify the directory and this is the recommended approach. |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 258 | |
| 259 | .. data:: tempdir |
| 260 | |
| 261 | When set to a value other than ``None``, this variable defines the |
Jelle Zijlstra | d3b8f98 | 2017-03-11 09:34:55 -0800 | [diff] [blame] | 262 | default value for the *dir* argument to the functions defined in this |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 263 | module. |
| 264 | |
Srinivas Reddy Thatiparthy (శ్రీనివాస్ రెడ్డి తాటిపర్తి) | 940ae60 | 2018-06-21 13:22:43 +0530 | [diff] [blame] | 265 | If ``tempdir`` is ``None`` (the default) at any call to any of the above |
Martin Panter | 8f26565 | 2016-04-19 04:03:41 +0000 | [diff] [blame] | 266 | functions except :func:`gettempprefix` it is initialized following the |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 267 | algorithm described in :func:`gettempdir`. |
| 268 | |
| 269 | .. _tempfile-examples: |
Nick Coghlan | 543af75 | 2010-10-24 11:23:25 +0000 | [diff] [blame] | 270 | |
| 271 | Examples |
| 272 | -------- |
| 273 | |
| 274 | Here are some examples of typical usage of the :mod:`tempfile` module:: |
| 275 | |
| 276 | >>> import tempfile |
| 277 | |
| 278 | # create a temporary file and write some data to it |
| 279 | >>> fp = tempfile.TemporaryFile() |
Ross Lagerwall | 810b94a | 2011-04-10 09:30:04 +0200 | [diff] [blame] | 280 | >>> fp.write(b'Hello world!') |
Nick Coghlan | 543af75 | 2010-10-24 11:23:25 +0000 | [diff] [blame] | 281 | # read data from file |
| 282 | >>> fp.seek(0) |
| 283 | >>> fp.read() |
Ross Lagerwall | 810b94a | 2011-04-10 09:30:04 +0200 | [diff] [blame] | 284 | b'Hello world!' |
Nick Coghlan | 543af75 | 2010-10-24 11:23:25 +0000 | [diff] [blame] | 285 | # close the file, it will be removed |
| 286 | >>> fp.close() |
| 287 | |
| 288 | # create a temporary file using a context manager |
| 289 | >>> with tempfile.TemporaryFile() as fp: |
Ross Lagerwall | 810b94a | 2011-04-10 09:30:04 +0200 | [diff] [blame] | 290 | ... fp.write(b'Hello world!') |
Nick Coghlan | 543af75 | 2010-10-24 11:23:25 +0000 | [diff] [blame] | 291 | ... fp.seek(0) |
| 292 | ... fp.read() |
Ross Lagerwall | 810b94a | 2011-04-10 09:30:04 +0200 | [diff] [blame] | 293 | b'Hello world!' |
Nick Coghlan | 543af75 | 2010-10-24 11:23:25 +0000 | [diff] [blame] | 294 | >>> |
| 295 | # file is now closed and removed |
| 296 | |
| 297 | # create a temporary directory using the context manager |
| 298 | >>> with tempfile.TemporaryDirectory() as tmpdirname: |
Ross Lagerwall | 810b94a | 2011-04-10 09:30:04 +0200 | [diff] [blame] | 299 | ... print('created temporary directory', tmpdirname) |
Nick Coghlan | 543af75 | 2010-10-24 11:23:25 +0000 | [diff] [blame] | 300 | >>> |
| 301 | # directory and contents have been removed |
| 302 | |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 303 | |
| 304 | Deprecated functions and variables |
| 305 | ---------------------------------- |
| 306 | |
| 307 | A historical way to create temporary files was to first generate a |
| 308 | file name with the :func:`mktemp` function and then create a file |
| 309 | using this name. Unfortunately this is not secure, because a different |
| 310 | process may create a file with this name in the time between the call |
| 311 | to :func:`mktemp` and the subsequent attempt to create the file by the |
| 312 | first process. The solution is to combine the two steps and create the |
| 313 | file immediately. This approach is used by :func:`mkstemp` and the |
| 314 | other functions described above. |
| 315 | |
| 316 | .. function:: mktemp(suffix='', prefix='tmp', dir=None) |
| 317 | |
| 318 | .. deprecated:: 2.3 |
| 319 | Use :func:`mkstemp` instead. |
| 320 | |
| 321 | Return an absolute pathname of a file that did not exist at the time the |
Martin Panter | 9b566c3 | 2015-11-07 00:32:50 +0000 | [diff] [blame] | 322 | call is made. The *prefix*, *suffix*, and *dir* arguments are similar |
| 323 | to those of :func:`mkstemp`, except that bytes file names, ``suffix=None`` |
| 324 | and ``prefix=None`` are not supported. |
Robert Collins | 2ebdc13 | 2015-08-13 11:38:02 +1200 | [diff] [blame] | 325 | |
| 326 | .. warning:: |
| 327 | |
| 328 | Use of this function may introduce a security hole in your program. By |
| 329 | the time you get around to doing anything with the file name it returns, |
| 330 | someone else may have beaten you to the punch. :func:`mktemp` usage can |
| 331 | be replaced easily with :func:`NamedTemporaryFile`, passing it the |
| 332 | ``delete=False`` parameter:: |
| 333 | |
| 334 | >>> f = NamedTemporaryFile(delete=False) |
| 335 | >>> f.name |
| 336 | '/tmp/tmptjujjt' |
| 337 | >>> f.write(b"Hello World!\n") |
| 338 | 13 |
| 339 | >>> f.close() |
| 340 | >>> os.unlink(f.name) |
| 341 | >>> os.path.exists(f.name) |
| 342 | False |