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