mirror of
https://github.com/python/cpython.git
synced 2025-10-20 05:41:23 +00:00
c1ddc505d9
accomodate the fact that they are more general now that they are for the os.path module and not just posixpath. This and the previous patch should be combined and applied to the 2.2-maint branch.
230 lines
9.2 KiB
TeX
230 lines
9.2 KiB
TeX
\section{\module{os.path} ---
|
|
Common pathname manipulations}
|
|
\declaremodule{standard}{os.path}
|
|
|
|
\modulesynopsis{Common pathname manipulations.}
|
|
|
|
This module implements some useful functions on pathnames.
|
|
\index{path!operations}
|
|
|
|
\warning{On Windows, many of these functions do not properly
|
|
support UNC pathnames. \function{splitunc()} and \function{ismount()}
|
|
do handle them correctly.}
|
|
|
|
|
|
\begin{funcdesc}{abspath}{path}
|
|
Return a normalized absolutized version of the pathname \var{path}.
|
|
On most platforms, this is equivalent to
|
|
\code{normpath(join(os.getcwd(), \var{path}))}.
|
|
\versionadded{1.5.2}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{basename}{path}
|
|
Return the base name of pathname \var{path}. This is the second half
|
|
of the pair returned by \code{split(\var{path})}. Note that the
|
|
result of this function is different from the
|
|
\UNIX{} \program{basename} program; where \program{basename} for
|
|
\code{'/foo/bar/'} returns \code{'bar'}, the \function{basename()}
|
|
function returns an empty string (\code{''}).
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{commonprefix}{list}
|
|
Return the longest path prefix (taken character-by-character) that is a
|
|
prefix of all paths in
|
|
\var{list}. If \var{list} is empty, return the empty string
|
|
(\code{''}). Note that this may return invalid paths because it works a
|
|
character at a time.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{dirname}{path}
|
|
Return the directory name of pathname \var{path}. This is the first
|
|
half of the pair returned by \code{split(\var{path})}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{exists}{path}
|
|
Return \code{True} if \var{path} refers to an existing path.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{expanduser}{path}
|
|
Return the argument with an initial component of \samp{\~} or
|
|
\samp{\~\var{user}} replaced by that \var{user}'s home directory. An
|
|
initial \samp{\~{}} is replaced by the environment variable
|
|
\envvar{HOME}; an initial \samp{\~\var{user}} is looked up in the
|
|
password directory through the built-in module
|
|
\refmodule{pwd}\refbimodindex{pwd}. If the expansion fails, or if the
|
|
path does not begin with a tilde, the path is returned unchanged. On
|
|
the Macintosh, this always returns \var{path} unchanged.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{expandvars}{path}
|
|
Return the argument with environment variables expanded. Substrings
|
|
of the form \samp{\$\var{name}} or \samp{\$\{\var{name}\}} are
|
|
replaced by the value of environment variable \var{name}. Malformed
|
|
variable names and references to non-existing variables are left
|
|
unchanged. On the Macintosh, this always returns \var{path}
|
|
unchanged.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getatime}{path}
|
|
Return the time of last access of \var{filename}. The return
|
|
value is integer giving the number of seconds since the epoch (see the
|
|
\refmodule{time} module). Raise \exception{os.error} if the file does
|
|
not exist or is inaccessible.
|
|
\versionadded{1.5.2}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getmtime}{path}
|
|
Return the time of last modification of \var{filename}. The return
|
|
value is integer giving the number of seconds since the epoch (see the
|
|
\refmodule{time} module). Raise \exception{os.error} if the file does
|
|
not exist or is inaccessible.
|
|
\versionadded{1.5.2}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getsize}{path}
|
|
Return the size, in bytes, of \var{filename}. Raise
|
|
\exception{os.error} if the file does not exist or is inaccessible.
|
|
\versionadded{1.5.2}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{isabs}{path}
|
|
Return \code{True} if \var{path} is an absolute pathname (begins with a
|
|
slash).
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{isfile}{path}
|
|
Return \code{True} if \var{path} is an existing regular file. This follows
|
|
symbolic links, so both \function{islink()} and \function{isfile()}
|
|
can be true for the same path.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{isdir}{path}
|
|
Return \code{True} if \var{path} is an existing directory. This follows
|
|
symbolic links, so both \function{islink()} and \function{isdir()} can
|
|
be true for the same path.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{islink}{path}
|
|
Return \code{True} if \var{path} refers to a directory entry that is a
|
|
symbolic link. Always \code{False} if symbolic links are not supported.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{ismount}{path}
|
|
Return \code{True} if pathname \var{path} is a \dfn{mount point}: a point in
|
|
a file system where a different file system has been mounted. The
|
|
function checks whether \var{path}'s parent, \file{\var{path}/..}, is
|
|
on a different device than \var{path}, or whether \file{\var{path}/..}
|
|
and \var{path} point to the same i-node on the same device --- this
|
|
should detect mount points for all \UNIX{} and \POSIX{} variants.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{join}{path1\optional{, path2\optional{, ...}}}
|
|
Joins one or more path components intelligently. If any component is
|
|
an absolute path, all previous components are thrown away, and joining
|
|
continues. The return value is the concatenation of \var{path1}, and
|
|
optionally \var{path2}, etc., with exactly one directory separator
|
|
(\code{os.sep}) inserted between components, unless \var{path} is
|
|
empty. Note that on Windows, since there is a current directory for
|
|
each drive, \function{os.path.join("c:", "foo")} represents a path
|
|
relative to the current directory on drive \file{C:} (\file{c:foo}), not
|
|
\file{c:\textbackslash\textbackslash foo}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{normcase}{path}
|
|
Normalize the case of a pathname. On \UNIX, 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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{normpath}{path}
|
|
Normalize a pathname. This collapses redundant separators and
|
|
up-level references, e.g. \code{A//B}, \code{A/./B} and
|
|
\code{A/foo/../B} all become \code{A/B}. It does not normalize the
|
|
case (use \function{normcase()} for that). On Windows, it converts
|
|
forward slashes to backward slashes.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{realpath}{path}
|
|
Return the canonical path of the specified filename, eliminating any
|
|
symbolic links encountered in the path.
|
|
Availability: \UNIX.
|
|
\versionadded{2.2}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{samefile}{path1, path2}
|
|
Return \code{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 \function{os.stat()} call on either pathname
|
|
fails.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{sameopenfile}{fp1, fp2}
|
|
Return \code{True} if the file objects \var{fp1} and \var{fp2} refer to the
|
|
same file. The two file objects may represent different file
|
|
descriptors.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{samestat}{stat1, stat2}
|
|
Return \code{True} if the stat tuples \var{stat1} and \var{stat2} refer to
|
|
the same file. These structures may have been returned by
|
|
\function{fstat()}, \function{lstat()}, or \function{stat()}. This
|
|
function implements the underlying comparison used by
|
|
\function{samefile()} and \function{sameopenfile()}.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{split}{path}
|
|
Split the pathname \var{path} into a pair, \code{(\var{head},
|
|
\var{tail})} where \var{tail} is the last pathname component and
|
|
\var{head} is everything leading up to that. The \var{tail} part will
|
|
never contain a slash; if \var{path} ends in a slash, \var{tail} will
|
|
be empty. If there is no slash in \var{path}, \var{head} will be
|
|
empty. If \var{path} is empty, both \var{head} and \var{tail} are
|
|
empty. Trailing slashes are stripped from \var{head} unless it is the
|
|
root (one or more slashes only). In nearly all cases,
|
|
\code{join(\var{head}, \var{tail})} equals \var{path} (the only
|
|
exception being when there were multiple slashes separating \var{head}
|
|
from \var{tail}).
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{splitdrive}{path}
|
|
Split the pathname \var{path} into a pair \code{(\var{drive},
|
|
\var{tail})} where \var{drive} is either a drive specification or the
|
|
empty string. On systems which do not use drive specifications,
|
|
\var{drive} will always be the empty string. In all cases,
|
|
\code{\var{drive} + \var{tail}} will be the same as \var{path}.
|
|
\versionadded{1.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{splitext}{path}
|
|
Split the pathname \var{path} into a pair \code{(\var{root}, \var{ext})}
|
|
such that \code{\var{root} + \var{ext} == \var{path}},
|
|
and \var{ext} is empty or begins with a period and contains
|
|
at most one period.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{walk}{path, visit, arg}
|
|
Calls the function \var{visit} with arguments
|
|
\code{(\var{arg}, \var{dirname}, \var{names})} for each directory in the
|
|
directory tree rooted at \var{path} (including \var{path} itself, if it
|
|
is a directory). The argument \var{dirname} specifies the visited
|
|
directory, the argument \var{names} lists the files in the directory
|
|
(gotten from \code{os.listdir(\var{dirname})}).
|
|
The \var{visit} function may modify \var{names} to
|
|
influence the set of directories visited below \var{dirname}, e.g., to
|
|
avoid visiting certain parts of the tree. (The object referred to by
|
|
\var{names} must be modified in place, using \keyword{del} or slice
|
|
assignment.)
|
|
|
|
\begin{notice}
|
|
Symbolic links to directories are not treated as subdirectories, and
|
|
that \function{walk()} therefore will not visit them. To visit linked
|
|
directories you must identify them with
|
|
\code{os.path.islink(\var{file})} and
|
|
\code{os.path.isdir(\var{file})}, and invoke \function{walk()} as
|
|
necessary.
|
|
\end{notice}
|
|
\end{funcdesc}
|