rest25/library/tempfile.rst => rest262/library/tempfile.rst
18
19In version 2.3 of Python, this module was overhauled for enhanced security.  It
20now provides three new functions, :func:`NamedTemporaryFile`, :func:`mkstemp`,
21and :func:`mkdtemp`, which should eliminate all remaining need to use the
22insecure :func:`mktemp` function.  Temporary file names created by this module
23no longer contain the process ID; instead a string of six random characters is
24used.
25
n26-Also, all the user-callable functions now take additional arguments which allow
n26+Also, all the user-callable functions now take additional arguments which
27-direct control over the location and name of temporary files.  It is no longer
27+allow direct control over the location and name of temporary files.  It is
28-necessary to use the global *tempdir* and *template* variables.  To maintain
28+no longer necessary to use the global *tempdir* and *template* variables.
29-backward compatibility, the argument order is somewhat odd; it is recommended to
29+To maintain backward compatibility, the argument order is somewhat odd; it
30-use keyword arguments for clarity.
30+is recommended to use keyword arguments for clarity.
31
32The module defines the following user-callable functions:
33
34
n35-.. function:: TemporaryFile([mode=``'w+b'``[, bufsize=``-1``[, suffix[, prefix[, dir]]]]])
n35+.. function:: TemporaryFile([mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None]]]]])
36
n37-   Return a file (or file-like) object that can be used as a temporary storage
n37+   Return a file-like object that can be used as a temporary storage area.
38-   area.  The file is created using :func:`mkstemp`. It will be destroyed as soon
38+   The file is created using :func:`mkstemp`. It will be destroyed as soon
39   as it is closed (including an implicit close when the object is garbage
n40-   collected).  Under Unix, the directory entry for the file is removed immediately
n40+   collected).  Under Unix, the directory entry for the file is removed
41-   after the file is created.  Other platforms do not support this; your code
41+   immediately after the file is created.  Other platforms do not support
42-   should not rely on a temporary file created using this function having or not
42+   this; your code should not rely on a temporary file created using this
43-   having a visible name in the file system.
43+   function having or not having a visible name in the file system.
44
n45-   The *mode* parameter defaults to ``'w+b'`` so that the file created can be read
n45+   The *mode* parameter defaults to ``'w+b'`` so that the file created can
46-   and written without being closed.  Binary mode is used so that it behaves
46+   be read and written without being closed.  Binary mode is used so that it
47-   consistently on all platforms without regard for the data that is stored.
47+   behaves consistently on all platforms without regard for the data that is
48-   *bufsize* defaults to ``-1``, meaning that the operating system default is used.
48+   stored.  *bufsize* defaults to ``-1``, meaning that the operating system
49+   default is used.
49
50   The *dir*, *prefix* and *suffix* parameters are passed to :func:`mkstemp`.
51
n53+   The returned object is a true file object on POSIX platforms.  On other
54+   platforms, it is a file-like object whose :attr:`file` attribute is the
55+   underlying true file object. This file-like object can be used in a
56+   :keyword:`with` statement, just like a normal file.
52
n58+ 
53-.. function:: NamedTemporaryFile([mode=``'w+b'``[, bufsize=``-1``[, suffix[, prefix[, dir]]]]])
59+.. function:: NamedTemporaryFile([mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None[, delete=True]]]]]])
54
n55-   This function operates exactly as :func:`TemporaryFile` does, except that the
n61+   This function operates exactly as :func:`TemporaryFile` does, except that
56-   file is guaranteed to have a visible name in the file system (on Unix, the
62+   the file is guaranteed to have a visible name in the file system (on
57-   directory entry is not unlinked).  That name can be retrieved from the
63+   Unix, the directory entry is not unlinked).  That name can be retrieved
58-   :attr:`name` member of the file object.  Whether the name can be used to open
64+   from the :attr:`name` member of the file object.  Whether the name can be
59-   the file a second time, while the named temporary file is still open, varies
65+   used to open the file a second time, while the named temporary file is
60-   across platforms (it can be so used on Unix; it cannot on Windows NT or later).
66+   still open, varies across platforms (it can be so used on Unix; it cannot
67+   on Windows NT or later).  If *delete* is true (the default), the file is
68+   deleted as soon as it is closed.
61
n70+   The returned object is always a file-like object whose :attr:`file`
71+   attribute is the underlying true file object. This file-like object can
72+   be used in a :keyword:`with` statement, just like a normal file.
73+ 
74+   .. versionadded:: 2.3
75+ 
62-   .. versionadded:: 2.3
76+   .. versionadded:: 2.6
77+      The *delete* parameter.
63
64
n80+.. function:: SpooledTemporaryFile([max_size=0, [mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None]]]]]])
81+ 
82+   This function operates exactly as :func:`TemporaryFile` does, except that
83+   data is spooled in memory until the file size exceeds *max_size*, or
84+   until the file's :func:`fileno` method is called, at which point the
85+   contents are written to disk and operation proceeds as with
86+   :func:`TemporaryFile`.
87+ 
88+   The resulting file has one additional method, :func:`rollover`, which
89+   causes the file to roll over to an on-disk file regardless of its size.
90+ 
91+   The returned object is a file-like object whose :attr:`_file` attribute
92+   is either a :class:`StringIO` object or a true file object, depending on
93+   whether :func:`rollover` has been called. This file-like object can be
94+   used in a :keyword:`with` statement, just like a normal file.
95+ 
96+   .. versionadded:: 2.6
97+ 
98+ 
65-.. function:: mkstemp([suffix[, prefix[, dir[, text]]]])
99+.. function:: mkstemp([suffix=''[, prefix='tmp'[, dir=None[, text=False]]]])
66
n67-   Creates a temporary file in the most secure manner possible.  There are no race
n101+   Creates a temporary file in the most secure manner possible.  There are
68-   conditions in the file's creation, assuming that the platform properly
102+   no race conditions in the file's creation, assuming that the platform
69-   implements the :const:`O_EXCL` flag for :func:`os.open`.  The file is readable
103+   properly implements the :const:`os.O_EXCL` flag for :func:`os.open`.  The
70-   and writable only by the creating user ID.  If the platform uses permission bits
104+   file is readable and writable only by the creating user ID.  If the
71-   to indicate whether a file is executable, the file is executable by no one.  The
105+   platform uses permission bits to indicate whether a file is executable,
72-   file descriptor is not inherited by child processes.
106+   the file is executable by no one.  The file descriptor is not inherited
107+   by child processes.
73
n74-   Unlike :func:`TemporaryFile`, the user of :func:`mkstemp` is responsible for
n109+   Unlike :func:`TemporaryFile`, the user of :func:`mkstemp` is responsible
75-   deleting the temporary file when done with it.
110+   for deleting the temporary file when done with it.
76
n77-   If *suffix* is specified, the file name will end with that suffix, otherwise
n112+   If *suffix* is specified, the file name will end with that suffix,
78-   there will be no suffix.  :func:`mkstemp` does not put a dot between the file
113+   otherwise there will be no suffix.  :func:`mkstemp` does not put a dot
79-   name and the suffix; if you need one, put it at the beginning of *suffix*.
114+   between the file name and the suffix; if you need one, put it at the
115+   beginning of *suffix*.
80
n81-   If *prefix* is specified, the file name will begin with that prefix; otherwise,
n117+   If *prefix* is specified, the file name will begin with that prefix;
82-   a default prefix is used.
118+   otherwise, a default prefix is used.
83
n84-   If *dir* is specified, the file will be created in that directory; otherwise, a
n120+   If *dir* is specified, the file will be created in that directory;
85-   default directory is used.
121+   otherwise, a default directory is used.  The default directory is chosen
122+   from a platform-dependent list, but the user of the application can
123+   control the directory location by setting the *TMPDIR*, *TEMP* or *TMP*
124+   environment variables.  There is thus no guarantee that the generated
125+   filename will have any nice properties, such as not requiring quoting
126+   when passed to external commands via ``os.popen()``.
86
n87-   If *text* is specified, it indicates whether to open the file in binary mode
n128+   If *text* is specified, it indicates whether to open the file in binary
88-   (the default) or text mode.  On some platforms, this makes no difference.
129+   mode (the default) or text mode.  On some platforms, this makes no
130+   difference.
89
n90-   :func:`mkstemp` returns a tuple containing an OS-level handle to an open file
n132+   :func:`mkstemp` returns a tuple containing an OS-level handle to an open
91-   (as would be returned by :func:`os.open`) and the absolute pathname of that
133+   file (as would be returned by :func:`os.open`) and the absolute pathname
92-   file, in that order.
134+   of that file, in that order.
93
94   .. versionadded:: 2.3
95
96
n97-.. function:: mkdtemp([suffix[, prefix[, dir]]])
n139+.. function:: mkdtemp([suffix=''[, prefix='tmp'[, dir=None]]])
98
n99-   Creates a temporary directory in the most secure manner possible. There are no
n141+   Creates a temporary directory in the most secure manner possible. There
100-   race conditions in the directory's creation.  The directory is readable,
142+   are no race conditions in the directory's creation.  The directory is
101-   writable, and searchable only by the creating user ID.
143+   readable, writable, and searchable only by the creating user ID.
102
n103-   The user of :func:`mkdtemp` is responsible for deleting the temporary directory
n145+   The user of :func:`mkdtemp` is responsible for deleting the temporary
104-   and its contents when done with it.
146+   directory and its contents when done with it.
105
n106-   The *prefix*, *suffix*, and *dir* arguments are the same as for :func:`mkstemp`.
n148+   The *prefix*, *suffix*, and *dir* arguments are the same as for
149+   :func:`mkstemp`.
107
108   :func:`mkdtemp` returns the absolute pathname of the new directory.
109
110   .. versionadded:: 2.3
111
112
n113-.. function:: mktemp([suffix[, prefix[, dir]]])
n156+.. function:: mktemp([suffix=''[, prefix='tmp'[, dir=None]]])
114
115   .. deprecated:: 2.3
116      Use :func:`mkstemp` instead.
117
n118-   Return an absolute pathname of a file that did not exist at the time the call is
n161+   Return an absolute pathname of a file that did not exist at the time the
119-   made.  The *prefix*, *suffix*, and *dir* arguments are the same as for
162+   call is made.  The *prefix*, *suffix*, and *dir* arguments are the same
120-   :func:`mkstemp`.
163+   as for :func:`mkstemp`.
121
122   .. warning::
123
n124-      Use of this function may introduce a security hole in your program.  By the time
n167+      Use of this function may introduce a security hole in your program.  By
125-      you get around to doing anything with the file name it returns, someone else may
168+      the time you get around to doing anything with the file name it returns,
126-      have beaten you to the punch.
169+      someone else may have beaten you to the punch.  :func:`mktemp` usage can
170+      be replaced easily with :func:`NamedTemporaryFile`, passing it the
171+      ``delete=False`` parameter::
127
n173+         >>> f = NamedTemporaryFile(delete=False)
174+         >>> f
175+         <open file '<fdopen>', mode 'w+b' at 0x384698>
176+         >>> f.name
177+         '/var/folders/5q/5qTPn6xq2RaWqk+1Ytw3-U+++TI/-Tmp-/tmpG7V1Y0'
178+         >>> f.write("Hello World!\n")
179+         >>> f.close()
180+         >>> os.unlink(f.name)
181+         >>> os.path.exists(f.name)
182+         False
183+ 
128-The module uses two global variables that tell it how to construct a temporary
184+The module uses two global variables that tell it how to construct a
129-name.  They are initialized at the first call to any of the functions above.
185+temporary name.  They are initialized at the first call to any of the
130-The caller may change them, but this is discouraged; use the appropriate
186+functions above.  The caller may change them, but this is discouraged; use
131-function arguments, instead.
187+the appropriate function arguments, instead.
132
133
134.. data:: tempdir
135
n136-   When set to a value other than ``None``, this variable defines the default value
n192+   When set to a value other than ``None``, this variable defines the
137-   for the *dir* argument to all the functions defined in this module.
193+   default value for the *dir* argument to all the functions defined in this
194+   module.
138
n139-   If ``tempdir`` is unset or ``None`` at any call to any of the above functions,
n196+   If ``tempdir`` is unset or ``None`` at any call to any of the above
140-   Python searches a standard list of directories and sets *tempdir* to the first
197+   functions, Python searches a standard list of directories and sets
141-   one which the calling user can create files in.  The list is:
198+   *tempdir* to the first one which the calling user can create files in.
199+   The list is:
142
n143-#. The directory named by the :envvar:`TMPDIR` environment variable.
n201+   #. The directory named by the :envvar:`TMPDIR` environment variable.
144
n145-#. The directory named by the :envvar:`TEMP` environment variable.
n203+   #. The directory named by the :envvar:`TEMP` environment variable.
146
n147-#. The directory named by the :envvar:`TMP` environment variable.
n205+   #. The directory named by the :envvar:`TMP` environment variable.
148
n149-#. A platform-specific location:
n207+   #. A platform-specific location:
150
n151-* On RiscOS, the directory named by the :envvar:`Wimp$ScrapDir` environment
n209+      * On RiscOS, the directory named by the :envvar:`Wimp$ScrapDir` environment
152        variable.
153
n154-* On Windows, the directories :file:`C:$\\TEMP`, :file:`C:$\\TMP`,
n212+      * On Windows, the directories :file:`C:\\TEMP`, :file:`C:\\TMP`,
155        :file:`\\TEMP`, and :file:`\\TMP`, in that order.
156
n157-* On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and
n215+      * On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and
158        :file:`/usr/tmp`, in that order.
159
n160-#. As a last resort, the current working directory.
n218+   #. As a last resort, the current working directory.
161
162
163.. function:: gettempdir()
164
165   Return the directory currently selected to create temporary files in. If
n166-   ``tempdir`` is not ``None``, this simply returns its contents; otherwise, the
n224+   :data:`tempdir` is not ``None``, this simply returns its contents; otherwise,
167-   search described above is performed, and the result returned.
225+   the search described above is performed, and the result returned.
226+ 
227+   .. versionadded:: 2.3
168
169
170.. data:: template
171
172   .. deprecated:: 2.0
173      Use :func:`gettempprefix` instead.
174
175   When set to a value other than ``None``, this variable defines the prefix of the
176   final component of the filenames returned by :func:`mktemp`.  A string of six
177   random letters and digits is appended to the prefix to make the filename unique.
t178-   On Windows, the default prefix is :file:`~T`; on all other systems it is
t238+   The default prefix is :file:`tmp`.
179-   :file:`tmp`.
180
181   Older versions of this module used to require that ``template`` be set to
182   ``None`` after a call to :func:`os.fork`; this has not been necessary since
183   version 1.5.2.
184
185
186.. function:: gettempprefix()
187
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op