From 37c18c9e9ed67742523fc62ce5df09df53c737ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 20 Mar 2015 15:05:13 -0400 Subject: [PATCH] docs: update description of TemporaryFile and tempfile module High-level context managers are made more visible in the introductory paragraph, and it is explicitly stated that TemporaryFile is as secure as mkstemp. Any references to TemporaryFile calling mkstemp are removed, since it does not do that anymore. --- Doc/library/tempfile.rst | 40 +++++++++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst index 2c6837744b..638bcc82d8 100644 --- a/Doc/library/tempfile.rst +++ b/Doc/library/tempfile.rst @@ -16,16 +16,19 @@ -------------- -This module generates temporary files and directories. It works on all -supported platforms. It provides three new functions, -:func:`NamedTemporaryFile`, :func:`mkstemp`, and :func:`mkdtemp`, which should -eliminate all remaining need to use the insecure :func:`mktemp` function. +This module generates temporary files and directories. It works on +all supported platforms. It provides four high-level functions, +:func:`TemporaryFile`, :func:`NamedTemporaryFile`, +:func:`TemporaryDirectory`, :func:`SpooledTemporaryFile`, which can be +used as context managers, and two lower-level functions +:func:`mkstemp` and :func:`mkdtemp` which require manual cleanup. The +need to use the insecure :func:`mktemp` function is eliminated. 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 *tempdir* variable. +allow direct control over the location and name of temporary files and +directories. It is no longer necessary to use the global *tempdir* variable. To maintain backward compatibility, the argument order is somewhat odd; it is recommended to use keyword arguments for clarity. @@ -33,13 +36,20 @@ The module defines the following user-callable items: .. function:: TemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix='', prefix='tmp', dir=None) - Return a :term:`file-like object` that can be used as a temporary storage area. - The file is created using :func:`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. + Return a :term:`file-like object` that can be used as a temporary + storage area. The file is created securely, using the same rules + as :func:`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 resulting object can be used as a context manager (see + :ref:`context-managers`). On completion of the context or + destruction of the file object the temporary file will be removed + from the filesystem. The *mode* parameter defaults to ``'w+b'`` so that the file created can be read and written without being closed. Binary mode is used so that it @@ -47,7 +57,8 @@ The module defines the following user-callable items: stored. *buffering*, *encoding* and *newline* are interpreted as for :func:`open`. - The *dir*, *prefix* and *suffix* parameters are passed to :func:`mkstemp`. + The *dir*, *prefix* and *suffix* parameters have the same meaning + as with :func:`mkstemp`. The returned object is a true file object on POSIX platforms. On other platforms, it is a file-like object whose :attr:`!file` attribute is the @@ -277,4 +288,3 @@ Here are some examples of typical usage of the :mod:`tempfile` module:: ... print('created temporary directory', tmpdirname) >>> # directory and contents have been removed - -- 2.1.0