Fred Drake | b23ee1d | 1999-02-01 20:20:39 +0000 | [diff] [blame] | 1 | \section{\module{os.path} --- |
| 2 | Common pathname manipulations} |
| 3 | \declaremodule{standard}{os.path} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 4 | |
Fred Drake | b23ee1d | 1999-02-01 20:20:39 +0000 | [diff] [blame] | 5 | \modulesynopsis{Common pathname manipulations.} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 6 | |
Fred Drake | b23ee1d | 1999-02-01 20:20:39 +0000 | [diff] [blame] | 7 | This module implements some useful functions on pathnames. |
Fred Drake | 203b4f1 | 1998-05-14 15:16:12 +0000 | [diff] [blame] | 8 | \index{path!operations} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 9 | |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 10 | \warning{On Windows, many of these functions do not properly |
Fred Drake | bbf7a40 | 2001-09-28 16:14:18 +0000 | [diff] [blame] | 11 | support UNC pathnames. \function{splitunc()} and \function{ismount()} |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 12 | do handle them correctly.} |
Fred Drake | bbf7a40 | 2001-09-28 16:14:18 +0000 | [diff] [blame] | 13 | |
Fred Drake | b23ee1d | 1999-02-01 20:20:39 +0000 | [diff] [blame] | 14 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 15 | \begin{funcdesc}{abspath}{path} |
| 16 | Return a normalized absolutized version of the pathname \var{path}. |
| 17 | On most platforms, this is equivalent to |
Fred Drake | 39d4a02 | 1999-10-18 14:10:06 +0000 | [diff] [blame] | 18 | \code{normpath(join(os.getcwd(), \var{path}))}. |
Fred Drake | 154d909 | 1999-03-17 22:25:11 +0000 | [diff] [blame] | 19 | \versionadded{1.5.2} |
Guido van Rossum | 1804dc3 | 1999-01-29 18:05:05 +0000 | [diff] [blame] | 20 | \end{funcdesc} |
| 21 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 22 | \begin{funcdesc}{basename}{path} |
| 23 | Return the base name of pathname \var{path}. This is the second half |
Fred Drake | 3aecfc9 | 2000-10-26 21:38:23 +0000 | [diff] [blame] | 24 | of the pair returned by \code{split(\var{path})}. Note that the |
| 25 | result of this function is different from the |
| 26 | \UNIX{} \program{basename} program; where \program{basename} for |
| 27 | \code{'/foo/bar/'} returns \code{'bar'}, the \function{basename()} |
| 28 | function returns an empty string (\code{''}). |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 29 | \end{funcdesc} |
| 30 | |
| 31 | \begin{funcdesc}{commonprefix}{list} |
Skip Montanaro | 297bf7c | 2000-08-23 16:58:32 +0000 | [diff] [blame] | 32 | Return the longest path prefix (taken character-by-character) that is a |
| 33 | prefix of all paths in |
Fred Drake | b23ee1d | 1999-02-01 20:20:39 +0000 | [diff] [blame] | 34 | \var{list}. If \var{list} is empty, return the empty string |
Skip Montanaro | 297bf7c | 2000-08-23 16:58:32 +0000 | [diff] [blame] | 35 | (\code{''}). Note that this may return invalid paths because it works a |
| 36 | character at a time. |
Fred Drake | b23ee1d | 1999-02-01 20:20:39 +0000 | [diff] [blame] | 37 | \end{funcdesc} |
| 38 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 39 | \begin{funcdesc}{dirname}{path} |
| 40 | Return the directory name of pathname \var{path}. This is the first |
| 41 | half of the pair returned by \code{split(\var{path})}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 42 | \end{funcdesc} |
| 43 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 44 | \begin{funcdesc}{exists}{path} |
Neal Norwitz | d3dab2b | 2002-04-05 02:21:09 +0000 | [diff] [blame] | 45 | Return \code{True} if \var{path} refers to an existing path. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 46 | \end{funcdesc} |
| 47 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 48 | \begin{funcdesc}{expanduser}{path} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 49 | Return the argument with an initial component of \samp{\~} or |
| 50 | \samp{\~\var{user}} replaced by that \var{user}'s home directory. An |
Fred Drake | 203b4f1 | 1998-05-14 15:16:12 +0000 | [diff] [blame] | 51 | initial \samp{\~{}} is replaced by the environment variable |
Fred Drake | 23a1634 | 1998-08-06 15:33:55 +0000 | [diff] [blame] | 52 | \envvar{HOME}; an initial \samp{\~\var{user}} is looked up in the |
| 53 | password directory through the built-in module |
Fred Drake | b23ee1d | 1999-02-01 20:20:39 +0000 | [diff] [blame] | 54 | \refmodule{pwd}\refbimodindex{pwd}. If the expansion fails, or if the |
| 55 | path does not begin with a tilde, the path is returned unchanged. On |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 56 | the Macintosh, this always returns \var{path} unchanged. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 57 | \end{funcdesc} |
| 58 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 59 | \begin{funcdesc}{expandvars}{path} |
Guido van Rossum | 1738311 | 1994-04-21 10:32:28 +0000 | [diff] [blame] | 60 | Return the argument with environment variables expanded. Substrings |
| 61 | of the form \samp{\$\var{name}} or \samp{\$\{\var{name}\}} are |
| 62 | replaced by the value of environment variable \var{name}. Malformed |
| 63 | variable names and references to non-existing variables are left |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 64 | unchanged. On the Macintosh, this always returns \var{path} |
| 65 | unchanged. |
Guido van Rossum | 1738311 | 1994-04-21 10:32:28 +0000 | [diff] [blame] | 66 | \end{funcdesc} |
| 67 | |
Fred Drake | d8a41e6 | 1999-02-19 17:54:10 +0000 | [diff] [blame] | 68 | \begin{funcdesc}{getatime}{path} |
Neal Norwitz | f3edea5 | 2002-12-31 13:38:28 +0000 | [diff] [blame] | 69 | Return the time of last access of \var{path}. The return |
Martin v. Löwis | 96a60e4 | 2002-12-31 13:11:54 +0000 | [diff] [blame] | 70 | value is a number giving the number of seconds since the epoch (see the |
Fred Drake | d8a41e6 | 1999-02-19 17:54:10 +0000 | [diff] [blame] | 71 | \refmodule{time} module). Raise \exception{os.error} if the file does |
| 72 | not exist or is inaccessible. |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 73 | \versionadded{1.5.2} |
Martin v. Löwis | 96a60e4 | 2002-12-31 13:11:54 +0000 | [diff] [blame] | 74 | \versionchanged[If \function{os.stat_float_times()} returns True, the result is a floating point number]{2.3} |
Guido van Rossum | 2babd7b | 1998-07-24 20:49:39 +0000 | [diff] [blame] | 75 | \end{funcdesc} |
| 76 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 77 | \begin{funcdesc}{getmtime}{path} |
Neal Norwitz | f3edea5 | 2002-12-31 13:38:28 +0000 | [diff] [blame] | 78 | Return the time of last modification of \var{path}. The return |
Martin v. Löwis | 96a60e4 | 2002-12-31 13:11:54 +0000 | [diff] [blame] | 79 | value is a number giving the number of seconds since the epoch (see the |
Fred Drake | b23ee1d | 1999-02-01 20:20:39 +0000 | [diff] [blame] | 80 | \refmodule{time} module). Raise \exception{os.error} if the file does |
| 81 | not exist or is inaccessible. |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 82 | \versionadded{1.5.2} |
Martin v. Löwis | 96a60e4 | 2002-12-31 13:11:54 +0000 | [diff] [blame] | 83 | \versionchanged[If \function{os.stat_float_times()} returns True, the result is a floating point number]{2.3} |
| 84 | \end{funcdesc} |
| 85 | |
| 86 | \begin{funcdesc}{getctime}{path} |
Raymond Hettinger | c43a7e7 | 2003-10-29 00:46:19 +0000 | [diff] [blame] | 87 | Return the system's ctime which, on some systems (like \UNIX) is the |
| 88 | time of the last change, and, on others (like Windows), is the |
| 89 | creation time for \var{path}. The return |
Martin v. Löwis | 96a60e4 | 2002-12-31 13:11:54 +0000 | [diff] [blame] | 90 | value is a number giving the number of seconds since the epoch (see the |
| 91 | \refmodule{time} module). Raise \exception{os.error} if the file does |
| 92 | not exist or is inaccessible. |
| 93 | \versionadded{2.3} |
Guido van Rossum | 2babd7b | 1998-07-24 20:49:39 +0000 | [diff] [blame] | 94 | \end{funcdesc} |
| 95 | |
Fred Drake | d8a41e6 | 1999-02-19 17:54:10 +0000 | [diff] [blame] | 96 | \begin{funcdesc}{getsize}{path} |
Neal Norwitz | f3edea5 | 2002-12-31 13:38:28 +0000 | [diff] [blame] | 97 | Return the size, in bytes, of \var{path}. Raise |
Fred Drake | d8a41e6 | 1999-02-19 17:54:10 +0000 | [diff] [blame] | 98 | \exception{os.error} if the file does not exist or is inaccessible. |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 99 | \versionadded{1.5.2} |
Guido van Rossum | 2babd7b | 1998-07-24 20:49:39 +0000 | [diff] [blame] | 100 | \end{funcdesc} |
| 101 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 102 | \begin{funcdesc}{isabs}{path} |
Neal Norwitz | d3dab2b | 2002-04-05 02:21:09 +0000 | [diff] [blame] | 103 | Return \code{True} if \var{path} is an absolute pathname (begins with a |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 104 | slash). |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 105 | \end{funcdesc} |
| 106 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 107 | \begin{funcdesc}{isfile}{path} |
Neal Norwitz | d3dab2b | 2002-04-05 02:21:09 +0000 | [diff] [blame] | 108 | Return \code{True} if \var{path} is an existing regular file. This follows |
Fred Drake | db9693e | 1998-03-11 05:50:42 +0000 | [diff] [blame] | 109 | symbolic links, so both \function{islink()} and \function{isfile()} |
| 110 | can be true for the same path. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 111 | \end{funcdesc} |
| 112 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 113 | \begin{funcdesc}{isdir}{path} |
Neal Norwitz | d3dab2b | 2002-04-05 02:21:09 +0000 | [diff] [blame] | 114 | Return \code{True} if \var{path} is an existing directory. This follows |
Fred Drake | db9693e | 1998-03-11 05:50:42 +0000 | [diff] [blame] | 115 | symbolic links, so both \function{islink()} and \function{isdir()} can |
| 116 | be true for the same path. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 117 | \end{funcdesc} |
| 118 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 119 | \begin{funcdesc}{islink}{path} |
Neal Norwitz | d3dab2b | 2002-04-05 02:21:09 +0000 | [diff] [blame] | 120 | Return \code{True} if \var{path} refers to a directory entry that is a |
| 121 | symbolic link. Always \code{False} if symbolic links are not supported. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 122 | \end{funcdesc} |
| 123 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 124 | \begin{funcdesc}{ismount}{path} |
Neal Norwitz | d3dab2b | 2002-04-05 02:21:09 +0000 | [diff] [blame] | 125 | Return \code{True} if pathname \var{path} is a \dfn{mount point}: a point in |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 126 | a file system where a different file system has been mounted. The |
| 127 | function checks whether \var{path}'s parent, \file{\var{path}/..}, is |
| 128 | on a different device than \var{path}, or whether \file{\var{path}/..} |
| 129 | and \var{path} point to the same i-node on the same device --- this |
| 130 | should detect mount points for all \UNIX{} and \POSIX{} variants. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 131 | \end{funcdesc} |
| 132 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 133 | \begin{funcdesc}{join}{path1\optional{, path2\optional{, ...}}} |
Barry Warsaw | 7574587 | 1997-02-18 21:53:53 +0000 | [diff] [blame] | 134 | Joins one or more path components intelligently. If any component is |
| 135 | an absolute path, all previous components are thrown away, and joining |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 136 | continues. The return value is the concatenation of \var{path1}, and |
Fred Drake | c1ddc50 | 2002-09-12 18:01:26 +0000 | [diff] [blame] | 137 | optionally \var{path2}, etc., with exactly one directory separator |
Martin v. Löwis | 0479104 | 2002-12-11 12:55:53 +0000 | [diff] [blame] | 138 | (\code{os.sep}) inserted between components, unless \var{path2} is |
Fred Drake | c1ddc50 | 2002-09-12 18:01:26 +0000 | [diff] [blame] | 139 | empty. Note that on Windows, since there is a current directory for |
| 140 | each drive, \function{os.path.join("c:", "foo")} represents a path |
| 141 | relative to the current directory on drive \file{C:} (\file{c:foo}), not |
| 142 | \file{c:\textbackslash\textbackslash foo}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 143 | \end{funcdesc} |
| 144 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 145 | \begin{funcdesc}{normcase}{path} |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 146 | Normalize the case of a pathname. On \UNIX, this returns the path |
Guido van Rossum | 1931c0c | 1998-02-18 14:00:05 +0000 | [diff] [blame] | 147 | unchanged; on case-insensitive filesystems, it converts the path to |
| 148 | lowercase. On Windows, it also converts forward slashes to backward |
| 149 | slashes. |
| 150 | \end{funcdesc} |
| 151 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 152 | \begin{funcdesc}{normpath}{path} |
Guido van Rossum | 1931c0c | 1998-02-18 14:00:05 +0000 | [diff] [blame] | 153 | Normalize a pathname. This collapses redundant separators and |
| 154 | up-level references, e.g. \code{A//B}, \code{A/./B} and |
| 155 | \code{A/foo/../B} all become \code{A/B}. It does not normalize the |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 156 | case (use \function{normcase()} for that). On Windows, it converts |
| 157 | forward slashes to backward slashes. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 158 | \end{funcdesc} |
| 159 | |
Guido van Rossum | 83eeef4 | 2001-09-17 15:16:09 +0000 | [diff] [blame] | 160 | \begin{funcdesc}{realpath}{path} |
| 161 | Return the canonical path of the specified filename, eliminating any |
| 162 | symbolic links encountered in the path. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 163 | Availability: \UNIX. |
Guido van Rossum | 83eeef4 | 2001-09-17 15:16:09 +0000 | [diff] [blame] | 164 | \versionadded{2.2} |
| 165 | \end{funcdesc} |
| 166 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 167 | \begin{funcdesc}{samefile}{path1, path2} |
Neal Norwitz | d3dab2b | 2002-04-05 02:21:09 +0000 | [diff] [blame] | 168 | Return \code{True} if both pathname arguments refer to the same file or |
Fred Drake | db9693e | 1998-03-11 05:50:42 +0000 | [diff] [blame] | 169 | directory (as indicated by device number and i-node number). |
| 170 | Raise an exception if a \function{os.stat()} call on either pathname |
| 171 | fails. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 172 | Availability: Macintosh, \UNIX. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 173 | \end{funcdesc} |
| 174 | |
Fred Drake | d673d48 | 1999-02-03 22:31:30 +0000 | [diff] [blame] | 175 | \begin{funcdesc}{sameopenfile}{fp1, fp2} |
Neal Norwitz | d3dab2b | 2002-04-05 02:21:09 +0000 | [diff] [blame] | 176 | Return \code{True} if the file objects \var{fp1} and \var{fp2} refer to the |
Fred Drake | d673d48 | 1999-02-03 22:31:30 +0000 | [diff] [blame] | 177 | same file. The two file objects may represent different file |
| 178 | descriptors. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 179 | Availability: Macintosh, \UNIX. |
Fred Drake | d673d48 | 1999-02-03 22:31:30 +0000 | [diff] [blame] | 180 | \end{funcdesc} |
| 181 | |
| 182 | \begin{funcdesc}{samestat}{stat1, stat2} |
Neal Norwitz | d3dab2b | 2002-04-05 02:21:09 +0000 | [diff] [blame] | 183 | Return \code{True} if the stat tuples \var{stat1} and \var{stat2} refer to |
Fred Drake | d673d48 | 1999-02-03 22:31:30 +0000 | [diff] [blame] | 184 | the same file. These structures may have been returned by |
| 185 | \function{fstat()}, \function{lstat()}, or \function{stat()}. This |
| 186 | function implements the underlying comparison used by |
| 187 | \function{samefile()} and \function{sameopenfile()}. |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 188 | Availability: Macintosh, \UNIX. |
Fred Drake | d673d48 | 1999-02-03 22:31:30 +0000 | [diff] [blame] | 189 | \end{funcdesc} |
| 190 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 191 | \begin{funcdesc}{split}{path} |
Fred Drake | d673d48 | 1999-02-03 22:31:30 +0000 | [diff] [blame] | 192 | Split the pathname \var{path} into a pair, \code{(\var{head}, |
| 193 | \var{tail})} where \var{tail} is the last pathname component and |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 194 | \var{head} is everything leading up to that. The \var{tail} part will |
| 195 | never contain a slash; if \var{path} ends in a slash, \var{tail} will |
| 196 | be empty. If there is no slash in \var{path}, \var{head} will be |
| 197 | empty. If \var{path} is empty, both \var{head} and \var{tail} are |
| 198 | empty. Trailing slashes are stripped from \var{head} unless it is the |
| 199 | root (one or more slashes only). In nearly all cases, |
| 200 | \code{join(\var{head}, \var{tail})} equals \var{path} (the only |
| 201 | exception being when there were multiple slashes separating \var{head} |
| 202 | from \var{tail}). |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 203 | \end{funcdesc} |
| 204 | |
Fred Drake | 0256c1f | 1999-02-03 19:24:44 +0000 | [diff] [blame] | 205 | \begin{funcdesc}{splitdrive}{path} |
| 206 | Split the pathname \var{path} into a pair \code{(\var{drive}, |
Fred Drake | d673d48 | 1999-02-03 22:31:30 +0000 | [diff] [blame] | 207 | \var{tail})} where \var{drive} is either a drive specification or the |
Fred Drake | 0256c1f | 1999-02-03 19:24:44 +0000 | [diff] [blame] | 208 | empty string. On systems which do not use drive specifications, |
| 209 | \var{drive} will always be the empty string. In all cases, |
| 210 | \code{\var{drive} + \var{tail}} will be the same as \var{path}. |
Fred Drake | 56a71ee | 2001-05-25 16:21:00 +0000 | [diff] [blame] | 211 | \versionadded{1.3} |
Fred Drake | 0256c1f | 1999-02-03 19:24:44 +0000 | [diff] [blame] | 212 | \end{funcdesc} |
| 213 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 214 | \begin{funcdesc}{splitext}{path} |
Fred Drake | 0256c1f | 1999-02-03 19:24:44 +0000 | [diff] [blame] | 215 | Split the pathname \var{path} into a pair \code{(\var{root}, \var{ext})} |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 216 | such that \code{\var{root} + \var{ext} == \var{path}}, |
Guido van Rossum | 56b30ea | 1996-08-19 23:00:50 +0000 | [diff] [blame] | 217 | and \var{ext} is empty or begins with a period and contains |
| 218 | at most one period. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 219 | \end{funcdesc} |
| 220 | |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 221 | \begin{funcdesc}{walk}{path, visit, arg} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 222 | Calls the function \var{visit} with arguments |
| 223 | \code{(\var{arg}, \var{dirname}, \var{names})} for each directory in the |
Fred Drake | a9b9bf9 | 1999-02-02 18:58:33 +0000 | [diff] [blame] | 224 | directory tree rooted at \var{path} (including \var{path} itself, if it |
| 225 | is a directory). The argument \var{dirname} specifies the visited |
| 226 | directory, the argument \var{names} lists the files in the directory |
| 227 | (gotten from \code{os.listdir(\var{dirname})}). |
Guido van Rossum | e8e8799 | 1997-03-25 15:25:54 +0000 | [diff] [blame] | 228 | The \var{visit} function may modify \var{names} to |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 229 | influence the set of directories visited below \var{dirname}, e.g., to |
| 230 | avoid visiting certain parts of the tree. (The object referred to by |
Fred Drake | db9693e | 1998-03-11 05:50:42 +0000 | [diff] [blame] | 231 | \var{names} must be modified in place, using \keyword{del} or slice |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 232 | assignment.) |
Steve Holden | 545092b | 2002-08-06 16:07:07 +0000 | [diff] [blame] | 233 | |
Fred Drake | 95fa4dd | 2002-08-07 12:39:33 +0000 | [diff] [blame] | 234 | \begin{notice} |
| 235 | Symbolic links to directories are not treated as subdirectories, and |
| 236 | that \function{walk()} therefore will not visit them. To visit linked |
| 237 | directories you must identify them with |
| 238 | \code{os.path.islink(\var{file})} and |
| 239 | \code{os.path.isdir(\var{file})}, and invoke \function{walk()} as |
| 240 | necessary. |
| 241 | \end{notice} |
Tim Peters | c4e0940 | 2003-04-25 07:11:48 +0000 | [diff] [blame] | 242 | |
Fred Drake | 9f48045 | 2003-04-25 15:12:47 +0000 | [diff] [blame] | 243 | \note{The newer \function{\refmodule{os}.walk()} generator supplies |
| 244 | similar functionality and can be easier to use.} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 245 | \end{funcdesc} |
Fred Drake | 604ade4 | 2003-02-04 19:13:07 +0000 | [diff] [blame] | 246 | |
| 247 | \begin{datadesc}{supports_unicode_filenames} |
| 248 | True if arbitrary Unicode strings can be used as file names (within |
| 249 | limitations imposed by the file system), and if |
| 250 | \function{os.listdir()} returns Unicode strings for a Unicode |
| 251 | argument. |
| 252 | \versionadded{2.3} |
| 253 | \end{datadesc} |