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