Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libtempfile.tex @ 32527:0da660e05e69 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
"#if WITH_THREAD" is incorrect; must be #ifdef instead; WITH_THREAD isn't always set to an integer value when it's defined.
author Tim Peters <tim.peters@gmail.com>
date Wed, 07 Jul 2004 20:42:07 +0000
parents 68e1f86056bc
children 7e7e86f45255
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,
28730
ac58608cd23c markup corrections
Fred Drake <fdrake@acm.org>
parents: 26316
diff changeset
16 \function{NamedTemporaryFile()}, \function{mkstemp()}, and
ac58608cd23c markup corrections
Fred Drake <fdrake@acm.org>
parents: 26316
diff changeset
17 \function{mkdtemp()}, which should eliminate all remaining need to use
ac58608cd23c markup corrections
Fred Drake <fdrake@acm.org>
parents: 26316
diff changeset
18 the insecure \function{mktemp()} function. Temporary file names created
24709
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
30412
68e1f86056bc fix markup buglets
Fred Drake <fdrake@acm.org>
parents: 28730
diff changeset
31 \begin{funcdesc}{TemporaryFile}{\optional{mode=\code{'w+b'}\optional{,
68e1f86056bc fix markup buglets
Fred Drake <fdrake@acm.org>
parents: 28730
diff changeset
32 bufsize=\code{-1}\optional{,
68e1f86056bc fix markup buglets
Fred Drake <fdrake@acm.org>
parents: 28730
diff changeset
33 suffix\optional{, prefix\optional{, dir}}}}}}
12772
7a4f6402c67f Added documentation for TemporaryFile() and the siffix parameter to mktemp().
Fred Drake <fdrake@acm.org>
parents: 10650
diff changeset
34 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
35 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
36 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
37 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
38 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
39 platforms do not support this; your code should not rely on a
28730
ac58608cd23c markup corrections
Fred Drake <fdrake@acm.org>
parents: 26316
diff changeset
40 temporary file created using this function having or not having a
ac58608cd23c markup corrections
Fred Drake <fdrake@acm.org>
parents: 26316
diff changeset
41 visible name in the file system.
12772
7a4f6402c67f Added documentation for TemporaryFile() and the siffix parameter to mktemp().
Fred Drake <fdrake@acm.org>
parents: 10650
diff changeset
42
7a4f6402c67f Added documentation for TemporaryFile() and the siffix parameter to mktemp().
Fred Drake <fdrake@acm.org>
parents: 10650
diff changeset
43 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
44 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
45 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
46 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
47 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
48
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
49 The \var{dir}, \var{prefix} and \var{suffix} parameters are passed to
28730
ac58608cd23c markup corrections
Fred Drake <fdrake@acm.org>
parents: 26316
diff changeset
50 \function{mkstemp()}.
24709
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
51 \end{funcdesc}
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
52
30412
68e1f86056bc fix markup buglets
Fred Drake <fdrake@acm.org>
parents: 28730
diff changeset
53 \begin{funcdesc}{NamedTemporaryFile}{\optional{mode=\code{'w+b'}\optional{,
68e1f86056bc fix markup buglets
Fred Drake <fdrake@acm.org>
parents: 28730
diff changeset
54 bufsize=\code{-1}\optional{,
68e1f86056bc fix markup buglets
Fred Drake <fdrake@acm.org>
parents: 28730
diff changeset
55 suffix\optional{, prefix\optional{,
68e1f86056bc fix markup buglets
Fred Drake <fdrake@acm.org>
parents: 28730
diff changeset
56 dir}}}}}}
28730
ac58608cd23c markup corrections
Fred Drake <fdrake@acm.org>
parents: 26316
diff changeset
57 This function operates exactly as \function{TemporaryFile()} does,
24709
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
58 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
59 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
60 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
61 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
62 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
63 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
64 \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
65 \end{funcdesc}
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
66
30412
68e1f86056bc fix markup buglets
Fred Drake <fdrake@acm.org>
parents: 28730
diff changeset
67 \begin{funcdesc}{mkstemp}{\optional{suffix\optional{,
68e1f86056bc fix markup buglets
Fred Drake <fdrake@acm.org>
parents: 28730
diff changeset
68 prefix\optional{, dir\optional{, text}}}}}
24709
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
69 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
70 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
71 platform properly implements the \constant{O_EXCL} flag for
28730
ac58608cd23c markup corrections
Fred Drake <fdrake@acm.org>
parents: 26316
diff changeset
72 \function{os.open()}. The file is readable and writable only by the
24709
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
73 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
74 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
75 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
76
28730
ac58608cd23c markup corrections
Fred Drake <fdrake@acm.org>
parents: 26316
diff changeset
77 Unlike \function{TemporaryFile()}, the user of \function{mkstemp()} is
24709
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
78 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
79
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
80 If \var{suffix} is specified, the file name will end with that suffix,
28730
ac58608cd23c markup corrections
Fred Drake <fdrake@acm.org>
parents: 26316
diff changeset
81 otherwise there will be no suffix. \function{mkstemp()} does not put a
24709
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
82 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
83 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
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{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
86 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
87
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
88 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
89 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
90
24822
d3d7de703a22 mkstemp's last argument changed from binary=True to text=False.
Tim Peters <tim.peters@gmail.com>
parents: 24709
diff changeset
91 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
92 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
93 no difference.
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
94
28730
ac58608cd23c markup corrections
Fred Drake <fdrake@acm.org>
parents: 26316
diff changeset
95 \function{mkstemp()} returns a tuple containing an OS-level handle to
ac58608cd23c markup corrections
Fred Drake <fdrake@acm.org>
parents: 26316
diff changeset
96 an open file (as would be returned by \function{os.open()}) and the
24709
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
97 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
98 \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
99 \end{funcdesc}
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
100
30412
68e1f86056bc fix markup buglets
Fred Drake <fdrake@acm.org>
parents: 28730
diff changeset
101 \begin{funcdesc}{mkdtemp}{\optional{suffix\optional{, prefix\optional{, dir}}}}
24709
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
102 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
103 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
104 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
105 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
106
28730
ac58608cd23c markup corrections
Fred Drake <fdrake@acm.org>
parents: 26316
diff changeset
107 The user of \function{mkdtemp()} is responsible for deleting the
24709
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
108 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
109
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
110 The \var{prefix}, \var{suffix}, and \var{dir} arguments are the same
28730
ac58608cd23c markup corrections
Fred Drake <fdrake@acm.org>
parents: 26316
diff changeset
111 as for \function{mkstemp()}.
24709
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
112
28730
ac58608cd23c markup corrections
Fred Drake <fdrake@acm.org>
parents: 26316
diff changeset
113 \function{mkdtemp()} returns the absolute pathname of the new directory.
24709
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
114 \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
115 \end{funcdesc}
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
116
30412
68e1f86056bc fix markup buglets
Fred Drake <fdrake@acm.org>
parents: 28730
diff changeset
117 \begin{funcdesc}{mktemp}{\optional{suffix\optional{, prefix\optional{, dir}}}}
24709
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
118 \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
119 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
120 the call is made. The \var{prefix}, \var{suffix}, and \var{dir}
28730
ac58608cd23c markup corrections
Fred Drake <fdrake@acm.org>
parents: 26316
diff changeset
121 arguments are the same as for \function{mkstemp()}.
24709
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
122
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
123 \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
124 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
125 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
126 \end{funcdesc}
1c29f6bdd898 en weer twee!
Guido van Rossum <guido@python.org>
parents:
diff changeset
127
1c29f6bdd898 en weer twee!
Guido van Rossum <guido@python.org>
parents:
diff changeset
128 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
129 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
130 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
131 use the appropriate function arguments, instead.
2460
1c29f6bdd898 en weer twee!
Guido van Rossum <guido@python.org>
parents:
diff changeset
132
1c29f6bdd898 en weer twee!
Guido van Rossum <guido@python.org>
parents:
diff changeset
133 \begin{datadesc}{tempdir}
1c29f6bdd898 en weer twee!
Guido van Rossum <guido@python.org>
parents:
diff changeset
134 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
135 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
136 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
137
30412
68e1f86056bc fix markup buglets
Fred Drake <fdrake@acm.org>
parents: 28730
diff changeset
138 If \code{tempdir} is unset or \code{None} at any call to any of the
24709
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
139 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
140 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
141 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
142
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
143 \begin{enumerate}
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
144 \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
145 \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
146 \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
147 \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
148 \begin{itemize}
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
149 \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
150 \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
151 \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
152 \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
153 \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
154 \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
155 \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
156 \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
157 \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
158 \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
159 \end{itemize}
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
160 \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
161 \end{enumerate}
2460
1c29f6bdd898 en weer twee!
Guido van Rossum <guido@python.org>
parents:
diff changeset
162 \end{datadesc}
1c29f6bdd898 en weer twee!
Guido van Rossum <guido@python.org>
parents:
diff changeset
163
24709
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
164 \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
165 Return the directory currently selected to create temporary files in.
30412
68e1f86056bc fix markup buglets
Fred Drake <fdrake@acm.org>
parents: 28730
diff changeset
166 If \code{tempdir} is not \code{None}, this simply returns its contents;
24709
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
167 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
168 returned.
12774
40db909ce2e3 Added documentation for gettempprefix().
Fred Drake <fdrake@acm.org>
parents: 12772
diff changeset
169 \end{funcdesc}
40db909ce2e3 Added documentation for gettempprefix().
Fred Drake <fdrake@acm.org>
parents: 12772
diff changeset
170
2460
1c29f6bdd898 en weer twee!
Guido van Rossum <guido@python.org>
parents:
diff changeset
171 \begin{datadesc}{template}
13222
5dd381aeb23b Update version numbering from 1.6 to 2.0.
Fred Drake <fdrake@acm.org>
parents: 12774
diff changeset
172 \deprecated{2.0}{Use \function{gettempprefix()} instead.}
2460
1c29f6bdd898 en weer twee!
Guido van Rossum <guido@python.org>
parents:
diff changeset
173 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
174 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
175 \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
176 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
177 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
178 it is \file{tmp}.
12774
40db909ce2e3 Added documentation for gettempprefix().
Fred Drake <fdrake@acm.org>
parents: 12772
diff changeset
179
40db909ce2e3 Added documentation for gettempprefix().
Fred Drake <fdrake@acm.org>
parents: 12772
diff changeset
180 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
181 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
182 been necessary since version 1.5.2.
2460
1c29f6bdd898 en weer twee!
Guido van Rossum <guido@python.org>
parents:
diff changeset
183 \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
184
6c96587a197f Doc portion of SF 589982 (tempfile.py rewrite, by Zack Weinberg).
Guido van Rossum <guido@python.org>
parents: 21062
diff changeset
185 \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
186 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
187 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
188 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
189 \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
190 \end{funcdesc}