Doc/lib/libposixpath.tex

   1 \section{\module{os.path} ---
   2          Common pathname manipulations}
   3 \declaremodule{standard}{os.path}
   4
   5 \modulesynopsis{Common pathname manipulations.}
   6
   7 This module implements some useful functions on pathnames.
   8 \index{path!operations}
   9
  10 \warning{On Windows, many of these functions do not properly
  11 support UNC pathnames.  \function{splitunc()} and \function{ismount()}
  12 do handle them correctly.}
  13
  14
  15 \begin{funcdesc}{abspath}{path}
  16 Return a normalized absolutized version of the pathname \var{path}.
  17 On most platforms, this is equivalent to
  18 \code{normpath(join(os.getcwd(), \var{path}))}.
  19 \versionadded{1.5.2}
  20 \end{funcdesc}
  21
  22 \begin{funcdesc}{basename}{path}
  23 Return the base name of pathname \var{path}.  This is the second half
  24 of the pair returned by \code{split(\var{path})}.  Note that the
  25 result of this function is different from the
  26 \UNIX{} \program{basename} program; where \program{basename} for
  27 \code{'/foo/bar/'} returns \code{'bar'}, the \function{basename()}
  28 function returns an empty string (\code{''}).
  29 \end{funcdesc}
  30
  31 \begin{funcdesc}{commonprefix}{list}
  32 Return the longest path prefix (taken character-by-character) that is a
  33 prefix of all paths in
  34 \var{list}.  If \var{list} is empty, return the empty string
  35 (\code{''}).  Note that this may return invalid paths because it works a
  36 character at a time.
  37 \end{funcdesc}
  38
  39 \begin{funcdesc}{dirname}{path}
  40 Return the directory name of pathname \var{path}.  This is the first
  41 half of the pair returned by \code{split(\var{path})}.
  42 \end{funcdesc}
  43
  44 \begin{funcdesc}{exists}{path}
  45 Return \code{True} if \var{path} refers to an existing path.
  46 \end{funcdesc}
  47
  48 \begin{funcdesc}{expanduser}{path}
  49 Return the argument with an initial component of \samp{\~} or
  50 \samp{\~\var{user}} replaced by that \var{user}'s home directory.  An
  51 initial \samp{\~{}} is replaced by the environment variable
  52 \envvar{HOME}; an initial \samp{\~\var{user}} is looked up in the
  53 password directory through the built-in module
  54 \refmodule{pwd}\refbimodindex{pwd}.  If the expansion fails, or if the
  55 path does not begin with a tilde, the path is returned unchanged.  On
  56 the Macintosh, this always returns \var{path} unchanged.
  57 \end{funcdesc}
  58
  59 \begin{funcdesc}{expandvars}{path}
  60 Return the argument with environment variables expanded.  Substrings
  61 of the form \samp{\$\var{name}} or \samp{\$\{\var{name}\}} are
  62 replaced by the value of environment variable \var{name}.  Malformed
  63 variable names and references to non-existing variables are left
  64 unchanged.  On the Macintosh, this always returns \var{path}
  65 unchanged.
  66 \end{funcdesc}
  67
  68 \begin{funcdesc}{getatime}{path}
  69 Return the time of last access of \var{filename}.  The return
  70 value is integer giving the number of seconds since the epoch (see the
  71 \refmodule{time} module).  Raise \exception{os.error} if the file does
  72 not exist or is inaccessible.
  73 \versionadded{1.5.2}
  74 \end{funcdesc}
  75
  76 \begin{funcdesc}{getmtime}{path}
  77 Return the time of last modification of \var{filename}.  The return
  78 value is integer giving the number of seconds since the epoch (see the
  79 \refmodule{time} module).  Raise \exception{os.error} if the file does
  80 not exist or is inaccessible.
  81 \versionadded{1.5.2}
  82 \end{funcdesc}
  83
  84 \begin{funcdesc}{getsize}{path}
  85 Return the size, in bytes, of \var{filename}.  Raise
  86 \exception{os.error} if the file does not exist or is inaccessible.
  87 \versionadded{1.5.2}
  88 \end{funcdesc}
  89
  90 \begin{funcdesc}{isabs}{path}
  91 Return \code{True} if \var{path} is an absolute pathname (begins with a
  92 slash).
  93 \end{funcdesc}
  94
  95 \begin{funcdesc}{isfile}{path}
  96 Return \code{True} if \var{path} is an existing regular file.  This follows
  97 symbolic links, so both \function{islink()} and \function{isfile()}
  98 can be true for the same path.
  99 \end{funcdesc}
 100
 101 \begin{funcdesc}{isdir}{path}
 102 Return \code{True} if \var{path} is an existing directory.  This follows
 103 symbolic links, so both \function{islink()} and \function{isdir()} can
 104 be true for the same path.
 105 \end{funcdesc}
 106
 107 \begin{funcdesc}{islink}{path}
 108 Return \code{True} if \var{path} refers to a directory entry that is a
 109 symbolic link.  Always \code{False} if symbolic links are not supported.
 110 \end{funcdesc}
 111
 112 \begin{funcdesc}{ismount}{path}
 113 Return \code{True} if pathname \var{path} is a \dfn{mount point}: a point in
 114 a file system where a different file system has been mounted.  The
 115 function checks whether \var{path}'s parent, \file{\var{path}/..}, is
 116 on a different device than \var{path}, or whether \file{\var{path}/..}
 117 and \var{path} point to the same i-node on the same device --- this
 118 should detect mount points for all \UNIX{} and \POSIX{} variants.
 119 \end{funcdesc}
 120
 121 \begin{funcdesc}{join}{path1\optional{, path2\optional{, ...}}}
 122 Joins one or more path components intelligently.  If any component is
 123 an absolute path, all previous components are thrown away, and joining
 124 continues.  The return value is the concatenation of \var{path1}, and
 125 optionally \var{path2}, etc., with exactly one slash (\code{'/'})
 126 inserted between components, unless \var{path} is empty.
 127 \end{funcdesc}
 128
 129 \begin{funcdesc}{normcase}{path}
 130 Normalize the case of a pathname.  On \UNIX, this returns the path
 131 unchanged; on case-insensitive filesystems, it converts the path to
 132 lowercase.  On Windows, it also converts forward slashes to backward
 133 slashes.
 134 \end{funcdesc}
 135
 136 \begin{funcdesc}{normpath}{path}
 137 Normalize a pathname.  This collapses redundant separators and
 138 up-level references, e.g. \code{A//B}, \code{A/./B} and
 139 \code{A/foo/../B} all become \code{A/B}.  It does not normalize the
 140 case (use \function{normcase()} for that).  On Windows, it converts
 141 forward slashes to backward slashes.
 142 \end{funcdesc}
 143
 144 \begin{funcdesc}{realpath}{path}
 145 Return the canonical path of the specified filename, eliminating any
 146 symbolic links encountered in the path.
 147 Availability:  \UNIX.
 148 \versionadded{2.2}
 149 \end{funcdesc}
 150
 151 \begin{funcdesc}{samefile}{path1, path2}
 152 Return \code{True} if both pathname arguments refer to the same file or
 153 directory (as indicated by device number and i-node number).
 154 Raise an exception if a \function{os.stat()} call on either pathname
 155 fails.
 156 Availability:  Macintosh, \UNIX.
 157 \end{funcdesc}
 158
 159 \begin{funcdesc}{sameopenfile}{fp1, fp2}
 160 Return \code{True} if the file objects \var{fp1} and \var{fp2} refer to the
 161 same file.  The two file objects may represent different file
 162 descriptors.
 163 Availability:  Macintosh, \UNIX.
 164 \end{funcdesc}
 165
 166 \begin{funcdesc}{samestat}{stat1, stat2}
 167 Return \code{True} if the stat tuples \var{stat1} and \var{stat2} refer to
 168 the same file.  These structures may have been returned by
 169 \function{fstat()}, \function{lstat()}, or \function{stat()}.  This
 170 function implements the underlying comparison used by
 171 \function{samefile()} and \function{sameopenfile()}.
 172 Availability:  Macintosh, \UNIX.
 173 \end{funcdesc}
 174
 175 \begin{funcdesc}{split}{path}
 176 Split the pathname \var{path} into a pair, \code{(\var{head},
 177 \var{tail})} where \var{tail} is the last pathname component and
 178 \var{head} is everything leading up to that.  The \var{tail} part will
 179 never contain a slash; if \var{path} ends in a slash, \var{tail} will
 180 be empty.  If there is no slash in \var{path}, \var{head} will be
 181 empty.  If \var{path} is empty, both \var{head} and \var{tail} are
 182 empty.  Trailing slashes are stripped from \var{head} unless it is the
 183 root (one or more slashes only).  In nearly all cases,
 184 \code{join(\var{head}, \var{tail})} equals \var{path} (the only
 185 exception being when there were multiple slashes separating \var{head}
 186 from \var{tail}).
 187 \end{funcdesc}
 188
 189 \begin{funcdesc}{splitdrive}{path}
 190 Split the pathname \var{path} into a pair \code{(\var{drive},
 191 \var{tail})} where \var{drive} is either a drive specification or the
 192 empty string.  On systems which do not use drive specifications,
 193 \var{drive} will always be the empty string.  In all cases,
 194 \code{\var{drive} + \var{tail}} will be the same as \var{path}.
 195 \versionadded{1.3}
 196 \end{funcdesc}
 197
 198 \begin{funcdesc}{splitext}{path}
 199 Split the pathname \var{path} into a pair \code{(\var{root}, \var{ext})}
 200 such that \code{\var{root} + \var{ext} == \var{path}},
 201 and \var{ext} is empty or begins with a period and contains
 202 at most one period.
 203 \end{funcdesc}
 204
 205 \begin{funcdesc}{walk}{path, visit, arg}
 206 Calls the function \var{visit} with arguments
 207 \code{(\var{arg}, \var{dirname}, \var{names})} for each directory in the
 208 directory tree rooted at \var{path} (including \var{path} itself, if it
 209 is a directory).  The argument \var{dirname} specifies the visited
 210 directory, the argument \var{names} lists the files in the directory
 211 (gotten from \code{os.listdir(\var{dirname})}).
 212 The \var{visit} function may modify \var{names} to
 213 influence the set of directories visited below \var{dirname}, e.g., to
 214 avoid visiting certain parts of the tree.  (The object referred to by
 215 \var{names} must be modified in place, using \keyword{del} or slice
 216 assignment.)
 217 \end{funcdesc}