Doc/lib/libtempfile.tex

   1 \section{\module{tempfile} ---
   2          Generate temporary files and directories}
   3 \sectionauthor{Zack Weinberg}{zack@codesourcery.com}
   4
   5 \declaremodule{standard}{tempfile}
   6 \modulesynopsis{Generate temporary files and directories.}
   7
   8 \indexii{temporary}{file name}
   9 \indexii{temporary}{file}
  10
  11 This module generates temporary files and directories.  It works on
  12 all supported platforms.
  13
  14 In version 2.3 of Python, this module was overhauled for enhanced
  15 security.  It now provides three new functions,
  16 \function{NamedTemporaryFile}, \function{mkstemp}, and
  17 \function{mkdtemp}, which should eliminate all remaining need to use
  18 the insecure \function{mktemp} function.  Temporary file names created
  19 by this module no longer contain the process ID; instead a string of
  20 six random characters is used.
  21
  22 Also, all the user-callable functions now take additional arguments
  23 which allow direct control over the location and name of temporary
  24 files.  It is no longer necessary to use the global \var{tempdir} and
  25 \var{template} variables.  To maintain backward compatibility, the
  26 argument order is somewhat odd; it is recommended to use keyword
  27 arguments for clarity.
  28
  29 The module defines the following user-callable functions:
  30
  31 \begin{funcdesc}{TemporaryFile}{\optional{mode='w+b'}
  32                                 \optional{, bufsize=-1}
  33                                 \optional{, suffix}
  34                                 \optional{, prefix}
  35                                 \optional{, dir}}
  36 Return a file (or file-like) object that can be used as a temporary
  37 storage area.  The file is created using \function{mkstemp}. It will
  38 be destroyed as soon as it is closed (including an implicit close when
  39 the object is garbage collected).  Under \UNIX, the directory entry
  40 for the file is removed immediately after the file is created.  Other
  41 platforms do not support this; your code should not rely on a
  42 \class{TemporaryFile} having or not having a visible name in the file
  43 system.
  44
  45 The \var{mode} parameter defaults to \code{'w+b'} so that the file
  46 created can be read and written without being closed.  Binary mode is
  47 used so that it behaves consistently on all platforms without regard
  48 for the data that is stored.  \var{bufsize} defaults to \code{-1},
  49 meaning that the operating system default is used.
  50
  51 The \var{dir}, \var{prefix} and \var{suffix} parameters are passed to
  52 \function{mkstemp}.
  53 \end{funcdesc}
  54
  55 \begin{funcdesc}{NamedTemporaryFile}{\optional{mode='w+b'}
  56                                      \optional{, bufsize=-1}
  57                                      \optional{, suffix}
  58                                      \optional{, prefix}
  59                                      \optional{, dir}}
  60 This function operates exactly as \function{TemporaryFile} does,
  61 except that the file is guaranteed to have a visible name in the file
  62 system (on \UNIX, the directory entry is not unlinked).  That name can
  63 be retrieved from the \member{name} member of the file object.  Whether
  64 the name can be used to open the file a second time, while the
  65 named temporary file is still open, varies across platforms (it can
  66 be so used on \UNIX; it cannot on Windows NT or later).
  67 \versionadded{2.3}
  68 \end{funcdesc}
  69
  70 \begin{funcdesc}{mkstemp}{\optional{suffix}
  71                           \optional{, prefix}
  72                           \optional{, dir}
  73                           \optional{, text=False}}
  74 Creates a temporary file in the most secure manner possible.  There
  75 are no race conditions in the file's creation, assuming that the
  76 platform properly implements the \constant{O_EXCL} flag for
  77 \function{os.open}.  The file is readable and writable only by the
  78 creating user ID.  If the platform uses permission bits to indicate
  79 whether a file is executable, the file is executable by no one.  The
  80 file descriptor is not inherited by child processes.
  81
  82 Unlike \function{TemporaryFile}, the user of \function{mkstemp} is
  83 responsible for deleting the temporary file when done with it.
  84
  85 If \var{suffix} is specified, the file name will end with that suffix,
  86 otherwise there will be no suffix.  \function{mkstemp} does not put a
  87 dot between the file name and the suffix; if you need one, put it at
  88 the beginning of \var{suffix}.
  89
  90 If \var{prefix} is specified, the file name will begin with that
  91 prefix; otherwise, a default prefix is used.
  92
  93 If \var{dir} is specified, the file will be created in that directory;
  94 otherwise, a default directory is used.
  95
  96 If \var{text} is specified, it indicates whether to open the file in
  97 binary mode (the default) or text mode.  On some platforms, this makes
  98 no difference.
  99
 100 \function{mkstemp} returns a tuple containing an OS-level handle to
 101 an open file (as would be returned by \function{os.open}) and the
 102 absolute pathname of that file, in that order.
 103 \versionadded{2.3}
 104 \end{funcdesc}
 105
 106 \begin{funcdesc}{mkdtemp}{\optional{suffix}
 107                           \optional{, prefix}
 108                           \optional{, dir}}
 109 Creates a temporary directory in the most secure manner possible.
 110 There are no race conditions in the directory's creation.  The
 111 directory is readable, writable, and searchable only by the
 112 creating user ID.
 113
 114 The user of \function{mkdtemp} is responsible for deleting the
 115 temporary directory and its contents when done with it.
 116
 117 The \var{prefix}, \var{suffix}, and \var{dir} arguments are the same
 118 as for \function{mkstemp}.
 119
 120 \function{mkdtemp} returns the absolute pathname of the new directory.
 121 \versionadded{2.3}
 122 \end{funcdesc}
 123
 124 \begin{funcdesc}{mktemp}{\optional{suffix}
 125                          \optional{, prefix}
 126                          \optional{, dir}}
 127 \deprecated{2.3}{Use \function{mkstemp()} instead.}
 128 Return an absolute pathname of a file that did not exist at the time
 129 the call is made.  The \var{prefix}, \var{suffix}, and \var{dir}
 130 arguments are the same as for \function{mkstemp}.
 131
 132 \warning{Use of this function may introduce a security hole in your
 133 program.  By the time you get around to doing anything with the file
 134 name it returns, someone else may have beaten you to the punch.}
 135 \end{funcdesc}
 136
 137 The module uses two global variables that tell it how to construct a
 138 temporary name.  They are initialized at the first call to any of the
 139 functions above.  The caller may change them, but this is discouraged;
 140 use the appropriate function arguments, instead.
 141
 142 \begin{datadesc}{tempdir}
 143 When set to a value other than \code{None}, this variable defines the
 144 default value for the \var{dir} argument to all the functions defined
 145 in this module.
 146
 147 If \var{tempdir} is unset or \code{None} at any call to any of the
 148 above functions, Python searches a standard list of directories and
 149 sets \var{tempdir} to the first one which the calling user can create
 150 files in.  The list is:
 151
 152 \begin{enumerate}
 153 \item The directory named by the \envvar{TMPDIR} environment variable.
 154 \item The directory named by the \envvar{TEMP} environment variable.
 155 \item The directory named by the \envvar{TMP} environment variable.
 156 \item A platform-specific location:
 157     \begin{itemize}
 158     \item On Macintosh, the \file{Temporary Items} folder.
 159     \item On RiscOS, the directory named by the
 160           \envvar{Wimp\$ScrapDir} environment variable.
 161     \item On Windows, the directories
 162           \file{C:$\backslash$TEMP},
 163           \file{C:$\backslash$TMP},
 164           \file{$\backslash$TEMP}, and
 165           \file{$\backslash$TMP}, in that order.
 166     \item On all other platforms, the directories
 167           \file{/tmp}, \file{/var/tmp}, and \file{/usr/tmp}, in that order.
 168     \end{itemize}
 169 \item As a last resort, the current working directory.
 170 \end{enumerate}
 171 \end{datadesc}
 172
 173 \begin{funcdesc}{gettempdir}{}
 174 Return the directory currently selected to create temporary files in.
 175 If \var{tempdir} is not None, this simply returns its contents;
 176 otherwise, the search described above is performed, and the result
 177 returned.
 178 \end{funcdesc}
 179
 180 \begin{datadesc}{template}
 181 \deprecated{2.0}{Use \function{gettempprefix()} instead.}
 182 When set to a value other than \code{None}, this variable defines the
 183 prefix of the final component of the filenames returned by
 184 \function{mktemp()}.  A string of six random letters and digits is
 185 appended to the prefix to make the filename unique.  On Windows,
 186 the default prefix is \file{\textasciitilde{}T}; on all other systems
 187 it is \file{tmp}.
 188
 189 Older versions of this module used to require that \code{template} be
 190 set to \code{None} after a call to \function{os.fork()}; this has not
 191 been necessary since version 1.5.2.
 192 \end{datadesc}
 193
 194 \begin{funcdesc}{gettempprefix}{}
 195 Return the filename prefix used to create temporary files.  This does
 196 not contain the directory component.  Using this function is preferred
 197 over reading the \var{template} variable directly.
 198 \versionadded{1.5.2}
 199 \end{funcdesc}