Doc/library/tempfile.rst

   1
   2 :mod:`tempfile` --- Generate temporary files and directories
   3 ============================================================
   4
   5 .. sectionauthor:: Zack Weinberg <zack@codesourcery.com>
   6
   7
   8 .. module:: tempfile
   9    :synopsis: Generate temporary files and directories.
  10
  11
  12 .. index::
  13    pair: temporary; file name
  14    pair: temporary; file
  15
  16 This module generates temporary files and directories.  It works on all
  17 supported platforms.
  18
  19 In version 2.3 of Python, this module was overhauled for enhanced security.  It
  20 now provides three new functions, :func:`NamedTemporaryFile`, :func:`mkstemp`,
  21 and :func:`mkdtemp`, which should eliminate all remaining need to use the
  22 insecure :func:`mktemp` function.  Temporary file names created by this module
  23 no longer contain the process ID; instead a string of six random characters is
  24 used.
  25
  26 Also, all the user-callable functions now take additional arguments which
  27 allow direct control over the location and name of temporary files.  It is
  28 no longer necessary to use the global *tempdir* and *template* variables.
  29 To maintain backward compatibility, the argument order is somewhat odd; it
  30 is recommended to use keyword arguments for clarity.
  31
  32 The module defines the following user-callable functions:
  33
  34
  35 .. function:: TemporaryFile([mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None]]]]])
  36
  37    Return a file-like object that can be used as a temporary storage area.
  38    The file is created using :func:`mkstemp`. It will be destroyed as soon
  39    as it is closed (including an implicit close when the object is garbage
  40    collected).  Under Unix, the directory entry for the file is removed
  41    immediately after the file is created.  Other platforms do not support
  42    this; your code should not rely on a temporary file created using this
  43    function having or not having a visible name in the file system.
  44
  45    The *mode* parameter defaults to ``'w+b'`` so that the file created can
  46    be read and written without being closed.  Binary mode is used so that it
  47    behaves consistently on all platforms without regard for the data that is
  48    stored.  *bufsize* defaults to ``-1``, meaning that the operating system
  49    default is used.
  50
  51    The *dir*, *prefix* and *suffix* parameters are passed to :func:`mkstemp`.
  52
  53    The returned object is a true file object on POSIX platforms.  On other
  54    platforms, it is a file-like object whose :attr:`file` attribute is the
  55    underlying true file object. This file-like object can be used in a
  56    :keyword:`with` statement, just like a normal file.
  57
  58
  59 .. function:: NamedTemporaryFile([mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None[, delete=True]]]]]])
  60
  61    This function operates exactly as :func:`TemporaryFile` does, except that
  62    the file is guaranteed to have a visible name in the file system (on
  63    Unix, the directory entry is not unlinked).  That name can be retrieved
  64    from the :attr:`name` member of the file object.  Whether the name can be
  65    used to open the file a second time, while the named temporary file is
  66    still open, varies across platforms (it can be so used on Unix; it cannot
  67    on Windows NT or later).  If *delete* is true (the default), the file is
  68    deleted as soon as it is closed.
  69
  70    The returned object is always a file-like object whose :attr:`file`
  71    attribute is the underlying true file object. This file-like object can
  72    be used in a :keyword:`with` statement, just like a normal file.
  73
  74    .. versionadded:: 2.3
  75
  76    .. versionadded:: 2.6
  77       The *delete* parameter.
  78
  79
  80 .. function:: SpooledTemporaryFile([max_size=0, [mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None]]]]]])
  81
  82    This function operates exactly as :func:`TemporaryFile` does, except that
  83    data is spooled in memory until the file size exceeds *max_size*, or
  84    until the file's :func:`fileno` method is called, at which point the
  85    contents are written to disk and operation proceeds as with
  86    :func:`TemporaryFile`.
  87
  88    The resulting file has one additional method, :func:`rollover`, which
  89    causes the file to roll over to an on-disk file regardless of its size.
  90
  91    The returned object is a file-like object whose :attr:`_file` attribute
  92    is either a :class:`StringIO` object or a true file object, depending on
  93    whether :func:`rollover` has been called. This file-like object can be
  94    used in a :keyword:`with` statement, just like a normal file.
  95
  96    .. versionadded:: 2.6
  97
  98
  99 .. function:: mkstemp([suffix=''[, prefix='tmp'[, dir=None[, text=False]]]])
 100
 101    Creates a temporary file in the most secure manner possible.  There are
 102    no race conditions in the file's creation, assuming that the platform
 103    properly implements the :const:`os.O_EXCL` flag for :func:`os.open`.  The
 104    file is readable and writable only by the creating user ID.  If the
 105    platform uses permission bits to indicate whether a file is executable,
 106    the file is executable by no one.  The file descriptor is not inherited
 107    by child processes.
 108
 109    Unlike :func:`TemporaryFile`, the user of :func:`mkstemp` is responsible
 110    for deleting the temporary file when done with it.
 111
 112    If *suffix* is specified, the file name will end with that suffix,
 113    otherwise there will be no suffix.  :func:`mkstemp` does not put a dot
 114    between the file name and the suffix; if you need one, put it at the
 115    beginning of *suffix*.
 116
 117    If *prefix* is specified, the file name will begin with that prefix;
 118    otherwise, a default prefix is used.
 119
 120    If *dir* is specified, the file will be created in that directory;
 121    otherwise, a default directory is used.  The default directory is chosen
 122    from a platform-dependent list, but the user of the application can
 123    control the directory location by setting the *TMPDIR*, *TEMP* or *TMP*
 124    environment variables.  There is thus no guarantee that the generated
 125    filename will have any nice properties, such as not requiring quoting
 126    when passed to external commands via ``os.popen()``.
 127
 128    If *text* is specified, it indicates whether to open the file in binary
 129    mode (the default) or text mode.  On some platforms, this makes no
 130    difference.
 131
 132    :func:`mkstemp` returns a tuple containing an OS-level handle to an open
 133    file (as would be returned by :func:`os.open`) and the absolute pathname
 134    of that file, in that order.
 135
 136    .. versionadded:: 2.3
 137
 138
 139 .. function:: mkdtemp([suffix=''[, prefix='tmp'[, dir=None]]])
 140
 141    Creates a temporary directory in the most secure manner possible. There
 142    are no race conditions in the directory's creation.  The directory is
 143    readable, writable, and searchable only by the creating user ID.
 144
 145    The user of :func:`mkdtemp` is responsible for deleting the temporary
 146    directory and its contents when done with it.
 147
 148    The *prefix*, *suffix*, and *dir* arguments are the same as for
 149    :func:`mkstemp`.
 150
 151    :func:`mkdtemp` returns the absolute pathname of the new directory.
 152
 153    .. versionadded:: 2.3
 154
 155
 156 .. function:: mktemp([suffix=''[, prefix='tmp'[, dir=None]]])
 157
 158    .. deprecated:: 2.3
 159       Use :func:`mkstemp` instead.
 160
 161    Return an absolute pathname of a file that did not exist at the time the
 162    call is made.  The *prefix*, *suffix*, and *dir* arguments are the same
 163    as for :func:`mkstemp`.
 164
 165    .. warning::
 166
 167       Use of this function may introduce a security hole in your program.  By
 168       the time you get around to doing anything with the file name it returns,
 169       someone else may have beaten you to the punch.  :func:`mktemp` usage can
 170       be replaced easily with :func:`NamedTemporaryFile`, passing it the
 171       ``delete=False`` parameter::
 172
 173          >>> f = NamedTemporaryFile(delete=False)
 174          >>> f
 175          <open file '<fdopen>', mode 'w+b' at 0x384698>
 176          >>> f.name
 177          '/var/folders/5q/5qTPn6xq2RaWqk+1Ytw3-U+++TI/-Tmp-/tmpG7V1Y0'
 178          >>> f.write("Hello World!\n")
 179          >>> f.close()
 180          >>> os.unlink(f.name)
 181          >>> os.path.exists(f.name)
 182          False
 183
 184 The module uses two global variables that tell it how to construct a
 185 temporary name.  They are initialized at the first call to any of the
 186 functions above.  The caller may change them, but this is discouraged; use
 187 the appropriate function arguments, instead.
 188
 189
 190 .. data:: tempdir
 191
 192    When set to a value other than ``None``, this variable defines the
 193    default value for the *dir* argument to all the functions defined in this
 194    module.
 195
 196    If ``tempdir`` is unset or ``None`` at any call to any of the above
 197    functions, Python searches a standard list of directories and sets
 198    *tempdir* to the first one which the calling user can create files in.
 199    The list is:
 200
 201    #. The directory named by the :envvar:`TMPDIR` environment variable.
 202
 203    #. The directory named by the :envvar:`TEMP` environment variable.
 204
 205    #. The directory named by the :envvar:`TMP` environment variable.
 206
 207    #. A platform-specific location:
 208
 209       * On RiscOS, the directory named by the :envvar:`Wimp$ScrapDir` environment
 210         variable.
 211
 212       * On Windows, the directories :file:`C:\\TEMP`, :file:`C:\\TMP`,
 213         :file:`\\TEMP`, and :file:`\\TMP`, in that order.
 214
 215       * On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and
 216         :file:`/usr/tmp`, in that order.
 217
 218    #. As a last resort, the current working directory.
 219
 220
 221 .. function:: gettempdir()
 222
 223    Return the directory currently selected to create temporary files in. If
 224    :data:`tempdir` is not ``None``, this simply returns its contents; otherwise,
 225    the search described above is performed, and the result returned.
 226
 227    .. versionadded:: 2.3
 228
 229
 230 .. data:: template
 231
 232    .. deprecated:: 2.0
 233       Use :func:`gettempprefix` instead.
 234
 235    When set to a value other than ``None``, this variable defines the prefix of the
 236    final component of the filenames returned by :func:`mktemp`.  A string of six
 237    random letters and digits is appended to the prefix to make the filename unique.
 238    The default prefix is :file:`tmp`.
 239
 240    Older versions of this module used to require that ``template`` be set to
 241    ``None`` after a call to :func:`os.fork`; this has not been necessary since
 242    version 1.5.2.
 243
 244
 245 .. function:: gettempprefix()
 246
 247    Return the filename prefix used to create temporary files.  This does not
 248    contain the directory component.  Using this function is preferred over reading
 249    the *template* variable directly.
 250
 251    .. versionadded:: 1.5.2
 252