Wrap some long paragraphs and include the default values for optional

function parameters.

Doc/library/tempfile.rst

@@ -23,51 +23,53 @@ insecure :func:`mktemp` function.  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* and *template* variables.  To maintain
-backward compatibility, the argument order is somewhat odd; it is recommended to
-use keyword arguments for clarity.
+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* 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:
 
 
-.. function:: TemporaryFile([mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir]]]]])
+.. function:: TemporaryFile([mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None]]]]])
 
-   Return a 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
+   Return a 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.
+   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 *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 behaves
-   consistently on all platforms without regard for the data that is stored.
-   *bufsize* defaults to ``-1``, meaning that the operating system default is used.
+   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
+   behaves consistently on all platforms without regard for the data that is
+   stored.  *bufsize* defaults to ``-1``, meaning that the operating system
+   default is used.
 
    The *dir*, *prefix* and *suffix* parameters are passed to :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
-   underlying true file object. This file-like object can be used in a :keyword:`with`
-   statement, just like a normal file.
+   underlying true file object. This file-like object can be used in a
+   :keyword:`with` statement, just like a normal file.
 
 
-.. function:: NamedTemporaryFile([mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir[, delete]]]]]])
+.. function:: NamedTemporaryFile([mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None[, delete=True]]]]]])
 
-   This function operates exactly as :func:`TemporaryFile` does, except that the
-   file is guaranteed to have a visible name in the file system (on Unix, the
-   directory entry is not unlinked).  That name can be retrieved from the
-   :attr:`name` member of the file object.  Whether the name can be used to open
-   the file a second time, while the named temporary file is still open, varies
-   across platforms (it can be so used on Unix; it cannot on Windows NT or later).
-   If *delete* is true (the default), the file is deleted as soon as it is closed.
+   This function operates exactly as :func:`TemporaryFile` does, except that
+   the file is guaranteed to have a visible name in the file system (on
+   Unix, the directory entry is not unlinked).  That name can be retrieved
+   from the :attr:`name` member of the file object.  Whether the name can be
+   used to open the file a second time, while the named temporary file is
+   still open, varies across platforms (it can be so used on Unix; it cannot
+   on Windows NT or later).  If *delete* is true (the default), the file is
+   deleted as soon as it is closed.
 
-   The returned object is always a file-like object whose :attr:`file` attribute
-   is the underlying true file object. This file-like object can be used in a :keyword:`with`
-   statement, just like a normal file.
+   The returned object is always a file-like object whose :attr:`file`
+   attribute is the underlying true file object. This file-like object can
+   be used in a :keyword:`with` statement, just like a normal file.
 
    .. versionadded:: 2.3
 
@@ -75,107 +77,113 @@ The module defines the following user-callable functions:
       The *delete* parameter.
 
 
-.. function:: SpooledTemporaryFile([max_size=0, [mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir]]]]]])
+.. function:: SpooledTemporaryFile([max_size=0, [mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None]]]]]])
 
-   This function operates exactly as :func:`TemporaryFile` does, except that data
-   is spooled in memory until the file size exceeds *max_size*, or until the file's
-   :func:`fileno` method is called, at which point the contents are written to disk
-   and operation proceeds as with :func:`TemporaryFile`.
+   This function operates exactly as :func:`TemporaryFile` does, except that
+   data is spooled in memory until the file size exceeds *max_size*, or
+   until the file's :func:`fileno` method is called, at which point the
+   contents are written to disk and operation proceeds as with
+   :func:`TemporaryFile`.
 
-   The resulting file has one additional method, :func:`rollover`, which causes the
-   file to roll over to an on-disk file regardless of its size.
+   The resulting file has one additional method, :func:`rollover`, which
+   causes the file to roll over to an on-disk file regardless of its size.
 
    The returned object is a file-like object whose :attr:`_file` attribute
    is either a :class:`StringIO` object or a true file object, depending on
-   whether :func:`rollover` has been called. This file-like object can be used in a
-   :keyword:`with` statement, just like a normal file.
+   whether :func:`rollover` has been called. This file-like object can be
+   used in a :keyword:`with` statement, just like a normal file.
 
    .. versionadded:: 2.6
 
 
-.. function:: mkstemp([suffix[, prefix[, dir[, text]]]])
+.. function:: mkstemp([suffix=''[, prefix='tmp'[, dir=None[, text=False]]]])
 
-   Creates a temporary file in the most secure manner possible.  There are no
-   race conditions in the file's creation, assuming that the platform properly
-   implements the :const:`os.O_EXCL` flag for :func:`os.open`.  The file is
-   readable and writable only by the creating user ID.  If the platform uses
-   permission bits to indicate whether a file is executable, the file is
-   executable by no one.  The file descriptor is not inherited by child
-   processes.
+   Creates a temporary file in the most secure manner possible.  There are
+   no race conditions in the file's creation, assuming that the platform
+   properly implements the :const:`os.O_EXCL` flag for :func:`os.open`.  The
+   file is readable and writable only by the creating user ID.  If the
+   platform uses permission bits to indicate whether a file is executable,
+   the file is executable by no one.  The file descriptor is not inherited
+   by child processes.
 
-   Unlike :func:`TemporaryFile`, the user of :func:`mkstemp` is responsible for
-   deleting the temporary file when done with it.
+   Unlike :func:`TemporaryFile`, the user of :func:`mkstemp` is responsible
+   for deleting the temporary file when done with it.
 
