n | |
| :mod:`os.path` --- Common pathname manipulations |
| ================================================ |
| |
| .. module:: os.path |
n | |
n | :synopsis: Operations on pathnames. |
| |
| |
| |
| .. index:: single: path; operations |
| |
n | This module implements some useful functions on pathnames. |
n | 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. |
| |
| .. warning:: |
| |
| On Windows, many of these functions do not properly support UNC pathnames. |
| :func:`splitunc` and :func:`ismount` do handle them correctly. |
n | |
| |
| .. note:: |
| |
| Since different operating systems have different path name conventions, there |
| are several versions of this module in the standard library. The |
| :mod:`os.path` module is always the path module suitable for the operating |
| system Python is running on, and therefore usable for local paths. However, |
| you can also import and use the individual modules if you want to manipulate |
| a path that is *always* in one of the different formats. They all have the |
| same interface: |
| |
| * :mod:`posixpath` for UNIX-style paths |
| * :mod:`ntpath` for Windows paths |
| * :mod:`macpath` for old-style MacOS paths |
| * :mod:`os2emxpath` for OS/2 EMX paths |
| |
| |
| .. function:: abspath(path) |
| |
| Return a normalized absolutized version of the pathname *path*. On most |
| platforms, this is equivalent to ``normpath(join(os.getcwd(), path))``. |
| |
| .. versionadded:: 1.5.2 |
| broken symbolic links. Equivalent to :func:`exists` on platforms lacking |
| :func:`os.lstat`. |
| |
| .. versionadded:: 2.4 |
| |
| |
| .. function:: expanduser(path) |
| |
n | On Unix and Windows, return the argument with an initial component of ``~`` or |
| ``~user`` replaced by that *user*'s home directory. |
| |
| .. index:: module: pwd |
| |
n | On Unix, return the argument with an initial component of ``~`` or ``~user`` |
n | On Unix, an initial ``~`` is replaced by the environment variable :envvar:`HOME` |
| replaced by that *user*'s home directory. An initial ``~`` is replaced by the |
| if it is set; otherwise the current user's home directory is looked up in the |
| environment variable :envvar:`HOME` if it is set; otherwise the current user's |
| password directory through the built-in module :mod:`pwd`. An initial ``~user`` |
| home directory is looked up in the password directory through the built-in |
| is looked up directly in the password directory. |
| module :mod:`pwd`. An initial ``~user`` is looked up directly in the password |
| directory. |
| |
n | On Windows, only ``~`` is supported; it is replaced by the environment variable |
n | On Windows, :envvar:`HOME` and :envvar:`USERPROFILE` will be used if set, |
| :envvar:`HOME` or by a combination of :envvar:`HOMEDRIVE` and |
| otherwise a combination of :envvar:`HOMEPATH` and :envvar:`HOMEDRIVE` will be |
| :envvar:`HOMEPATH`. |
| used. An initial ``~user`` is handled by stripping the last directory component |
| from the created user path derived above. |
| |
| If the expansion fails or if the path does not begin with a tilde, the path is |
| returned unchanged. |
| |
| |
| .. function:: expandvars(path) |
| |
| Return the argument with environment variables expanded. Substrings of the form |
| ``$name`` or ``${name}`` are replaced by the value of environment variable |
| *name*. Malformed variable names and references to non-existing variables are |
| left unchanged. |
n | |
| On Windows, ``%name%`` expansions are supported in addition to ``$name`` and |
| ``${name}``. |
| |
| |
| .. function:: getatime(path) |
| |
| Return the time of last access of *path*. The return value is a number 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. |
| |
| 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) |
| |
n | Return ``True`` if *path* is an absolute pathname (begins with a slash). |
n | Return ``True`` if *path* is an absolute pathname. On Unix, that means it |
| begins with a slash, on Windows that it begins with a (back)slash after chopping |
| off a potential drive letter. |
| |
| |
| .. function:: isfile(path) |
| |
| Return ``True`` if *path* is an existing regular file. This follows symbolic |
| links, so both :func:`islink` and :func:`isfile` can be true for the same path. |
| |
| |
| .. function:: join(path1[, path2[, ...]]) |
| |
| Join one or more path components intelligently. If any component is an absolute |
| path, all previous components (on Windows, including the previous drive letter, |
| if there was one) are thrown away, and joining continues. The return value is |
| the concatenation of *path1*, and optionally *path2*, etc., with exactly one |
| directory separator (``os.sep``) inserted between components, unless *path2* is |
| empty. Note that on Windows, since there is a current directory for each drive, |
n | :func:`os.path.join("c:", "foo")` represents a path relative to the current |
n | ``os.path.join("c:", "foo")`` represents a path relative to the current |
| directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\\\foo`. |
| directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`. |
| |
| |
| .. function:: normcase(path) |
| |
n | Normalize the case of a pathname. On Unix, this returns the path unchanged; on |
n | Normalize the case of a pathname. On Unix and Mac OS X, this returns the |
| case-insensitive filesystems, it converts the path to lowercase. On Windows, it |
| path unchanged; on case-insensitive filesystems, it converts the path to |
| also converts forward slashes to backward slashes. |
| lowercase. On Windows, it also converts forward slashes to backward slashes. |
| |
| |
| .. function:: normpath(path) |
| |
| Normalize a pathname. This collapses redundant separators and up-level |
| references so that ``A//B``, ``A/./B`` and ``A/foo/../B`` all become ``A/B``. |
| It does not normalize the case (use :func:`normcase` for that). On Windows, it |
| converts forward slashes to backward slashes. It should be understood that this |
| .. function:: realpath(path) |
| |
| 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 |
| |
| |
n | .. function:: relpath(path[, start]) |
| |
| 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 |
| |
| |
| .. 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 |
n | :func:`os.stat` call on either pathname fails. Availability: Macintosh, Unix. |
n | :func:`os.stat` call on either pathname fails. Availability: Unix. |
| |
| |
| .. function:: sameopenfile(fp1, fp2) |
| |
| Return ``True`` if the file descriptors *fp1* and *fp2* refer to the same file. |
n | Availability: Macintosh, Unix. |
n | Availability: Unix. |
| |
| |
| .. function:: samestat(stat1, stat2) |
| |
| Return ``True`` if the stat tuples *stat1* and *stat2* refer to the same file. |
| These structures may have been returned by :func:`fstat`, :func:`lstat`, or |
| :func:`stat`. This function implements the underlying comparison used by |
n | :func:`samefile` and :func:`sameopenfile`. Availability: Macintosh, Unix. |
n | :func:`samefile` and :func:`sameopenfile`. Availability: Unix. |
| |
| |
| .. function:: split(path) |
| |
| Split the pathname *path* into a pair, ``(head, tail)`` where *tail* is the last |
| pathname component and *head* is everything leading up to that. The *tail* part |
| will never contain a slash; if *path* ends in a slash, *tail* will be empty. If |
| there is no slash in *path*, *head* will be empty. If *path* is empty, both |
| |
| .. versionadded:: 1.3 |
| |
| |
| .. function:: splitext(path) |
| |
| Split the pathname *path* into a pair ``(root, ext)`` such that ``root + ext == |
| path``, and *ext* is empty or begins with a period and contains at most one |
n | period. |
n | 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) |
| |
| 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, |
| *unc* will always be the empty string. Availability: Windows. |
| |
| .. 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. |
| |
n | .. note:: |
n | .. warning:: |
| |
t | The newer :func:`os.walk` generator supplies similar functionality and can be |
t | This function is deprecated and has been removed in 3.0 in favor of |
| easier to use. |
| :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), and if :func:`os.listdir` returns Unicode strings |
| for a Unicode argument. |
| |