mirror of
https://github.com/python/cpython.git
synced 2025-11-03 19:34:08 +00:00
190 lines
8.3 KiB
TeX
190 lines
8.3 KiB
TeX
\section{\module{tempfile} ---
|
|
Generate temporary files and directories}
|
|
\sectionauthor{Zack Weinberg}{zack@codesourcery.com}
|
|
|
|
\declaremodule{standard}{tempfile}
|
|
\modulesynopsis{Generate temporary files and directories.}
|
|
|
|
\indexii{temporary}{file name}
|
|
\indexii{temporary}{file}
|
|
|
|
This module generates temporary files and directories. It works on
|
|
all supported platforms.
|
|
|
|
In version 2.3 of Python, this module was overhauled for enhanced
|
|
security. It now provides three new functions,
|
|
\function{NamedTemporaryFile()}, \function{mkstemp()}, and
|
|
\function{mkdtemp()}, which should eliminate all remaining need to use
|
|
the insecure \function{mktemp()} function. Temporary file names created
|
|
by this module no longer contain the process ID; instead a string of
|
|
six random characters is used.
|
|
|
|
Also, all the user-callable functions now take additional arguments
|
|
which allow direct control over the location and name of temporary
|
|
files. It is no longer necessary to use the global \var{tempdir} and
|
|
\var{template} variables. To maintain backward compatibility, the
|
|
argument order is somewhat odd; it is recommended to use keyword
|
|
arguments for clarity.
|
|
|
|
The module defines the following user-callable functions:
|
|
|
|
\begin{funcdesc}{TemporaryFile}{\optional{mode=\code{'w+b'}\optional{,
|
|
bufsize=\code{-1}\optional{,
|
|
suffix\optional{, prefix\optional{, dir}}}}}}
|
|
Return a file (or file-like) object that can be used as a temporary
|
|
storage area. The file is created using \function{mkstemp}. It will
|
|
be destroyed as soon as it is closed (including an implicit close when
|
|
the object is garbage collected). Under \UNIX, the directory entry
|
|
for the file is removed immediately after the file is created. Other
|
|
platforms do not support this; your code should not rely on a
|
|
temporary file created using this function having or not having a
|
|
visible name in the file system.
|
|
|
|
The \var{mode} parameter defaults to \code{'w+b'} so that the file
|
|
created can be read and written without being closed. Binary mode is
|
|
used so that it behaves consistently on all platforms without regard
|
|
for the data that is stored. \var{bufsize} defaults to \code{-1},
|
|
meaning that the operating system default is used.
|
|
|
|
The \var{dir}, \var{prefix} and \var{suffix} parameters are passed to
|
|
\function{mkstemp()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{NamedTemporaryFile}{\optional{mode=\code{'w+b'}\optional{,
|
|
bufsize=\code{-1}\optional{,
|
|
suffix\optional{, prefix\optional{,
|
|
dir}}}}}}
|
|
This function operates exactly as \function{TemporaryFile()} does,
|
|
except that the file is guaranteed to have a visible name in the file
|
|
system (on \UNIX, the directory entry is not unlinked). That name can
|
|
be retrieved from the \member{name} member of the file object. Whether
|
|
the name can be used to open the file a second time, while the
|
|
named temporary file is still open, varies across platforms (it can
|
|
be so used on \UNIX; it cannot on Windows NT or later).
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{mkstemp}{\optional{suffix\optional{,
|
|
prefix\optional{, dir\optional{, text}}}}}
|
|
Creates a temporary file in the most secure manner possible. There
|
|
are no race conditions in the file's creation, assuming that the
|
|
platform properly implements the \constant{O_EXCL} flag for
|
|
\function{os.open()}. The file is readable and writable only by the
|
|
creating user ID. If the platform uses permission bits to indicate
|
|
whether a file is executable, the file is executable by no one. The
|
|
file descriptor is not inherited by child processes.
|
|
|
|
Unlike \function{TemporaryFile()}, the user of \function{mkstemp()} is
|
|
responsible for deleting the temporary file when done with it.
|
|
|
|
If \var{suffix} is specified, the file name will end with that suffix,
|
|
otherwise there will be no suffix. \function{mkstemp()} does not put a
|
|
dot between the file name and the suffix; if you need one, put it at
|
|
the beginning of \var{suffix}.
|
|
|
|
If \var{prefix} is specified, the file name will begin with that
|
|
prefix; otherwise, a default prefix is used.
|
|
|
|
If \var{dir} is specified, the file will be created in that directory;
|
|
otherwise, a default directory is used.
|
|
|
|
If \var{text} is specified, it indicates whether to open the file in
|
|
binary mode (the default) or text mode. On some platforms, this makes
|
|
no difference.
|
|
|
|
\function{mkstemp()} returns a tuple containing an OS-level handle to
|
|
an open file (as would be returned by \function{os.open()}) and the
|
|
absolute pathname of that file, in that order.
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{mkdtemp}{\optional{suffix\optional{, prefix\optional{, dir}}}}
|
|
Creates a temporary directory in the most secure manner possible.
|
|
There are no race conditions in the directory's creation. The
|
|
directory is readable, writable, and searchable only by the
|
|
creating user ID.
|
|
|
|
The user of \function{mkdtemp()} is responsible for deleting the
|
|
temporary directory and its contents when done with it.
|
|
|
|
The \var{prefix}, \var{suffix}, and \var{dir} arguments are the same
|
|
as for \function{mkstemp()}.
|
|
|
|
\function{mkdtemp()} returns the absolute pathname of the new directory.
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{mktemp}{\optional{suffix\optional{, prefix\optional{, dir}}}}
|
|
\deprecated{2.3}{Use \function{mkstemp()} instead.}
|
|
Return an absolute pathname of a file that did not exist at the time
|
|
the call is made. The \var{prefix}, \var{suffix}, and \var{dir}
|
|
arguments are the same as for \function{mkstemp()}.
|
|
|
|
\warning{Use of this function may introduce a security hole in your
|
|
program. By the time you get around to doing anything with the file
|
|
name it returns, someone else may have beaten you to the punch.}
|
|
\end{funcdesc}
|
|
|
|
The module uses two global variables that tell it how to construct a
|
|
temporary name. They are initialized at the first call to any of the
|
|
functions above. The caller may change them, but this is discouraged;
|
|
use the appropriate function arguments, instead.
|
|
|
|
\begin{datadesc}{tempdir}
|
|
When set to a value other than \code{None}, this variable defines the
|
|
default value for the \var{dir} argument to all the functions defined
|
|
in this module.
|
|
|
|
If \code{tempdir} is unset or \code{None} at any call to any of the
|
|
above functions, Python searches a standard list of directories and
|
|
sets \var{tempdir} to the first one which the calling user can create
|
|
files in. The list is:
|
|
|
|
\begin{enumerate}
|
|
\item The directory named by the \envvar{TMPDIR} environment variable.
|
|
\item The directory named by the \envvar{TEMP} environment variable.
|
|
\item The directory named by the \envvar{TMP} environment variable.
|
|
\item A platform-specific location:
|
|
\begin{itemize}
|
|
\item On Macintosh, the \file{Temporary Items} folder.
|
|
\item On RiscOS, the directory named by the
|
|
\envvar{Wimp\$ScrapDir} environment variable.
|
|
\item On Windows, the directories
|
|
\file{C:$\backslash$TEMP},
|
|
\file{C:$\backslash$TMP},
|
|
\file{$\backslash$TEMP}, and
|
|
\file{$\backslash$TMP}, in that order.
|
|
\item On all other platforms, the directories
|
|
\file{/tmp}, \file{/var/tmp}, and \file{/usr/tmp}, in that order.
|
|
\end{itemize}
|
|
\item As a last resort, the current working directory.
|
|
\end{enumerate}
|
|
\end{datadesc}
|
|
|
|
\begin{funcdesc}{gettempdir}{}
|
|
Return the directory currently selected to create temporary files in.
|
|
If \code{tempdir} is not \code{None}, this simply returns its contents;
|
|
otherwise, the search described above is performed, and the result
|
|
returned.
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{template}
|
|
\deprecated{2.0}{Use \function{gettempprefix()} instead.}
|
|
When set to a value other than \code{None}, this variable defines the
|
|
prefix of the final component of the filenames returned by
|
|
\function{mktemp()}. A string of six random letters and digits is
|
|
appended to the prefix to make the filename unique. On Windows,
|
|
the default prefix is \file{\textasciitilde{}T}; on all other systems
|
|
it is \file{tmp}.
|
|
|
|
Older versions of this module used to require that \code{template} be
|
|
set to \code{None} after a call to \function{os.fork()}; this has not
|
|
been necessary since version 1.5.2.
|
|
\end{datadesc}
|
|
|
|
\begin{funcdesc}{gettempprefix}{}
|
|
Return the filename prefix used to create temporary files. This does
|
|
not contain the directory component. Using this function is preferred
|
|
over reading the \var{template} variable directly.
|
|
\versionadded{1.5.2}
|
|
\end{funcdesc}
|