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