-   If *suffix* is specified, the file name will end with that suffix, otherwise
-   there will be no suffix.  :func:`mkstemp` does not put a dot between the file
-   name and the suffix; if you need one, put it at the beginning of *suffix*.
+   If *suffix* is specified, the file name will end with that suffix,
+   otherwise there will be no suffix.  :func:`mkstemp` does not put a dot
+   between the file name and the suffix; if you need one, put it at the
+   beginning of *suffix*.
 
-   If *prefix* is specified, the file name will begin with that prefix; otherwise,
-   a default prefix is used.
+   If *prefix* is specified, the file name will begin with that prefix;
+   otherwise, a default prefix is used.
 
-   If *dir* is specified, the file will be created in that directory; otherwise,
-   a default directory is used.  The default directory is chosen from a
-   platform-dependent list, but the user of the application can control the
-   directory location by setting the *TMPDIR*, *TEMP* or *TMP* environment
-   variables.  There is thus no guarantee that the generated filename will have
-   any nice properties, such as not requiring quoting when passed to external
-   commands via ``os.popen()``.
+   If *dir* is specified, the file will be created in that directory;
+   otherwise, a default directory is used.  The default directory is chosen
+   from a platform-dependent list, but the user of the application can
+   control the directory location by setting the *TMPDIR*, *TEMP* or *TMP*
+   environment variables.  There is thus no guarantee that the generated
+   filename will have any nice properties, such as not requiring quoting
+   when passed to external commands via ``os.popen()``.
 
-   If *text* is specified, it indicates whether to open the file in binary mode
-   (the default) or text mode.  On some platforms, this makes no difference.
+   If *text* is specified, it indicates whether to open the file in binary
+   mode (the default) or text mode.  On some platforms, this makes no
+   difference.
 
-   :func:`mkstemp` returns a tuple containing an OS-level handle to an open file
-   (as would be returned by :func:`os.open`) and the absolute pathname of that
-   file, in that order.
+   :func:`mkstemp` returns a tuple containing an OS-level handle to an open
+   file (as would be returned by :func:`os.open`) and the absolute pathname
+   of that file, in that order.
 
    .. versionadded:: 2.3
 
 
-.. function:: mkdtemp([suffix[, prefix[, dir]]])
+.. function:: mkdtemp([suffix=''[, prefix='tmp'[, dir=None]]])
 
-   Creates a temporary directory in the most secure manner possible. There are no
-   race conditions in the directory's creation.  The directory is readable,
-   writable, and searchable only by the creating user ID.
+   Creates a temporary directory in the most secure manner possible. There
+   are no race conditions in the directory's creation.  The directory is
+   readable, writable, and searchable only by the creating user ID.
 
-   The user of :func:`mkdtemp` is responsible for deleting the temporary directory
-   and its contents when done with it.
+   The user of :func:`mkdtemp` is responsible for deleting the temporary
+   directory and its contents when done with it.
 
-   The *prefix*, *suffix*, and *dir* arguments are the same as for :func:`mkstemp`.
+   The *prefix*, *suffix*, and *dir* arguments are the same as for
+   :func:`mkstemp`.
 
    :func:`mkdtemp` returns the absolute pathname of the new directory.
 
    .. versionadded:: 2.3
 
 
-.. function:: mktemp([suffix[, prefix[, dir]]])
+.. function:: mktemp([suffix=''[, prefix='tmp'[, dir=None]]])
 
    .. deprecated:: 2.3
       Use :func:`mkstemp` instead.
 
-   Return an absolute pathname of a file that did not exist at the time the call is
-   made.  The *prefix*, *suffix*, and *dir* arguments are the same as for
-   :func:`mkstemp`.
+   Return an absolute pathname of a file that did not exist at the time the
+   call is made.  The *prefix*, *suffix*, and *dir* arguments are the same
+   as for :func:`mkstemp`.
 
    .. warning::
 
-      Use of this function may introduce a security hole in your program.  By the time
-      you get around to doing anything with the file name it returns, someone else may
-      have beaten you to the punch.
+      Use of this function may introduce a security hole in your program.
+      By the time you get around to doing anything with the file name it
+      returns, someone else may have beaten you to the punch.
 
-The module uses two global variables that tell it how to construct a temporary
-name.  They are initialized at the first call to any of the functions above.
-The caller may change them, but this is discouraged; use the appropriate
-function arguments, instead.
+The module uses two global variables that tell it how to construct a
+temporary name.  They are initialized at the first call to any of the
+functions above.  The caller may change them, but this is discouraged; use
+the appropriate function arguments, instead.
 
 
 .. data:: tempdir
 
-   When set to a value other than ``None``, this variable defines the default value
-   for the *dir* argument to all the functions defined in this module.
+   When set to a value other than ``None``, this variable defines the
+   default value for the *dir* argument to all the functions defined in this
+   module.
 
-   If ``tempdir`` is unset or ``None`` at any call to any of the above functions,
-   Python searches a standard list of directories and sets *tempdir* to the first
-   one which the calling user can create files in.  The list is:
+   If ``tempdir`` is unset or ``None`` at any call to any of the above
+   functions, Python searches a standard list of directories and sets
+   *tempdir* to the first one which the calling user can create files in.
+   The list is:
 
    #. The directory named by the :envvar:`TMPDIR` environment variable.