Doc/lib/libtempfile.tex

   1 \section{\module{tempfile} ---
   2          Generate temporary file names}
   3
   4 \declaremodule{standard}{tempfile}
   5 \modulesynopsis{Generate temporary file names.}
   6
   7 \indexii{temporary}{file name}
   8 \indexii{temporary}{file}
   9
  10
  11 This module generates temporary file names.  It is not \UNIX{} specific,
  12 but it may require some help on non-\UNIX{} systems.
  13
  14 The module defines the following user-callable functions:
  15
  16 \begin{funcdesc}{mktemp}{\optional{suffix}}
  17 Return a unique temporary filename.  This is an absolute pathname of a
  18 file that does not exist at the time the call is made.  No two calls
  19 will return the same filename.  \var{suffix}, if provided, is used as
  20 the last part of the generated file name.  This can be used to provide
  21 a filename extension or other identifying information that may be
  22 useful on some platforms.
  23 \end{funcdesc}
  24
  25 \begin{funcdesc}{TemporaryFile}{\optional{mode\optional{,
  26                                 bufsize\optional{, suffix}}}}
  27 Return a file (or file-like) object that can be used as a temporary
  28 storage area.  The file is created in the most secure manner available
  29 in the appropriate temporary directory for the host platform.  Under
  30 \UNIX, the directory entry to the file is removed so that it is secure
  31 against attacks which involve creating symbolic links to the file or
  32 replacing the file with a symbolic link to some other file.  For other
  33 platforms, which don't allow removing the directory entry while the
  34 file is in use, the file is automatically deleted as soon as it is
  35 closed (including an implicit close when it is garbage-collected).
  36
  37 The \var{mode} parameter defaults to \code{'w+b'} so that the file
  38 created can be read and written without being closed.  Binary mode is
  39 used so that it behaves consistently on all platforms without regard
  40 for the data that is stored.  \var{bufsize} defaults to \code{-1},
  41 meaning that the operating system default is used.  \var{suffix} is
  42 passed to \function{mktemp()}.
  43 \end{funcdesc}
  44
  45 The module uses two global variables that tell it how to construct a
  46 temporary name.  The caller may assign values to them; by default they
  47 are initialized at the first call to \function{mktemp()}.
  48
  49 \begin{datadesc}{tempdir}
  50 When set to a value other than \code{None}, this variable defines the
  51 directory in which filenames returned by \function{mktemp()} reside.
  52 The default is taken from the environment variable \envvar{TMPDIR}; if
  53 this is not set, either \file{/usr/tmp} is used (on \UNIX{}), or the
  54 current working directory (all other systems).  No check is made to
  55 see whether its value is valid.
  56 \end{datadesc}
  57
  58 \begin{funcdesc}{gettempprefix}{}
  59 Return the filename prefix used to create temporary files.  This does
  60 not contain the directory component.  Using this function is preferred
  61 over using the \code{template} variable directly.
  62 \versionadded{1.5.2}
  63 \end{funcdesc}
  64
  65 \begin{datadesc}{template}
  66 \deprecated{2.0}{Use \function{gettempprefix()} instead.}
  67 When set to a value other than \code{None}, this variable defines the
  68 prefix of the final component of the filenames returned by
  69 \function{mktemp()}.  A string of decimal digits is added to generate
  70 unique filenames.  The default is either \file{@\var{pid}.} where
  71 \var{pid} is the current process ID (on \UNIX{}),
  72 \file{\textasciitilde\var{pid}-} on Windows NT, \file{Python-Tmp-} on
  73 MacOS, or \file{tmp} (all other systems).
  74
  75 Older versions of this module used to require that \code{template} be
  76 set to \code{None} after a call to \function{os.fork()}; this has not
  77 been necessary since version 1.5.2.
  78 \end{datadesc}