Lib/ntpath.py

   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     if p[1:2] == ':':
 126         return p[0:2], p[2:]
 127     return '', p
 128
 129
 130 # Parse UNC paths
 131 def splitunc(p):
 132     """Split a pathname into UNC mount point and relative path specifiers.
 133
 134     Return a 2-tuple (unc, rest); either part may be empty.
 135     If unc is not empty, it has the form '//host/mount' (or similar
 136     using backslashes).  unc+rest is always the input path.
 137     Paths containing drive letters never have an UNC part.
 138     """
 139     if p[1:2] == ':':
 140         return '', p # Drive letter present
 141     firstTwo = p[0:2]
 142     if firstTwo == '//' or firstTwo == '\\\\':
 143         # is a UNC path:
 144         # vvvvvvvvvvvvvvvvvvvv equivalent to drive letter
 145         # \\machine\mountpoint\directories...
 146         #           directory ^^^^^^^^^^^^^^^
 147         normp = normcase(p)
 148         index = normp.find('\\', 2)
 149         if index == -1:
 150             ##raise RuntimeError, 'illegal UNC path: "' + p + '"'
 151             return ("", p)
 152         index = normp.find('\\', index + 1)
 153         if index == -1:
 154             index = len(p)
 155         return p[:index], p[index:]
 156     return '', p
 157
 158
 159 # Split a path in head (everything up to the last '/') and tail (the
 160 # rest).  After the trailing '/' is stripped, the invariant
 161 # join(head, tail) == p holds.
 162 # The resulting head won't end in '/' unless it is the root.
 163
 164 def split(p):
 165     """Split a pathname.
 166
 167     Return tuple (head, tail) where tail is everything after the final slash.
 168     Either part may be empty."""
 169
 170     d, p = splitdrive(p)
 171     # set i to index beyond p's last slash
 172     i = len(p)
 173     while i and p[i-1] not in '/\\':
 174         i = i - 1
 175     head, tail = p[:i], p[i:]  # now tail has no slashes
 176     # remove trailing slashes from head, unless it's all slashes
 177     head2 = head
 178     while head2 and head2[-1] in '/\\':
 179         head2 = head2[:-1]
 180     head = head2 or head
 181     return d + head, tail
 182
 183
 184 # Split a path in root and extension.
 185 # The extension is everything starting at the last dot in the last
 186 # pathname component; the root is everything before that.
 187 # It is always true that root + ext == p.
 188
 189 def splitext(p):
 190     return genericpath._splitext(p, sep, altsep, extsep)
 191 splitext.__doc__ = genericpath._splitext.__doc__
 192
 193
 194 # Return the tail (basename) part of a path.
 195
 196 def basename(p):
 197     """Returns the final component of a pathname"""
 198     return split(p)[1]
 199
 200
 201 # Return the head (dirname) part of a path.
 202
 203 def dirname(p):
 204     """Returns the directory component of a pathname"""
 205     return split(p)[0]
 206
 207 # Is a path a symbolic link?
 208 # This will always return false on systems where posix.lstat doesn't exist.
 209
 210 def islink(path):
 211     """Test for symbolic link.
 212     On WindowsNT/95 and OS/2 always returns false
 213     """
 214     return False
 215
 216 # alias exists to lexists
 217 lexists = exists
 218
 219 # Is a path a mount point?  Either a root (with or without drive letter)
 220 # or an UNC path with at most a / or \ after the mount point.
 221
 222 def ismount(path):
 223     """Test whether a path is a mount point (defined as root of drive)"""
 224     unc, rest = splitunc(path)
 225     if unc:
 226         return rest in ("", "/", "\\")
 227     p = splitdrive(path)[1]
 228     return len(p) == 1 and p[0] in '/\\'
 229
 230
 231 # Directory tree walk.
 232 # For each directory under top (including top itself, but excluding
 233 # '.' and '..'), func(arg, dirname, filenames) is called, where
 234 # dirname is the name of the directory and filenames is the list
 235 # of files (and subdirectories etc.) in the directory.
 236 # The func may modify the filenames list, to implement a filter,
 237 # or to impose a different order of visiting.
 238
 239 def walk(top, func, arg):
 240     """Directory tree walk with callback function.
 241
 242     For each directory in the directory tree rooted at top (including top
 243     itself, but excluding '.' and '..'), call func(arg, dirname, fnames).
 244     dirname is the name of the directory, and fnames a list of the names of
 245     the files and subdirectories in dirname (excluding '.' and '..').  func
 246     may modify the fnames list in-place (e.g. via del or slice assignment),
 247     and walk will only recurse into the subdirectories whose names remain in
 248     fnames; this can be used to implement a filter, or to impose a specific
 249     order of visiting.  No semantics are defined for, or required of, arg,
 250     beyond that arg is always passed to func.  It can be used, e.g., to pass
 251     a filename pattern, or a mutable object designed to accumulate
 252     statistics.  Passing None for arg is common."""
 253     warnings.warnpy3k("In 3.x, os.path.walk is removed in favor of os.walk.")
 254     try:
 255         names = os.listdir(top)
 256     except os.error:
 257         return
 258     func(arg, top, names)
 259     for name in names:
 260         name = join(top, name)
 261         if isdir(name):
 262             walk(name, func, arg)
 263
 264
 265 # Expand paths beginning with '~' or '~user'.
 266 # '~' means $HOME; '~user' means that user's home directory.
 267 # If the path doesn't begin with '~', or if the user or $HOME is unknown,
 268 # the path is returned unchanged (leaving error reporting to whatever
 269 # function is called with the expanded path as argument).
 270 # See also module 'glob' for expansion of *, ? and [...] in pathnames.
 271 # (A function should also be defined to do full *sh-style environment
 272 # variable expansion.)
 273
 274 def expanduser(path):
 275     """Expand ~ and ~user constructs.
 276
 277     If user or $HOME is unknown, do nothing."""
 278     if path[:1] != '~':
 279         return path
 280     i, n = 1, len(path)
 281     while i < n and path[i] not in '/\\':
 282         i = i + 1
 283
 284     if 'HOME' in os.environ:
 285         userhome = os.environ['HOME']
 286     elif 'USERPROFILE' in os.environ:
 287         userhome = os.environ['USERPROFILE']
 288     elif not 'HOMEPATH' in os.environ:
 289         return path
 290     else:
 291         try:
 292             drive = os.environ['HOMEDRIVE']
 293         except KeyError:
 294             drive = ''
 295         userhome = join(drive, os.environ['HOMEPATH'])
 296
 297     if i != 1: #~user
 298         userhome = join(dirname(userhome), path[1:i])
 299
 300     return userhome + path[i:]
 301
 302
 303 # Expand paths containing shell variable substitutions.
 304 # The following rules apply:
 305 #       - no expansion within single quotes
 306 #       - '$$' is translated into '$'
 307 #       - '%%' is translated into '%' if '%%' are not seen in %var1%%var2%
 308 #       - ${varname} is accepted.
 309 #       - $varname is accepted.
 310 #       - %varname% is accepted.
 311 #       - varnames can be made out of letters, digits and the characters '_-'
 312 #         (though is not verifed in the ${varname} and %varname% cases)
 313 # XXX With COMMAND.COM you can use any characters in a variable name,
 314 # XXX except '^|<>='.
 315
 316 def expandvars(path):
 317     """Expand shell variables of the forms $var, ${var} and %var%.
 318
 319     Unknown variables are left unchanged."""
 320     if '$' not in path and '%' not in path:
 321         return path
 322     import string
 323     varchars = string.ascii_letters + string.digits + '_-'
 324     res = ''
 325     index = 0
 326     pathlen = len(path)
 327     while index < pathlen:
 328         c = path[index]
 329         if c == '\'':   # no expansion within single quotes
 330             path = path[index + 1:]
 331             pathlen = len(path)
 332             try:
 333                 index = path.index('\'')
 334                 res = res + '\'' + path[:index + 1]
 335             except ValueError:
 336                 res = res + path
 337                 index = pathlen - 1
 338         elif c == '%':  # variable or '%'
 339             if path[index + 1:index + 2] == '%':
 340                 res = res + c
 341                 index = index + 1
 342             else:
 343                 path = path[index+1:]
 344                 pathlen = len(path)
 345                 try:
 346                     index = path.index('%')
 347                 except ValueError:
 348                     res = res + '%' + path
 349                     index = pathlen - 1
 350                 else:
 351                     var = path[:index]
 352                     if var in os.environ:
 353                         res = res + os.environ[var]
 354                     else:
 355                         res = res + '%' + var + '%'
 356         elif c == '$':  # variable or '$$'
 357             if path[index + 1:index + 2] == '$':
 358                 res = res + c
 359                 index = index + 1
 360             elif path[index + 1:index + 2] == '{':
 361                 path = path[index+2:]
 362                 pathlen = len(path)
 363                 try:
 364                     index = path.index('}')
 365                     var = path[:index]
 366                     if var in os.environ:
 367                         res = res + os.environ[var]
 368                     else:
 369                         res = res + '${' + var + '}'
 370                 except ValueError:
 371                     res = res + '${' + path
 372                     index = pathlen - 1
 373             else:
 374                 var = ''
 375                 index = index + 1
 376                 c = path[index:index + 1]
 377                 while c != '' and c in varchars:
 378                     var = var + c
 379                     index = index + 1
 380                     c = path[index:index + 1]
 381                 if var in os.environ:
 382                     res = res + os.environ[var]
 383                 else:
 384                     res = res + '$' + var
 385                 if c != '':
 386                     index = index - 1
 387         else:
 388             res = res + c
 389         index = index + 1
 390     return res
 391
 392
 393 # Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A\B.
 394 # Previously, this function also truncated pathnames to 8+3 format,
 395 # but as this module is called "ntpath", that's obviously wrong!
 396
 397 def normpath(path):
 398     """Normalize path, eliminating double slashes, etc."""
 399     path = path.replace("/", "\\")
 400     prefix, path = splitdrive(path)
 401     # We need to be careful here. If the prefix is empty, and the path starts
 402     # with a backslash, it could either be an absolute path on the current
 403     # drive (\dir1\dir2\file) or a UNC filename (\\server\mount\dir1\file). It
 404     # is therefore imperative NOT to collapse multiple backslashes blindly in
 405     # that case.
 406     # The code below preserves multiple backslashes when there is no drive
 407     # letter. This means that the invalid filename \\\a\b is preserved
 408     # unchanged, where a\\\b is normalised to a\b. It's not clear that there
 409     # is any better behaviour for such edge cases.
 410     if prefix == '':
 411         # No drive letter - preserve initial backslashes
 412         while path[:1] == "\\":
 413             prefix = prefix + "\\"
 414             path = path[1:]
 415     else:
 416         # We have a drive letter - collapse initial backslashes
 417         if path.startswith("\\"):
 418             prefix = prefix + "\\"
 419             path = path.lstrip("\\")
 420     comps = path.split("\\")
 421     i = 0
 422     while i < len(comps):
 423         if comps[i] in ('.', ''):
 424             del comps[i]
 425         elif comps[i] == '..':
 426             if i > 0 and comps[i-1] != '..':
 427                 del comps[i-1:i+1]
 428                 i -= 1
 429             elif i == 0 and prefix.endswith("\\"):
 430                 del comps[i]
 431             else:
 432                 i += 1
 433         else:
 434             i += 1
 435     # If the path is now empty, substitute '.'
 436     if not prefix and not comps:
 437         comps.append('.')
 438     return prefix + "\\".join(comps)
 439
 440
 441 # Return an absolute path.
 442 try:
 443     from nt import _getfullpathname
 444
 445 except ImportError: # not running on Windows - mock up something sensible
 446     def abspath(path):
 447         """Return the absolute version of a path."""
 448         if not isabs(path):
 449             path = join(os.getcwd(), path)
 450         return normpath(path)
 451
 452 else:  # use native Windows method on Windows
 453     def abspath(path):
 454         """Return the absolute version of a path."""
 455
 456         if path: # Empty path must return current working directory.
 457             try:
 458                 path = _getfullpathname(path)
 459             except WindowsError:
 460                 pass # Bad path - return unchanged.
 461         else:
 462             path = os.getcwd()
 463         return normpath(path)
 464
 465 # realpath is a no-op on systems without islink support
 466 realpath = abspath
 467 # Win9x family and earlier have no Unicode filename support.
 468 supports_unicode_filenames = (hasattr(sys, "getwindowsversion") and
 469                               sys.getwindowsversion()[3] >= 2)
 470
 471 def relpath(path, start=curdir):
 472     """Return a relative version of a path"""
 473
 474     if not path:
 475         raise ValueError("no path specified")
 476     start_list = abspath(start).split(sep)
 477     path_list = abspath(path).split(sep)
 478     if start_list[0].lower() != path_list[0].lower():
 479         unc_path, rest = splitunc(path)
 480         unc_start, rest = splitunc(start)
 481         if bool(unc_path) ^ bool(unc_start):
 482             raise ValueError("Cannot mix UNC and non-UNC paths (%s and %s)"
 483                                                                 % (path, start))
 484         else:
 485             raise ValueError("path is on drive %s, start on drive %s"
 486                                                 % (path_list[0], start_list[0]))
 487     # Work out how much of the filepath is shared by start and path.
 488     for i in range(min(len(start_list), len(path_list))):
 489         if start_list[i].lower() != path_list[i].lower():
 490             break
 491     else:
 492         i += 1
 493
 494     rel_list = [pardir] * (len(start_list)-i) + path_list[i:]
 495     if not rel_list:
 496         return curdir
 497     return join(*rel_list)