| |
| In version 2.3 of Python, this module was overhauled for enhanced security. It |
| now provides three new functions, :func:`NamedTemporaryFile`, :func:`mkstemp`, |
| and :func:`mkdtemp`, which should eliminate all remaining need to use the |
| 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. |
| |
n | Also, all the user-callable functions now take additional arguments which allow |
n | 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: |
| |
| |
n | .. function:: TemporaryFile([mode=``'w+b'``[, bufsize=``-1``[, suffix[, prefix[, dir]]]]]) |
n | .. function:: TemporaryFile([mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None]]]]]) |
| |
n | Return a file (or file-like) object that can be used as a temporary storage |
n | 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 |
n | collected). Under Unix, the directory entry for the file is removed immediately |
n | 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. |
| |
n | The *mode* parameter defaults to ``'w+b'`` so that the file created can be read |
n | 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`. |
| |
n | 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. |
| |
n | |
| .. function:: NamedTemporaryFile([mode=``'w+b'``[, bufsize=``-1``[, suffix[, prefix[, dir]]]]]) |
| .. function:: NamedTemporaryFile([mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None[, delete=True]]]]]]) |
| |
n | This function operates exactly as :func:`TemporaryFile` does, except that the |
n | 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 |
| on Windows NT or later). If *delete* is true (the default), the file is |
| deleted as soon as it is closed. |
| |
n | 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 |
| |
| .. versionadded:: 2.3 |
| .. versionadded:: 2.6 |
| The *delete* parameter. |
| |
| |
n | .. 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`. |
| |
| 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. |
| |
| .. versionadded:: 2.6 |
| |
| |
| .. function:: mkstemp([suffix[, prefix[, dir[, text]]]]) |
| .. function:: mkstemp([suffix=''[, prefix='tmp'[, dir=None[, text=False]]]]) |
| |
n | Creates a temporary file in the most secure manner possible. There are no race |
n | Creates a temporary file in the most secure manner possible. There are |
| 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:`O_EXCL` flag for :func:`os.open`. The file is readable |
| properly implements the :const:`os.O_EXCL` flag for :func:`os.open`. The |
| and writable only by the creating user ID. If the platform uses permission bits |
| file is readable and writable only by the creating user ID. If the |
| to indicate whether a file is executable, the file is executable by no one. The |
| platform uses permission bits to indicate whether a file is executable, |
| file descriptor is not inherited by child processes. |
| the file is executable by no one. The file descriptor is not inherited |
| by child processes. |
| |
n | Unlike :func:`TemporaryFile`, the user of :func:`mkstemp` is responsible for |
n | 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. |
| |
n | If *suffix* is specified, the file name will end with that suffix, otherwise |
n | 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*. |
| |
n | If *prefix* is specified, the file name will begin with that prefix; otherwise, |
n | If *prefix* is specified, the file name will begin with that prefix; |
| a default prefix is used. |
| otherwise, a default prefix is used. |
| |
n | If *dir* is specified, the file will be created in that directory; otherwise, a |
n | If *dir* is specified, the file will be created in that directory; |
| default directory is used. |
| 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()``. |
| |
n | If *text* is specified, it indicates whether to open the file in binary mode |
n | 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. |
| |
n | :func:`mkstemp` returns a tuple containing an OS-level handle to an open file |
n | :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 |
| |
| |
n | .. function:: mkdtemp([suffix[, prefix[, dir]]]) |
n | .. function:: mkdtemp([suffix=''[, prefix='tmp'[, dir=None]]]) |
| |
n | Creates a temporary directory in the most secure manner possible. There are no |
n | 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. |
| |
n | The user of :func:`mkdtemp` is responsible for deleting the temporary directory |
n | 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. |
| |
n | The *prefix*, *suffix*, and *dir* arguments are the same as for :func:`mkstemp`. |
n | 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 |
| |
| |
n | .. function:: mktemp([suffix[, prefix[, dir]]]) |
n | .. function:: mktemp([suffix=''[, prefix='tmp'[, dir=None]]]) |
| |
| .. deprecated:: 2.3 |
| Use :func:`mkstemp` instead. |
| |
n | Return an absolute pathname of a file that did not exist at the time the call is |
n | 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:: |
| |
n | Use of this function may introduce a security hole in your program. By the time |
n | Use of this function may introduce a security hole in your program. By |
| you get around to doing anything with the file name it returns, someone else may |
| the time you get around to doing anything with the file name it returns, |
| have beaten you to the punch. |
| someone else may have beaten you to the punch. :func:`mktemp` usage can |
| be replaced easily with :func:`NamedTemporaryFile`, passing it the |
| ``delete=False`` parameter:: |
| |
n | >>> f = NamedTemporaryFile(delete=False) |
| >>> f |
| <open file '<fdopen>', mode 'w+b' at 0x384698> |
| >>> f.name |
| '/var/folders/5q/5qTPn6xq2RaWqk+1Ytw3-U+++TI/-Tmp-/tmpG7V1Y0' |
| >>> f.write("Hello World!\n") |
| >>> f.close() |
| >>> os.unlink(f.name) |
| >>> os.path.exists(f.name) |
| False |
| |
| 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 |
| |
n | When set to a value other than ``None``, this variable defines the default value |
n | 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. |
| |
n | If ``tempdir`` is unset or ``None`` at any call to any of the above functions, |
n | 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: |
| |
n | #. The directory named by the :envvar:`TMPDIR` environment variable. |
n | #. The directory named by the :envvar:`TMPDIR` environment variable. |
| |
n | #. The directory named by the :envvar:`TEMP` environment variable. |
n | #. The directory named by the :envvar:`TEMP` environment variable. |
| |
n | #. The directory named by the :envvar:`TMP` environment variable. |
n | #. The directory named by the :envvar:`TMP` environment variable. |
| |
n | #. A platform-specific location: |
n | #. A platform-specific location: |
| |
n | * On RiscOS, the directory named by the :envvar:`Wimp$ScrapDir` environment |
n | * On RiscOS, the directory named by the :envvar:`Wimp$ScrapDir` environment |
| variable. |
| |
n | * On Windows, the directories :file:`C:$\\TEMP`, :file:`C:$\\TMP`, |
n | * On Windows, the directories :file:`C:\\TEMP`, :file:`C:\\TMP`, |
| :file:`\\TEMP`, and :file:`\\TMP`, in that order. |
| |
n | * On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and |
n | * On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and |
| :file:`/usr/tmp`, in that order. |
| |
n | #. As a last resort, the current working directory. |
n | #. As a last resort, the current working directory. |
| |
| |
| .. function:: gettempdir() |
| |
| Return the directory currently selected to create temporary files in. If |
n | ``tempdir`` is not ``None``, this simply returns its contents; otherwise, the |
n | :data:`tempdir` is not ``None``, this simply returns its contents; otherwise, |
| search described above is performed, and the result returned. |
| the search described above is performed, and the result returned. |
| |
| .. versionadded:: 2.3 |
| |
| |
| .. data:: template |
| |
| .. deprecated:: 2.0 |
| Use :func:`gettempprefix` instead. |
| |
| When set to a value other than ``None``, this variable defines the prefix of the |
| final component of the filenames returned by :func:`mktemp`. A string of six |
| random letters and digits is appended to the prefix to make the filename unique. |
t | On Windows, the default prefix is :file:`~T`; on all other systems it is |
t | The default prefix is :file:`tmp`. |
| :file:`tmp`. |
| |
| Older versions of this module used to require that ``template`` be set to |
| ``None`` after a call to :func:`os.fork`; this has not been necessary since |
| version 1.5.2. |
| |
| |
| .. function:: gettempprefix() |
| |