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