238 lines
9.4 KiB
TeX
238 lines
9.4 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{datadesc}{supports_unicode_filenames}
|
|
True if arbitrary Unicode strings can be used as file names (within
|
|
limitations imposed by the file system), and if os.listdir returns
|
|
Unicode strings for a Unicode argument.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\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}
|