diff -r ffa851df0825 -r 2fb8b9db1c86 symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/tempfile.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/tempfile.rst Fri Jul 31 15:01:17 2009 +0100 @@ -0,0 +1,252 @@ + +:mod:`tempfile` --- Generate temporary files and directories +============================================================ + +.. sectionauthor:: Zack Weinberg + + +.. module:: tempfile + :synopsis: Generate temporary files and directories. + + +.. index:: + pair: temporary; file name + pair: temporary; file + +This module generates temporary files and directories. It works on all +supported platforms. + +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. + +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='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 + 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. + + 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. + + +.. 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. + + .. versionadded:: 2.3 + + .. versionadded:: 2.6 + The *delete* parameter. + + +.. 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='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. + + 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 *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 *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. + + .. versionadded:: 2.3 + + +.. 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. + + 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`. + + :func:`mkdtemp` returns the absolute pathname of the new directory. + + .. versionadded:: 2.3 + + +.. 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`. + + .. 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. + :func:`mktemp` usage can be replaced easily with + :func:`NamedTemporaryFile`, passing it the `delete=False` parameter:: + + >>> f = NamedTemporaryFile(delete=False) + >>> f + ', 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 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. + + 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. + + #. The directory named by the :envvar:`TEMP` environment variable. + + #. The directory named by the :envvar:`TMP` environment variable. + + #. A platform-specific location: + + * On RiscOS, the directory named by the :envvar:`Wimp$ScrapDir` environment + variable. + + * On Windows, the directories :file:`C:\\TEMP`, :file:`C:\\TMP`, + :file:`\\TEMP`, and :file:`\\TMP`, in that order. + + * On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and + :file:`/usr/tmp`, in that order. + + #. As a last resort, the current working directory. + + +.. function:: gettempdir() + + Return the directory currently selected to create temporary files in. If + :data:`tempdir` is not ``None``, this simply returns its contents; otherwise, + 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. + The default prefix is :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() + + Return the filename prefix used to create temporary files. This does not + contain the directory component. Using this function is preferred over reading + the *template* variable directly. + + .. versionadded:: 1.5.2 +