Doc/libppath.tex

   1 \section{Standard Module \sectcode{posixpath}}
   2 \stmodindex{posixpath}
   3
   4 This module implements some useful functions on POSIX pathnames.
   5
   6 \strong{Do not import this module directly.}  Instead, import the
   7 module \code{os} and use \code{os.path}.
   8 \stmodindex{os}
   9
  10 \renewcommand{\indexsubitem}{(in module posixpath)}
  11
  12 \begin{funcdesc}{basename}{p}
  13 Return the base name of pathname
  14 \var{p}.
  15 This is the second half of the pair returned by
  16 \code{posixpath.split(\var{p})}.
  17 \end{funcdesc}
  18
  19 \begin{funcdesc}{commonprefix}{list}
  20 Return the longest string that is a prefix of all strings in
  21 \var{list}.
  22 If
  23 \var{list}
  24 is empty, return the empty string (\code{''}).
  25 \end{funcdesc}
  26
  27 \begin{funcdesc}{exists}{p}
  28 Return true if
  29 \var{p}
  30 refers to an existing path.
  31 \end{funcdesc}
  32
  33 \begin{funcdesc}{expanduser}{p}
  34 Return the argument with an initial component of \samp{\~} or
  35 \samp{\~\var{user}} replaced by that \var{user}'s home directory.  An
  36 initial \samp{\~{}} is replaced by the environment variable \code{\${}HOME};
  37 an initial \samp{\~\var{user}} is looked up in the password directory through
  38 the built-in module \code{pwd}.  If the expansion fails, or if the
  39 path does not begin with a tilde, the path is returned unchanged.
  40 \end{funcdesc}
  41
  42 \begin{funcdesc}{expandvars}{p}
  43 Return the argument with environment variables expanded.  Substrings
  44 of the form \samp{\$\var{name}} or \samp{\$\{\var{name}\}} are
  45 replaced by the value of environment variable \var{name}.  Malformed
  46 variable names and references to non-existing variables are left
  47 unchanged.
  48 \end{funcdesc}
  49
  50 \begin{funcdesc}{isabs}{p}
  51 Return true if \var{p} is an absolute pathname (begins with a slash).
  52 \end{funcdesc}
  53
  54 \begin{funcdesc}{isfile}{p}
  55 Return true if \var{p} is an existing regular file.  This follows
  56 symbolic links, so both \code{islink()} and \code{isfile()} can be true for the same
  57 path.
  58 \end{funcdesc}
  59
  60 \begin{funcdesc}{isdir}{p}
  61 Return true if \var{p} is an existing directory.  This follows
  62 symbolic links, so both \code{islink()} and \code{isdir()} can be true for the same
  63 path.
  64 \end{funcdesc}
  65
  66 \begin{funcdesc}{islink}{p}
  67 Return true if
  68 \var{p}
  69 refers to a directory entry that is a symbolic link.
  70 Always false if symbolic links are not supported.
  71 \end{funcdesc}
  72
  73 \begin{funcdesc}{ismount}{p}
  74 Return true if pathname \var{p} is a \dfn{mount point}: a point in a
  75 file system where a different file system has been mounted.  The
  76 function checks whether \var{p}'s parent, \file{\var{p}/..}, is on a
  77 different device than \var{p}, or whether \file{\var{p}/..} and
  78 \var{p} point to the same i-node on the same device --- this should
  79 detect mount points for all \UNIX{} and POSIX variants.
  80 \end{funcdesc}
  81
  82 \begin{funcdesc}{join}{p\, q}
  83 Join the paths
  84 \var{p}
  85 and
  86 \var{q} intelligently:
  87 If
  88 \var{q}
  89 is an absolute path, the return value is
  90 \var{q}.
  91 Otherwise, the concatenation of
  92 \var{p}
  93 and
  94 \var{q}
  95 is returned, with a slash (\code{'/'}) inserted unless
  96 \var{p}
  97 is empty or ends in a slash.
  98 \end{funcdesc}
  99
 100 \begin{funcdesc}{normcase}{p}
 101 Normalize the case of a pathname.  This returns the path unchanged;
 102 however, a similar function in \code{macpath} converts upper case to
 103 lower case.
 104 \end{funcdesc}
 105
 106 \begin{funcdesc}{samefile}{p\, q}
 107 Return true if both pathname arguments refer to the same file or directory
 108 (as indicated by device number and i-node number).
 109 Raise an exception if a stat call on either pathname fails.
 110 \end{funcdesc}
 111
 112 \begin{funcdesc}{split}{p}
 113 Split the pathname \var{p} in a pair \code{(\var{head}, \var{tail})}, where
 114 \var{tail} is the last pathname component and \var{head} is
 115 everything leading up to that.  If \var{p} ends in a slash (except if
 116 it is the root), the trailing slash is removed and the operation
 117 applied to the result; otherwise, \code{join(\var{head}, \var{tail})} equals
 118 \var{p}.  The \var{tail} part never contains a slash.  Some boundary
 119 cases:\ if \var{p} is the root, \var{head} equals \var{p} and
 120 \var{tail} is empty; if \var{p} is empty, both \var{head} and
 121 \var{tail} are empty; if \var{p} contains no slash, \var{head} is
 122 empty and \var{tail} equals \var{p}.
 123 \end{funcdesc}
 124
 125 \begin{funcdesc}{splitext}{p}
 126 Split the pathname \var{p} in a pair \code{(\var{root}, \var{ext})}
 127 such that \code{\var{root} + \var{ext} == \var{p}},
 128 the last component of \var{root} contains no periods,
 129 and \var{ext} is empty or begins with a period.
 130 \end{funcdesc}
 131
 132 \begin{funcdesc}{walk}{p\, visit\, arg}
 133 Calls the function \var{visit} with arguments
 134 \code{(\var{arg}, \var{dirname}, \var{names})} for each directory in the
 135 directory tree rooted at \var{p} (including \var{p} itself, if it is a
 136 directory).  The argument \var{dirname} specifies the visited directory,
 137 the argument \var{names} lists the files in the directory (gotten from
 138 \code{posix.listdir(\var{dirname})}, so including \samp{.} and
 139 \samp{..}).  The \var{visit} function may modify \var{names} to
 140 influence the set of directories visited below \var{dirname}, e.g., to
 141 avoid visiting certain parts of the tree.  (The object referred to by
 142 \var{names} must be modified in place, using \code{del} or slice
 143 assignment.)
 144 \end{funcdesc}