Issue 5178: Add tempfile.TemporaryDirectory (original patch by Neil Schemenauer)
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 @@
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 @@
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 @@
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
+