Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | # Module 'ntpath' -- common operations on WinNT/Win95 pathnames |
2 | """Common pathname manipulations, WindowsNT/95 version. | |
3 | ||
4 | Instead of importing this module directly, import os and refer to this | |
5 | module as os.path. | |
6 | """ | |
7 | ||
8 | import os | |
9 | import stat | |
10 | import sys | |
11 | ||
12 | __all__ = ["normcase","isabs","join","splitdrive","split","splitext", | |
13 | "basename","dirname","commonprefix","getsize","getmtime", | |
14 | "getatime","getctime", "islink","exists","lexists","isdir","isfile", | |
15 | "ismount","walk","expanduser","expandvars","normpath","abspath", | |
16 | "splitunc","curdir","pardir","sep","pathsep","defpath","altsep", | |
17 | "extsep","devnull","realpath","supports_unicode_filenames"] | |
18 | ||
19 | # strings representing various path-related bits and pieces | |
20 | curdir = '.' | |
21 | pardir = '..' | |
22 | extsep = '.' | |
23 | sep = '\\' | |
24 | pathsep = ';' | |
25 | altsep = '/' | |
26 | defpath = '.;C:\\bin' | |
27 | if 'ce' in sys.builtin_module_names: | |
28 | defpath = '\\Windows' | |
29 | elif 'os2' in sys.builtin_module_names: | |
30 | # OS/2 w/ VACPP | |
31 | altsep = '/' | |
32 | devnull = 'nul' | |
33 | ||
34 | # Normalize the case of a pathname and map slashes to backslashes. | |
35 | # Other normalizations (such as optimizing '../' away) are not done | |
36 | # (this is done by normpath). | |
37 | ||
38 | def normcase(s): | |
39 | """Normalize case of pathname. | |
40 | ||
41 | Makes all characters lowercase and all slashes into backslashes.""" | |
42 | return s.replace("/", "\\").lower() | |
43 | ||
44 | ||
45 | # Return whether a path is absolute. | |
46 | # Trivial in Posix, harder on the Mac or MS-DOS. | |
47 | # For DOS it is absolute if it starts with a slash or backslash (current | |
48 | # volume), or if a pathname after the volume letter and colon / UNC resource | |
49 | # starts with a slash or backslash. | |
50 | ||
51 | def isabs(s): | |
52 | """Test whether a path is absolute""" | |
53 | s = splitdrive(s)[1] | |
54 | return s != '' and s[:1] in '/\\' | |
55 | ||
56 | ||
57 | # Join two (or more) paths. | |
58 | ||
59 | def join(a, *p): | |
60 | """Join two or more pathname components, inserting "\\" as needed""" | |
61 | path = a | |
62 | for b in p: | |
63 | b_wins = 0 # set to 1 iff b makes path irrelevant | |
64 | if path == "": | |
65 | b_wins = 1 | |
66 | ||
67 | elif isabs(b): | |
68 | # This probably wipes out path so far. However, it's more | |
69 | # complicated if path begins with a drive letter: | |
70 | # 1. join('c:', '/a') == 'c:/a' | |
71 | # 2. join('c:/', '/a') == 'c:/a' | |
72 | # But | |
73 | # 3. join('c:/a', '/b') == '/b' | |
74 | # 4. join('c:', 'd:/') = 'd:/' | |
75 | # 5. join('c:/', 'd:/') = 'd:/' | |
76 | if path[1:2] != ":" or b[1:2] == ":": | |
77 | # Path doesn't start with a drive letter, or cases 4 and 5. | |
78 | b_wins = 1 | |
79 | ||
80 | # Else path has a drive letter, and b doesn't but is absolute. | |
81 | elif len(path) > 3 or (len(path) == 3 and | |
82 | path[-1] not in "/\\"): | |
83 | # case 3 | |
84 | b_wins = 1 | |
85 | ||
86 | if b_wins: | |
87 | path = b | |
88 | else: | |
89 | # Join, and ensure there's a separator. | |
90 | assert len(path) > 0 | |
91 | if path[-1] in "/\\": | |
92 | if b and b[0] in "/\\": | |
93 | path += b[1:] | |
94 | else: | |
95 | path += b | |
96 | elif path[-1] == ":": | |
97 | path += b | |
98 | elif b: | |
99 | if b[0] in "/\\": | |
100 | path += b | |
101 | else: | |
102 | path += "\\" + b | |
103 | else: | |
104 | # path is not empty and does not end with a backslash, | |
105 | # but b is empty; since, e.g., split('a/') produces | |
106 | # ('a', ''), it's best if join() adds a backslash in | |
107 | # this case. | |
108 | path += '\\' | |
109 | ||
110 | return path | |
111 | ||
112 | ||
113 | # Split a path in a drive specification (a drive letter followed by a | |
114 | # colon) and the path specification. | |
115 | # It is always true that drivespec + pathspec == p | |
116 | def splitdrive(p): | |
117 | """Split a pathname into drive and path specifiers. Returns a 2-tuple | |
118 | "(drive,path)"; either part may be empty""" | |
119 | if p[1:2] == ':': | |
120 | return p[0:2], p[2:] | |
121 | return '', p | |
122 | ||
123 | ||
124 | # Parse UNC paths | |
125 | def splitunc(p): | |
126 | """Split a pathname into UNC mount point and relative path specifiers. | |
127 | ||
128 | Return a 2-tuple (unc, rest); either part may be empty. | |
129 | If unc is not empty, it has the form '//host/mount' (or similar | |
130 | using backslashes). unc+rest is always the input path. | |
131 | Paths containing drive letters never have an UNC part. | |
132 | """ | |
133 | if p[1:2] == ':': | |
134 | return '', p # Drive letter present | |
135 | firstTwo = p[0:2] | |
136 | if firstTwo == '//' or firstTwo == '\\\\': | |
137 | # is a UNC path: | |
138 | # vvvvvvvvvvvvvvvvvvvv equivalent to drive letter | |
139 | # \\machine\mountpoint\directories... | |
140 | # directory ^^^^^^^^^^^^^^^ | |
141 | normp = normcase(p) | |
142 | index = normp.find('\\', 2) | |
143 | if index == -1: | |
144 | ##raise RuntimeError, 'illegal UNC path: "' + p + '"' | |
145 | return ("", p) | |
146 | index = normp.find('\\', index + 1) | |
147 | if index == -1: | |
148 | index = len(p) | |
149 | return p[:index], p[index:] | |
150 | return '', p | |
151 | ||
152 | ||
153 | # Split a path in head (everything up to the last '/') and tail (the | |
154 | # rest). After the trailing '/' is stripped, the invariant | |
155 | # join(head, tail) == p holds. | |
156 | # The resulting head won't end in '/' unless it is the root. | |
157 | ||
158 | def split(p): | |
159 | """Split a pathname. | |
160 | ||
161 | Return tuple (head, tail) where tail is everything after the final slash. | |
162 | Either part may be empty.""" | |
163 | ||
164 | d, p = splitdrive(p) | |
165 | # set i to index beyond p's last slash | |
166 | i = len(p) | |
167 | while i and p[i-1] not in '/\\': | |
168 | i = i - 1 | |
169 | head, tail = p[:i], p[i:] # now tail has no slashes | |
170 | # remove trailing slashes from head, unless it's all slashes | |
171 | head2 = head | |
172 | while head2 and head2[-1] in '/\\': | |
173 | head2 = head2[:-1] | |
174 | head = head2 or head | |
175 | return d + head, tail | |
176 | ||
177 | ||
178 | # Split a path in root and extension. | |
179 | # The extension is everything starting at the last dot in the last | |
180 | # pathname component; the root is everything before that. | |
181 | # It is always true that root + ext == p. | |
182 | ||
183 | def splitext(p): | |
184 | """Split the extension from a pathname. | |
185 | ||
186 | Extension is everything from the last dot to the end. | |
187 | Return (root, ext), either part may be empty.""" | |
188 | ||
189 | i = p.rfind('.') | |
190 | if i<=max(p.rfind('/'), p.rfind('\\')): | |
191 | return p, '' | |
192 | else: | |
193 | return p[:i], p[i:] | |
194 | ||
195 | ||
196 | # Return the tail (basename) part of a path. | |
197 | ||
198 | def basename(p): | |
199 | """Returns the final component of a pathname""" | |
200 | return split(p)[1] | |
201 | ||
202 | ||
203 | # Return the head (dirname) part of a path. | |
204 | ||
205 | def dirname(p): | |
206 | """Returns the directory component of a pathname""" | |
207 | return split(p)[0] | |
208 | ||
209 | ||
210 | # Return the longest prefix of all list elements. | |
211 | ||
212 | def commonprefix(m): | |
213 | "Given a list of pathnames, returns the longest common leading component" | |
214 | if not m: return '' | |
215 | prefix = m[0] | |
216 | for item in m: | |
217 | for i in range(len(prefix)): | |
218 | if prefix[:i+1] != item[:i+1]: | |
219 | prefix = prefix[:i] | |
220 | if i == 0: return '' | |
221 | break | |
222 | return prefix | |
223 | ||
224 | ||
225 | # Get size, mtime, atime of files. | |
226 | ||
227 | def getsize(filename): | |
228 | """Return the size of a file, reported by os.stat()""" | |
229 | return os.stat(filename).st_size | |
230 | ||
231 | def getmtime(filename): | |
232 | """Return the last modification time of a file, reported by os.stat()""" | |
233 | return os.stat(filename).st_mtime | |
234 | ||
235 | def getatime(filename): | |
236 | """Return the last access time of a file, reported by os.stat()""" | |
237 | return os.stat(filename).st_atime | |
238 | ||
239 | def getctime(filename): | |
240 | """Return the creation time of a file, reported by os.stat().""" | |
241 | return os.stat(filename).st_ctime | |
242 | ||
243 | # Is a path a symbolic link? | |
244 | # This will always return false on systems where posix.lstat doesn't exist. | |
245 | ||
246 | def islink(path): | |
247 | """Test for symbolic link. On WindowsNT/95 always returns false""" | |
248 | return False | |
249 | ||
250 | ||
251 | # Does a path exist? | |
252 | ||
253 | def exists(path): | |
254 | """Test whether a path exists""" | |
255 | try: | |
256 | st = os.stat(path) | |
257 | except os.error: | |
258 | return False | |
259 | return True | |
260 | ||
261 | lexists = exists | |
262 | ||
263 | ||
264 | # Is a path a dos directory? | |
265 | # This follows symbolic links, so both islink() and isdir() can be true | |
266 | # for the same path. | |
267 | ||
268 | def isdir(path): | |
269 | """Test whether a path is a directory""" | |
270 | try: | |
271 | st = os.stat(path) | |
272 | except os.error: | |
273 | return False | |
274 | return stat.S_ISDIR(st.st_mode) | |
275 | ||
276 | ||
277 | # Is a path a regular file? | |
278 | # This follows symbolic links, so both islink() and isdir() can be true | |
279 | # for the same path. | |
280 | ||
281 | def isfile(path): | |
282 | """Test whether a path is a regular file""" | |
283 | try: | |
284 | st = os.stat(path) | |
285 | except os.error: | |
286 | return False | |
287 | return stat.S_ISREG(st.st_mode) | |
288 | ||
289 | ||
290 | # Is a path a mount point? Either a root (with or without drive letter) | |
291 | # or an UNC path with at most a / or \ after the mount point. | |
292 | ||
293 | def ismount(path): | |
294 | """Test whether a path is a mount point (defined as root of drive)""" | |
295 | unc, rest = splitunc(path) | |
296 | if unc: | |
297 | return rest in ("", "/", "\\") | |
298 | p = splitdrive(path)[1] | |
299 | return len(p) == 1 and p[0] in '/\\' | |
300 | ||
301 | ||
302 | # Directory tree walk. | |
303 | # For each directory under top (including top itself, but excluding | |
304 | # '.' and '..'), func(arg, dirname, filenames) is called, where | |
305 | # dirname is the name of the directory and filenames is the list | |
306 | # of files (and subdirectories etc.) in the directory. | |
307 | # The func may modify the filenames list, to implement a filter, | |
308 | # or to impose a different order of visiting. | |
309 | ||
310 | def walk(top, func, arg): | |
311 | """Directory tree walk with callback function. | |
312 | ||
313 | For each directory in the directory tree rooted at top (including top | |
314 | itself, but excluding '.' and '..'), call func(arg, dirname, fnames). | |
315 | dirname is the name of the directory, and fnames a list of the names of | |
316 | the files and subdirectories in dirname (excluding '.' and '..'). func | |
317 | may modify the fnames list in-place (e.g. via del or slice assignment), | |
318 | and walk will only recurse into the subdirectories whose names remain in | |
319 | fnames; this can be used to implement a filter, or to impose a specific | |
320 | order of visiting. No semantics are defined for, or required of, arg, | |
321 | beyond that arg is always passed to func. It can be used, e.g., to pass | |
322 | a filename pattern, or a mutable object designed to accumulate | |
323 | statistics. Passing None for arg is common.""" | |
324 | ||
325 | try: | |
326 | names = os.listdir(top) | |
327 | except os.error: | |
328 | return | |
329 | func(arg, top, names) | |
330 | exceptions = ('.', '..') | |
331 | for name in names: | |
332 | if name not in exceptions: | |
333 | name = join(top, name) | |
334 | if isdir(name): | |
335 | walk(name, func, arg) | |
336 | ||
337 | ||
338 | # Expand paths beginning with '~' or '~user'. | |
339 | # '~' means $HOME; '~user' means that user's home directory. | |
340 | # If the path doesn't begin with '~', or if the user or $HOME is unknown, | |
341 | # the path is returned unchanged (leaving error reporting to whatever | |
342 | # function is called with the expanded path as argument). | |
343 | # See also module 'glob' for expansion of *, ? and [...] in pathnames. | |
344 | # (A function should also be defined to do full *sh-style environment | |
345 | # variable expansion.) | |
346 | ||
347 | def expanduser(path): | |
348 | """Expand ~ and ~user constructs. | |
349 | ||
350 | If user or $HOME is unknown, do nothing.""" | |
351 | if path[:1] != '~': | |
352 | return path | |
353 | i, n = 1, len(path) | |
354 | while i < n and path[i] not in '/\\': | |
355 | i = i + 1 | |
356 | if i == 1: | |
357 | if 'HOME' in os.environ: | |
358 | userhome = os.environ['HOME'] | |
359 | elif not 'HOMEPATH' in os.environ: | |
360 | return path | |
361 | else: | |
362 | try: | |
363 | drive = os.environ['HOMEDRIVE'] | |
364 | except KeyError: | |
365 | drive = '' | |
366 | userhome = join(drive, os.environ['HOMEPATH']) | |
367 | else: | |
368 | return path | |
369 | return userhome + path[i:] | |
370 | ||
371 | ||
372 | # Expand paths containing shell variable substitutions. | |
373 | # The following rules apply: | |
374 | # - no expansion within single quotes | |
375 | # - no escape character, except for '$$' which is translated into '$' | |
376 | # - ${varname} is accepted. | |
377 | # - varnames can be made out of letters, digits and the character '_' | |
378 | # XXX With COMMAND.COM you can use any characters in a variable name, | |
379 | # XXX except '^|<>='. | |
380 | ||
381 | def expandvars(path): | |
382 | """Expand shell variables of form $var and ${var}. | |
383 | ||
384 | Unknown variables are left unchanged.""" | |
385 | if '$' not in path: | |
386 | return path | |
387 | import string | |
388 | varchars = string.ascii_letters + string.digits + '_-' | |
389 | res = '' | |
390 | index = 0 | |
391 | pathlen = len(path) | |
392 | while index < pathlen: | |
393 | c = path[index] | |
394 | if c == '\'': # no expansion within single quotes | |
395 | path = path[index + 1:] | |
396 | pathlen = len(path) | |
397 | try: | |
398 | index = path.index('\'') | |
399 | res = res + '\'' + path[:index + 1] | |
400 | except ValueError: | |
401 | res = res + path | |
402 | index = pathlen - 1 | |
403 | elif c == '$': # variable or '$$' | |
404 | if path[index + 1:index + 2] == '$': | |
405 | res = res + c | |
406 | index = index + 1 | |
407 | elif path[index + 1:index + 2] == '{': | |
408 | path = path[index+2:] | |
409 | pathlen = len(path) | |
410 | try: | |
411 | index = path.index('}') | |
412 | var = path[:index] | |
413 | if var in os.environ: | |
414 | res = res + os.environ[var] | |
415 | except ValueError: | |
416 | res = res + path | |
417 | index = pathlen - 1 | |
418 | else: | |
419 | var = '' | |
420 | index = index + 1 | |
421 | c = path[index:index + 1] | |
422 | while c != '' and c in varchars: | |
423 | var = var + c | |
424 | index = index + 1 | |
425 | c = path[index:index + 1] | |
426 | if var in os.environ: | |
427 | res = res + os.environ[var] | |
428 | if c != '': | |
429 | res = res + c | |
430 | else: | |
431 | res = res + c | |
432 | index = index + 1 | |
433 | return res | |
434 | ||
435 | ||
436 | # Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A\B. | |
437 | # Previously, this function also truncated pathnames to 8+3 format, | |
438 | # but as this module is called "ntpath", that's obviously wrong! | |
439 | ||
440 | def normpath(path): | |
441 | """Normalize path, eliminating double slashes, etc.""" | |
442 | path = path.replace("/", "\\") | |
443 | prefix, path = splitdrive(path) | |
444 | # We need to be careful here. If the prefix is empty, and the path starts | |
445 | # with a backslash, it could either be an absolute path on the current | |
446 | # drive (\dir1\dir2\file) or a UNC filename (\\server\mount\dir1\file). It | |
447 | # is therefore imperative NOT to collapse multiple backslashes blindly in | |
448 | # that case. | |
449 | # The code below preserves multiple backslashes when there is no drive | |
450 | # letter. This means that the invalid filename \\\a\b is preserved | |
451 | # unchanged, where a\\\b is normalised to a\b. It's not clear that there | |
452 | # is any better behaviour for such edge cases. | |
453 | if prefix == '': | |
454 | # No drive letter - preserve initial backslashes | |
455 | while path[:1] == "\\": | |
456 | prefix = prefix + "\\" | |
457 | path = path[1:] | |
458 | else: | |
459 | # We have a drive letter - collapse initial backslashes | |
460 | if path.startswith("\\"): | |
461 | prefix = prefix + "\\" | |
462 | path = path.lstrip("\\") | |
463 | comps = path.split("\\") | |
464 | i = 0 | |
465 | while i < len(comps): | |
466 | if comps[i] in ('.', ''): | |
467 | del comps[i] | |
468 | elif comps[i] == '..': | |
469 | if i > 0 and comps[i-1] != '..': | |
470 | del comps[i-1:i+1] | |
471 | i -= 1 | |
472 | elif i == 0 and prefix.endswith("\\"): | |
473 | del comps[i] | |
474 | else: | |
475 | i += 1 | |
476 | else: | |
477 | i += 1 | |
478 | # If the path is now empty, substitute '.' | |
479 | if not prefix and not comps: | |
480 | comps.append('.') | |
481 | return prefix + "\\".join(comps) | |
482 | ||
483 | ||
484 | # Return an absolute path. | |
485 | def abspath(path): | |
486 | """Return the absolute version of a path""" | |
487 | try: | |
488 | from nt import _getfullpathname | |
489 | except ImportError: # Not running on Windows - mock up something sensible. | |
490 | global abspath | |
491 | def _abspath(path): | |
492 | if not isabs(path): | |
493 | path = join(os.getcwd(), path) | |
494 | return normpath(path) | |
495 | abspath = _abspath | |
496 | return _abspath(path) | |
497 | ||
498 | if path: # Empty path must return current working directory. | |
499 | try: | |
500 | path = _getfullpathname(path) | |
501 | except WindowsError: | |
502 | pass # Bad path - return unchanged. | |
503 | else: | |
504 | path = os.getcwd() | |
505 | return normpath(path) | |
506 | ||
507 | # realpath is a no-op on systems without islink support | |
508 | realpath = abspath | |
509 | # Win9x family and earlier have no Unicode filename support. | |
510 | supports_unicode_filenames = (hasattr(sys, "getwindowsversion") and | |
511 | sys.getwindowsversion()[3] >= 2) |