diff options
Diffstat (limited to 'Doc/library/tempfile.rst')
| -rw-r--r-- | Doc/library/tempfile.rst | 184 |
1 files changed, 96 insertions, 88 deletions
diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst index cc3318f..4de9236 100644 --- a/Doc/library/tempfile.rst +++ b/Doc/library/tempfile.rst @@ -23,147 +23,155 @@ 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. - 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. + 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. -.. 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. -.. 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. -.. 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. -.. 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. |