Issue #25064: Merge tempfile doc from 3.5
This commit is contained in:
commit
eb1d89abdd
|
@ -33,7 +33,7 @@ is recommended to use keyword arguments for clarity.
|
||||||
|
|
||||||
The module defines the following user-callable items:
|
The module defines the following user-callable items:
|
||||||
|
|
||||||
.. function:: TemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix='', prefix='tmp', dir=None)
|
.. function:: TemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=None)
|
||||||
|
|
||||||
Return a :term:`file-like object` that can be used as a temporary storage area.
|
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
|
The file is created securely, using the same rules as :func:`mkstemp`. It will be destroyed as soon
|
||||||
|
@ -54,8 +54,8 @@ The module defines the following user-callable items:
|
||||||
stored. *buffering*, *encoding* and *newline* are interpreted as for
|
stored. *buffering*, *encoding* and *newline* are interpreted as for
|
||||||
:func:`open`.
|
:func:`open`.
|
||||||
|
|
||||||
The *dir*, *prefix* and *suffix* parameters have the same meaning
|
The *dir*, *prefix* and *suffix* parameters have the same meaning and
|
||||||
as with :func:`mkstemp`.
|
defaults as with :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
|
||||||
|
@ -69,7 +69,7 @@ The module defines the following user-callable items:
|
||||||
The :py:data:`os.O_TMPFILE` flag is now used if available.
|
The :py:data:`os.O_TMPFILE` flag is now used if available.
|
||||||
|
|
||||||
|
|
||||||
.. function:: NamedTemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix='', prefix='tmp', dir=None, delete=True)
|
.. function:: NamedTemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=None, delete=True)
|
||||||
|
|
||||||
This function operates exactly as :func:`TemporaryFile` does, except that
|
This function operates exactly as :func:`TemporaryFile` does, except that
|
||||||
the file is guaranteed to have a visible name in the file system (on
|
the file is guaranteed to have a visible name in the file system (on
|
||||||
|
@ -84,7 +84,7 @@ The module defines the following user-callable items:
|
||||||
be used in a :keyword:`with` statement, just like a normal file.
|
be used in a :keyword:`with` statement, just like a normal file.
|
||||||
|
|
||||||
|
|
||||||
.. function:: SpooledTemporaryFile(max_size=0, mode='w+b', buffering=None, encoding=None, newline=None, suffix='', prefix='tmp', dir=None)
|
.. function:: SpooledTemporaryFile(max_size=0, mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=None)
|
||||||
|
|
||||||
This function operates exactly as :func:`TemporaryFile` does, except that
|
This function operates exactly as :func:`TemporaryFile` does, except that
|
||||||
data is spooled in memory until the file size exceeds *max_size*, or
|
data is spooled in memory until the file size exceeds *max_size*, or
|
||||||
|
@ -106,7 +106,7 @@ The module defines the following user-callable items:
|
||||||
the truncate method now accepts a ``size`` argument.
|
the truncate method now accepts a ``size`` argument.
|
||||||
|
|
||||||
|
|
||||||
.. function:: TemporaryDirectory(suffix='', prefix='tmp', dir=None)
|
.. function:: TemporaryDirectory(suffix=None, prefix=None, dir=None)
|
||||||
|
|
||||||
This function securely creates a temporary directory using the same rules as :func:`mkdtemp`.
|
This function securely creates a temporary directory using the same rules as :func:`mkdtemp`.
|
||||||
The resulting object can be used as a context manager (see
|
The resulting object can be used as a context manager (see
|
||||||
|
@ -138,15 +138,16 @@ The module defines the following user-callable items:
|
||||||
Unlike :func:`TemporaryFile`, the user of :func:`mkstemp` is responsible
|
Unlike :func:`TemporaryFile`, the user of :func:`mkstemp` is responsible
|
||||||
for 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,
|
If *suffix* is not ``None``, the file name will end with that suffix,
|
||||||
otherwise there will be no suffix. :func:`mkstemp` does not put a dot
|
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
|
between the file name and the suffix; if you need one, put it at the
|
||||||
beginning of *suffix*.
|
beginning of *suffix*.
|
||||||
|
|
||||||
If *prefix* is specified, the file name will begin with that prefix;
|
If *prefix* is not ``None``, the file name will begin with that prefix;
|
||||||
otherwise, a default prefix is used.
|
otherwise, a default prefix is used. The default is the return value of
|
||||||
|
:func:`gettempprefix` or :func:`gettempprefixb`, as appropriate.
|
||||||
|
|
||||||
If *dir* is specified, the file will be created in that directory;
|
If *dir* is not ``None``, the file will be created in that directory;
|
||||||
otherwise, a default directory is used. The default directory is chosen
|
otherwise, a default directory is used. The default directory is chosen
|
||||||
from a platform-dependent list, but the user of the application can
|
from a platform-dependent list, but the user of the application can
|
||||||
control the directory location by setting the *TMPDIR*, *TEMP* or *TMP*
|
control the directory location by setting the *TMPDIR*, *TEMP* or *TMP*
|
||||||
|
@ -154,16 +155,12 @@ The module defines the following user-callable items:
|
||||||
filename will have any nice properties, such as not requiring quoting
|
filename will have any nice properties, such as not requiring quoting
|
||||||
when passed to external commands via ``os.popen()``.
|
when passed to external commands via ``os.popen()``.
|
||||||
|
|
||||||
*suffix*, *prefix*, and *dir* must all contain the same type, if specified.
|
If any of *suffix*, *prefix*, and *dir* are not
|
||||||
|
``None``, they must be the same type.
|
||||||
If they are bytes, the returned name will be bytes instead of str.
|
If they are bytes, the returned name will be bytes instead of str.
|
||||||
If you want to force a bytes return value with otherwise default behavior,
|
If you want to force a bytes return value with otherwise default behavior,
|
||||||
pass ``suffix=b''``.
|
pass ``suffix=b''``.
|
||||||
|
|
||||||
A *prefix* value of ``None`` means use the return value of
|
|
||||||
:func:`gettempprefix` or :func:`gettempprefixb` as appropriate.
|
|
||||||
|
|
||||||
A *suffix* value of ``None`` means use an appropriate empty value.
|
|
||||||
|
|
||||||
If *text* is specified, it indicates whether to open the file in binary
|
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
|
mode (the default) or text mode. On some platforms, this makes no
|
||||||
difference.
|
difference.
|
||||||
|
@ -241,7 +238,7 @@ The module defines the following user-callable items:
|
||||||
|
|
||||||
.. function:: gettempprefixb()
|
.. function:: gettempprefixb()
|
||||||
|
|
||||||
Same as :func:`gettempprefixb` but the return value is in bytes.
|
Same as :func:`gettempprefix` but the return value is in bytes.
|
||||||
|
|
||||||
.. versionadded:: 3.5
|
.. versionadded:: 3.5
|
||||||
|
|
||||||
|
@ -314,8 +311,9 @@ other functions described above.
|
||||||
Use :func:`mkstemp` instead.
|
Use :func:`mkstemp` instead.
|
||||||
|
|
||||||
Return an absolute pathname of a file that did not exist at the time the
|
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
|
call is made. The *prefix*, *suffix*, and *dir* arguments are similar
|
||||||
as for :func:`mkstemp`.
|
to those of :func:`mkstemp`, except that bytes file names, ``suffix=None``
|
||||||
|
and ``prefix=None`` are not supported.
|
||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
|
|
|
@ -307,22 +307,22 @@ def mkstemp(suffix=None, prefix=None, dir=None, text=False):
|
||||||
file. The return value is a pair (fd, name) where fd is the
|
file. The return value is a pair (fd, name) where fd is the
|
||||||
file descriptor returned by os.open, and name is the filename.
|
file descriptor returned by os.open, and name is the filename.
|
||||||
|
|
||||||
If 'suffix' is specified, the file name will end with that suffix,
|
If 'suffix' is not None, the file name will end with that suffix,
|
||||||
otherwise there will be no suffix.
|
otherwise there will be no suffix.
|
||||||
|
|
||||||
If 'prefix' is specified, the file name will begin with that prefix,
|
If 'prefix' is not None, the file name will begin with that prefix,
|
||||||
otherwise a default prefix is used.
|
otherwise a default prefix is used.
|
||||||
|
|
||||||
If 'dir' is specified, the file will be created in that directory,
|
If 'dir' is not None, the file will be created in that directory,
|
||||||
otherwise a default directory is used.
|
otherwise a default directory is used.
|
||||||
|
|
||||||
If 'text' is specified and true, the file is opened in text
|
If 'text' is specified and true, the file is opened in text
|
||||||
mode. Else (the default) the file is opened in binary mode. On
|
mode. Else (the default) the file is opened in binary mode. On
|
||||||
some operating systems, this makes no difference.
|
some operating systems, this makes no difference.
|
||||||
|
|
||||||
suffix, prefix and dir must all contain the same type if specified.
|
If any of 'suffix', 'prefix' and 'dir' are not None, they must be the
|
||||||
If they are bytes, the returned name will be bytes; str otherwise.
|
same type. If they are bytes, the returned name will be bytes; str
|
||||||
A value of None will cause an appropriate default to be used.
|
otherwise.
|
||||||
|
|
||||||
The file is readable and writable only by the creating user ID.
|
The file is readable and writable only by the creating user ID.
|
||||||
If the operating system uses permission bits to indicate whether a
|
If the operating system uses permission bits to indicate whether a
|
||||||
|
@ -385,8 +385,9 @@ def mktemp(suffix="", prefix=template, dir=None):
|
||||||
"""User-callable function to return a unique temporary file name. The
|
"""User-callable function to return a unique temporary file name. The
|
||||||
file is not created.
|
file is not created.
|
||||||
|
|
||||||
Arguments are as for mkstemp, except that the 'text' argument is
|
Arguments are similar to mkstemp, except that the 'text' argument is
|
||||||
not accepted.
|
not accepted, and suffix=None, prefix=None and bytes file names are not
|
||||||
|
supported.
|
||||||
|
|
||||||
THIS FUNCTION IS UNSAFE AND SHOULD NOT BE USED. The file name may
|
THIS FUNCTION IS UNSAFE AND SHOULD NOT BE USED. The file name may
|
||||||
refer to a file that did not exist at some point, but by the time
|
refer to a file that did not exist at some point, but by the time
|
||||||
|
|
Loading…
Reference in New Issue