Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1 | \section{Standard Module \sectcode{posixpath}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 2 | \stmodindex{posixpath} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 3 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 4 | This module implements some useful functions on POSIX pathnames. |
| 5 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 6 | \strong{Do not import this module directly.} Instead, import the |
| 7 | module \code{os} and use \code{os.path}. |
| 8 | \stmodindex{os} |
| 9 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 10 | \renewcommand{\indexsubitem}{(in module posixpath)} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 11 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 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 | |
Guido van Rossum | 1738311 | 1994-04-21 10:32:28 +0000 | [diff] [blame] | 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 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 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 |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 56 | symbolic links, so both \code{islink()} and \code{isfile()} can be true for the same |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 57 | path. |
| 58 | \end{funcdesc} |
| 59 | |
| 60 | \begin{funcdesc}{isdir}{p} |
| 61 | Return true if \var{p} is an existing directory. This follows |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 62 | symbolic links, so both \code{islink()} and \code{isdir()} can be true for the same |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 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} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 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} |
Guido van Rossum | 7c2fdda | 1996-06-26 19:23:26 +0000 | [diff] [blame^] | 113 | Split the pathname \var{p} in a pair \code{(\var{head}, \var{tail})}, |
| 114 | where \var{tail} is the last pathname component and \var{head} is |
| 115 | everything leading up to that. The \var{tail} part will never contain |
| 116 | a slash; if \var{p} ends in a slash, \var{tail} will be empty. If |
| 117 | there is no slash in \var{p}, \var{head} will be empty. If \var{p} is |
| 118 | empty, both \var{head} and \var{tail} are empty. Trailing slashes are |
| 119 | stripped from \var{head} unless it is the root (one or more slashes |
| 120 | only). In nearly all cases, \code{join(\var{head}, \var{tail})} |
| 121 | equals \var{p} (the only exception being when there were multiple |
| 122 | slashes separating \var{head} from \var{tail}). |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 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 |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 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.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 144 | \end{funcdesc} |