Issue 5178: Add tempfile.TemporaryDirectory (original patch by Neil Schemenauer)

2 files changed, 59 insertions, 1 deletions

diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst
index a13df0d..5caea67 100644
--- a/Doc/library/tempfile.rst
+++ b/Doc/library/tempfile.rst
@@ -25,7 +25,7 @@ no longer necessary to use the global *tempdir* and *template* variables.
 To maintain backward compatibility, the argument order is somewhat odd; it
 is recommended to use keyword arguments for clarity.
 
-The module defines the following user-callable functions:
+The module defines the following user-callable items:
 
 .. function:: TemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix='', prefix='tmp', dir=None)
 
@@ -83,6 +83,24 @@ The module defines the following user-callable functions:
    used in a :keyword:`with` statement, just like a normal file.
 
 
+.. function:: TemporaryDirectory(suffix='', prefix='tmp', dir=None)
+
+   This function creates a temporary directory using :func:`mkdtemp`
+   (the supplied arguments are passed directly to the underlying function).
+   The resulting object can be used as a context manager (see
+   :ref:`context-managers`).  On completion of the context (or destruction
+   of the temporary directory object), the newly created temporary directory
+   and all its contents are removed from the filesystem.
+
+   The directory name can be retrieved from the :attr:`name` member
+   of the returned object.
+
+   The directory can be explicitly cleaned up by calling the
+   :func:`cleanup` method.
+
+   .. versionadded:: 3.2
+
+
 .. function:: mkstemp(suffix='', prefix='tmp', dir=None, text=False)
 
    Creates a temporary file in the most secure manner possible.  There are
@@ -210,3 +228,36 @@ the appropriate function arguments, instead.
    Return the filename prefix used to create temporary files.  This does not
    contain the directory component.
 
+
+Examples
+--------
+
+Here are some examples of typical usage of the :mod:`tempfile` module::
+
+    >>> import tempfile
+
+    # create a temporary file and write some data to it
+    >>> fp = tempfile.TemporaryFile()
+    >>> fp.write('Hello world!')
+    # read data from file
+    >>> fp.seek(0)
+    >>> fp.read()
+    'Hello world!'
+    # close the file, it will be removed
+    >>> fp.close()
+
+    # create a temporary file using a context manager
+    >>> with tempfile.TemporaryFile() as fp:
+    ...     fp.write('Hello world!')
+    ...     fp.seek(0)
+    ...     fp.read()
+    'Hello world!'
+    >>>
+    # file is now closed and removed
+
+    # create a temporary directory using the context manager
+    >>> with tempfile.TemporaryDirectory() as tmpdirname:
+    ...     print 'created temporary directory', tmpdirname
+    >>>
+    # directory and contents have been removed
+
diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst
index c16fe87..386e527 100644
--- a/Doc/whatsnew/3.2.rst
+++ b/Doc/whatsnew/3.2.rst
@@ -496,6 +496,13 @@ New, Improved, and Deprecated Modules
 
   (Contributed by Giampaolo Rodolà; :issue:`6706`.)
 
+* The :mod:`tempfile` module has a new context manager,
+  :class:`~tempfile.TemporaryDirectory` which provides easy deterministic
+  cleanup of temporary directories.
+
+  (Contributed by Neil Schemenauer and Nick Coghlan; :issue:`5178`.)
+
+
 Multi-threading
 ===============