345 lines
12 KiB
ReStructuredText
345 lines
12 KiB
ReStructuredText
:mod:`os.path` --- Common pathname manipulations
|
|
================================================
|
|
|
|
.. module:: os.path
|
|
:synopsis: Operations on pathnames.
|
|
|
|
.. index:: single: path; operations
|
|
|
|
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.
|
|
|
|
.. note::
|
|
|
|
On Windows, many of these functions do not properly support UNC pathnames.
|
|
:func:`splitunc` and :func:`ismount` do handle them correctly.
|
|
|
|
|
|
.. 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
|
|
|
|
|
|
.. function:: basename(path)
|
|
|
|
Return the base name of pathname *path*. This is the second half of the pair
|
|
returned by ``split(path)``. Note that the result of this function is different
|
|
from the Unix :program:`basename` program; where :program:`basename` for
|
|
``'/foo/bar/'`` returns ``'bar'``, the :func:`basename` function returns an
|
|
empty string (``''``).
|
|
|
|
|
|
.. function:: commonprefix(list)
|
|
|
|
Return the longest path prefix (taken character-by-character) that is a prefix
|
|
of all paths in *list*. If *list* is empty, return the empty string (``''``).
|
|
Note that this may return invalid paths because it works a character at a time.
|
|
|
|
|
|
.. function:: dirname(path)
|
|
|
|
Return the directory name of pathname *path*. This is the first half of the
|
|
pair returned by ``split(path)``.
|
|
|
|
|
|
.. function:: exists(path)
|
|
|
|
Return ``True`` if *path* refers to an existing path. Returns ``False`` for
|
|
broken symbolic links. On some platforms, this function may return ``False`` if
|
|
permission is not granted to execute :func:`os.stat` on the requested file, even
|
|
if the *path* physically exists.
|
|
|
|
|
|
.. function:: lexists(path)
|
|
|
|
Return ``True`` if *path* refers to an existing path. Returns ``True`` for
|
|
broken symbolic links. Equivalent to :func:`exists` on platforms lacking
|
|
:func:`os.lstat`.
|
|
|
|
.. versionadded:: 2.4
|
|
|
|
|
|
.. function:: expanduser(path)
|
|
|
|
On Unix and Windows, return the argument with an initial component of ``~`` or
|
|
``~user`` replaced by that *user*'s home directory.
|
|
|
|
.. index:: module: pwd
|
|
|
|
On Unix, an initial ``~`` is replaced by the environment variable :envvar:`HOME`
|
|
if it is set; otherwise the current user's home directory is looked up in the
|
|
password directory through the built-in module :mod:`pwd`. An initial ``~user``
|
|
is looked up directly in the password directory.
|
|
|
|
On Windows, :envvar:`HOME` and :envvar:`USERPROFILE` will be used if set,
|
|
otherwise a combination of :envvar:`HOMEPATH` and :envvar:`HOMEDRIVE` will be
|
|
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.
|
|
|
|
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.
|
|
|
|
.. versionadded:: 1.5.2
|
|
|
|
.. versionchanged:: 2.3
|
|
If :func:`os.stat_float_times` returns True, the result is a floating point
|
|
number.
|
|
|
|
|
|
.. function:: getmtime(path)
|
|
|
|
Return the time of last modification 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.
|
|
|
|
.. versionadded:: 1.5.2
|
|
|
|
.. versionchanged:: 2.3
|
|
If :func:`os.stat_float_times` returns True, the result is a floating point
|
|
number.
|
|
|
|
|
|
.. function:: getctime(path)
|
|
|
|
Return the system's ctime which, on some systems (like Unix) is the time of the
|
|
last change, and, on others (like Windows), is the creation time for *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.
|
|
|
|
.. 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)
|
|
|
|
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:: isdir(path)
|
|
|
|
Return ``True`` if *path* is an existing directory. This follows symbolic
|
|
links, so both :func:`islink` and :func:`isdir` can be true for the same path.
|
|
|
|
|
|
.. function:: islink(path)
|
|
|
|
Return ``True`` if *path* refers to a directory entry that is a symbolic link.
|
|
Always ``False`` if symbolic links are not supported.
|
|
|
|
|
|
.. function:: ismount(path)
|
|
|
|
Return ``True`` if pathname *path* is a :dfn:`mount point`: a point in a file
|
|
system where a different file system has been mounted. The function checks
|
|
whether *path*'s parent, :file:`path/..`, is on a different device than *path*,
|
|
or whether :file:`path/..` and *path* point to the same i-node on the same
|
|
device --- this should detect mount points for all Unix and POSIX variants.
|
|
|
|
|
|
.. 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,
|
|
``os.path.join("c:", "foo")`` represents a path relative to the current
|
|
directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`.
|
|
|
|
|
|
.. function:: normcase(path)
|
|
|
|
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.
|
|
|
|
|
|
.. function:: normpath(path)
|
|
|
|
Normalize a pathname. This collapses redundant separators and up-level
|
|
references so that ``A//B``, ``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
|
|
may change the meaning of the path if it contains symbolic links!
|
|
|
|
|
|
.. 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
|
|
|
|
|
|
.. 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
|
|
: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.
|
|
|
|
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
|
|
: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
|
|
*head* and *tail* are empty. Trailing slashes are stripped from *head* unless
|
|
it is the root (one or more slashes only). In nearly all cases, ``join(head,
|
|
tail)`` equals *path* (the only exception being when there were multiple slashes
|
|
separating *head* from *tail*).
|
|
|
|
|
|
.. 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
|
|
specifications, *drive* will always be the empty string. In all cases, ``drive
|
|
+ tail`` will be the same as *path*.
|
|
|
|
.. 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
|
|
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.
|
|
|
|
|
|
.. 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 3.0 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), and if :func:`os.listdir` returns Unicode strings
|
|
for a Unicode argument.
|
|
|
|
.. versionadded:: 2.3
|
|
|