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