Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libtempfile.tex @ 27998:e27f58a50737 legacy-trunk

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