| \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} |
| |
| |
| \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})}. |
| \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 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 true if \var{path} is an absolute pathname (begins with a |
| slash). |
| \end{funcdesc} |
| |
| \begin{funcdesc}{isfile}{path} |
| Return 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 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 true if \var{path} refers to a directory entry that is a |
| symbolic link. Always false if symbolic links are not supported. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{ismount}{path} |
| Return 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 slash (\code{'/'}) |
| inserted between components, unless \var{path} is empty. |
| \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}{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 \function{os.stat()} call on either pathname |
| fails. |
| Availability: Macintosh, \UNIX{}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{sameopenfile}{fp1, fp2} |
| Return 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 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}. |
| \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.) |
| \end{funcdesc} |