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