diff options
Diffstat (limited to 'Doc/library/os.path.rst')
| -rw-r--r-- | Doc/library/os.path.rst | 110 |
1 files changed, 45 insertions, 65 deletions
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index 3e84de0c..22272a7 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -8,12 +8,20 @@ This module implements some useful functions on pathnames. To read or write files see :func:`open`, and for accessing the filesystem see the -:mod:`os` module. +:mod:`os` module. The path parameters can be passed as either strings, +or bytes. Applications are encouraged to represent file names as +(Unicode) character strings. Unfortunately, some file names may not be +representable as strings on Unix, so applications that need to support +arbitrary file names on Unix should use bytes objects to represent +path names. Vice versa, using bytes objects cannot represent all file +names on Windows (in the standard ``mbcs`` encoding), hence Windows +applications should use string objects to access all files. .. note:: - On Windows, many of these functions do not properly support UNC pathnames. - :func:`splitunc` and :func:`ismount` do handle them correctly. + All of these functions accept either only bytes or only string objects as + their parameters. The result is an object of the same type, if a path or + file name is returned. .. note:: @@ -38,8 +46,6 @@ write files see :func:`open`, and for accessing the filesystem see the platforms, this is equivalent to calling the function :func:`normpath` as follows: ``normpath(join(os.getcwd(), path))``. - .. versionadded:: 1.5.2 - .. function:: basename(path) @@ -78,8 +84,6 @@ write files see :func:`open`, and for accessing the filesystem see the broken symbolic links. Equivalent to :func:`exists` on platforms lacking :func:`os.lstat`. - .. versionadded:: 2.4 - .. function:: expanduser(path) @@ -119,11 +123,8 @@ write files see :func:`open`, and for accessing the filesystem see the the number of seconds since the epoch (see the :mod:`time` module). Raise :exc:`os.error` if the file does not exist or is inaccessible. - .. versionadded:: 1.5.2 - - .. versionchanged:: 2.3 - If :func:`os.stat_float_times` returns True, the result is a floating point - number. + If :func:`os.stat_float_times` returns True, the result is a floating point + number. .. function:: getmtime(path) @@ -132,11 +133,8 @@ write files see :func:`open`, and for accessing the filesystem see the giving the number of seconds since the epoch (see the :mod:`time` module). Raise :exc:`os.error` if the file does not exist or is inaccessible. - .. versionadded:: 1.5.2 - - .. versionchanged:: 2.3 - If :func:`os.stat_float_times` returns True, the result is a floating point - number. + If :func:`os.stat_float_times` returns True, the result is a floating point + number. .. function:: getctime(path) @@ -147,16 +145,12 @@ write files see :func:`open`, and for accessing the filesystem see the the :mod:`time` module). Raise :exc:`os.error` if the file does not exist or is inaccessible. - .. versionadded:: 2.3 - .. function:: getsize(path) Return the size, in bytes, of *path*. Raise :exc:`os.error` if the file does not exist or is inaccessible. - .. versionadded:: 1.5.2 - .. function:: isabs(path) @@ -210,6 +204,7 @@ write files see :func:`open`, and for accessing the filesystem see the Normalize the case of a pathname. On Unix and Mac OS X, this returns the path unchanged; on case-insensitive filesystems, it converts the path to lowercase. On Windows, it also converts forward slashes to backward slashes. + Raise a TypeError if the type of *path* is not ``str`` or ``bytes``. .. function:: normpath(path) @@ -228,35 +223,40 @@ write files see :func:`open`, and for accessing the filesystem see the Return the canonical path of the specified filename, eliminating any symbolic links encountered in the path (if they are supported by the operating system). - .. versionadded:: 2.2 - -.. function:: relpath(path[, start]) +.. function:: relpath(path, start=None) Return a relative filepath to *path* either from the current directory or from an optional *start* point. *start* defaults to :attr:`os.curdir`. - Availability: Windows, Unix. - - .. versionadded:: 2.6 + Availability: Unix, Windows. .. function:: samefile(path1, path2) - Return ``True`` if both pathname arguments refer to the same file or directory - (as indicated by device number and i-node number). Raise an exception if a - :func:`os.stat` call on either pathname fails. + Return ``True`` if both pathname arguments refer to the same file or directory. + On Unix, this is determined by the device number and i-node number and raises an + exception if a :func:`os.stat` call on either pathname fails. - Availability: Unix. + On Windows, two files are the same if they resolve to the same final path + name using the Windows API call GetFinalPathNameByHandle. This function + raises an exception if handles cannot be obtained to either file. + + Availability: Unix, Windows. + + .. versionchanged:: 3.2 + Added Windows support. .. function:: sameopenfile(fp1, fp2) Return ``True`` if the file descriptors *fp1* and *fp2* refer to the same file. - Availability: Unix. + Availability: Unix, Windows. + + .. versionchanged:: 3.2 Added Windows support. .. function:: samestat(stat1, stat2) @@ -285,11 +285,19 @@ write files see :func:`open`, and for accessing the filesystem see the .. function:: splitdrive(path) Split the pathname *path* into a pair ``(drive, tail)`` where *drive* is either - a drive specification or the empty string. On systems which do not use drive + a mount point or the empty string. On systems which do not use drive specifications, *drive* will always be the empty string. In all cases, ``drive + tail`` will be the same as *path*. - .. versionadded:: 1.3 + On Windows, splits a pathname into drive/UNC sharepoint and relative path. + + If the path contains a drive letter, drive will contain everything + up to and including the colon. + e.g. ``splitdrive("c:/dir")`` returns ``("c:", "/dir")`` + + If the path contains a UNC path, drive will contain the host name + and share, up to but not including the fourth separator. + e.g. ``splitdrive("//host/computer/dir")`` returns ``("//host/computer", "/dir")`` .. function:: splitext(path) @@ -299,13 +307,12 @@ write files see :func:`open`, and for accessing the filesystem see the period. Leading periods on the basename are ignored; ``splitext('.cshrc')`` returns ``('.cshrc', '')``. - .. versionchanged:: 2.6 - Earlier versions could produce an empty root when the only period was the - first character. - .. function:: splitunc(path) + .. deprecated:: 3.1 + Use *splitdrive* instead. + Split the pathname *path* into a pair ``(unc, rest)`` so that *unc* is the UNC mount point (such as ``r'\\host\mount'``), if present, and *rest* the rest of the path (such as ``r'\path\file.ext'``). For paths containing drive letters, @@ -314,34 +321,7 @@ write files see :func:`open`, and for accessing the filesystem see the Availability: Windows. -.. function:: walk(path, visit, arg) - - Calls the function *visit* with arguments ``(arg, dirname, names)`` for each - directory in the directory tree rooted at *path* (including *path* itself, if it - is a directory). The argument *dirname* specifies the visited directory, the - argument *names* lists the files in the directory (gotten from - ``os.listdir(dirname)``). The *visit* function may modify *names* to influence - the set of directories visited below *dirname*, e.g. to avoid visiting certain - parts of the tree. (The object referred to by *names* must be modified in - place, using :keyword:`del` or slice assignment.) - - .. note:: - - Symbolic links to directories are not treated as subdirectories, and that - :func:`walk` therefore will not visit them. To visit linked directories you must - identify them with ``os.path.islink(file)`` and ``os.path.isdir(file)``, and - invoke :func:`walk` as necessary. - - .. note:: - - This function is deprecated and has been removed in Python 3 in favor of - :func:`os.walk`. - - .. data:: supports_unicode_filenames True if arbitrary Unicode strings can be used as file names (within limitations imposed by the file system). - - .. versionadded:: 2.3 - |