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 stat
  10 import string
  11
  12
  13 # Normalize the case of a pathname and map slashes to backslashes.
  14 # Other normalizations (such as optimizing '../' away) are not done
  15 # (this is done by normpath).
  16
  17 def normcase(s):
  18     """Normalize case of pathname.
  19
  20     Makes all characters lowercase and all slashes into backslashes."""
  21     return string.lower(string.replace(s, "/", "\\"))
  22
  23
  24 # Return wheter a path is absolute.
  25 # Trivial in Posix, harder on the Mac or MS-DOS.
  26 # For DOS it is absolute if it starts with a slash or backslash (current
  27 # volume), or if a pathname after the volume letter and colon / UNC resource
  28 # starts with a slash or backslash.
  29
  30 def isabs(s):
  31     """Test whether a path is absolute"""
  32     s = splitdrive(s)[1]
  33     return s != '' and s[:1] in '/\\'
  34
  35
  36 # Join two (or more) paths.
  37
  38 def join(a, *p):
  39     """Join two or more pathname components, inserting "\\" as needed"""
  40     path = a
  41     for b in p:
  42         if isabs(b):
  43             path = b
  44         elif path == '' or path[-1:] in '/\\':
  45             path = path + b
  46         else:
  47             path = path + os.sep + b
  48     return path
  49
  50
  51 # Split a path in a drive specification (a drive letter followed by a
  52 # colon) and the path specification.
  53 # It is always true that drivespec + pathspec == p
  54 def splitdrive(p):
  55     """Split a pathname into drive and path specifiers. Returns a 2-tuple
  56 "(drive,path)";  either part may be empty"""
  57     if p[1:2] == ':':
  58         return p[0:2], p[2:]
  59     return '', p
  60
  61
  62 # Parse UNC paths
  63 def splitunc(p):
  64     """Split a pathname into UNC mount point and relative path specifiers.
  65
  66     Return a 2-tuple (unc, rest); either part may be empty.
  67     If unc is not empty, it has the form '//host/mount' (or similar
  68     using backslashes).  unc+rest is always the input path.
  69     Paths containing drive letters never have an UNC part.
  70     """
  71     if p[1:2] == ':':
  72         return '', p # Drive letter present
  73     firstTwo = p[0:2]
  74     if firstTwo == '//' or firstTwo == '\\\\':
  75         # is a UNC path:
  76         # vvvvvvvvvvvvvvvvvvvv equivalent to drive letter
  77         # \\machine\mountpoint\directories...
  78         #           directory ^^^^^^^^^^^^^^^
  79         normp = normcase(p)
  80         index = string.find(normp, '\\', 2)
  81         if index == -1:
  82             ##raise RuntimeError, 'illegal UNC path: "' + p + '"'
  83             return ("", p)
  84         index = string.find(normp, '\\', index + 1)
  85         if index == -1:
  86             index = len(p)
  87         return p[:index], p[index:]
  88     return '', p
  89
  90
  91 # Split a path in head (everything up to the last '/') and tail (the
  92 # rest).  After the trailing '/' is stripped, the invariant
  93 # join(head, tail) == p holds.
  94 # The resulting head won't end in '/' unless it is the root.
  95
  96 def split(p):
  97     """Split a pathname.
  98
  99     Return tuple (head, tail) where tail is everything after the final slash.
 100     Either part may be empty."""
 101
 102     d, p = splitdrive(p)
 103     # set i to index beyond p's last slash
 104     i = len(p)
 105     while i and p[i-1] not in '/\\':
 106         i = i - 1
 107     head, tail = p[:i], p[i:]  # now tail has no slashes
 108     # remove trailing slashes from head, unless it's all slashes
 109     head2 = head
 110     while head2 and head2[-1] in '/\\':
 111         head2 = head2[:-1]
 112     head = head2 or head
 113     return d + head, tail
 114
 115
 116 # Split a path in root and extension.
 117 # The extension is everything starting at the last dot in the last
 118 # pathname component; the root is everything before that.
 119 # It is always true that root + ext == p.
 120
 121 def splitext(p):
 122     """Split the extension from a pathname.
 123
 124     Extension is everything from the last dot to the end.
 125     Return (root, ext), either part may be empty."""
 126     root, ext = '', ''
 127     for c in p:
 128         if c in ['/','\\']:
 129             root, ext = root + ext + c, ''
 130         elif c == '.':
 131             if ext:
 132                 root, ext = root + ext, c
 133             else:
 134                 ext = c
 135         elif ext:
 136             ext = ext + c
 137         else:
 138             root = root + c
 139     return root, ext
 140
 141
 142 # Return the tail (basename) part of a path.
 143
 144 def basename(p):
 145     """Returns the final component of a pathname"""
 146     return split(p)[1]
 147
 148
 149 # Return the head (dirname) part of a path.
 150
 151 def dirname(p):
 152     """Returns the directory component of a pathname"""
 153     return split(p)[0]
 154
 155
 156 # Return the longest prefix of all list elements.
 157
 158 def commonprefix(m):
 159     "Given a list of pathnames, returns the longest common leading component"
 160     if not m: return ''
 161     prefix = m[0]
 162     for item in m:
 163         for i in range(len(prefix)):
 164             if prefix[:i+1] <> item[:i+1]:
 165                 prefix = prefix[:i]
 166                 if i == 0: return ''
 167                 break
 168     return prefix
 169
 170
 171 # Get size, mtime, atime of files.
 172
 173 def getsize(filename):
 174     """Return the size of a file, reported by os.stat()"""
 175     st = os.stat(filename)
 176     return st[stat.ST_SIZE]
 177
 178 def getmtime(filename):
 179     """Return the last modification time of a file, reported by os.stat()"""
 180     st = os.stat(filename)
 181     return st[stat.ST_MTIME]
 182
 183 def getatime(filename):
 184     """Return the last access time of a file, reported by os.stat()"""
 185     st = os.stat(filename)
 186     return st[stat.ST_MTIME]
 187
 188
 189 # Is a path a symbolic link?
 190 # This will always return false on systems where posix.lstat doesn't exist.
 191
 192 def islink(path):
 193     """Test for symbolic link.  On WindowsNT/95 always returns false"""
 194     return 0
 195
 196
 197 # Does a path exist?
 198 # This is false for dangling symbolic links.
 199
 200 def exists(path):
 201     """Test whether a path exists"""
 202     try:
 203         st = os.stat(path)
 204     except os.error:
 205         return 0
 206     return 1
 207
 208
 209 # Is a path a dos directory?
 210 # This follows symbolic links, so both islink() and isdir() can be true
 211 # for the same path.
 212
 213 def isdir(path):
 214     """Test whether a path is a directory"""
 215     try:
 216         st = os.stat(path)
 217     except os.error:
 218         return 0
 219     return stat.S_ISDIR(st[stat.ST_MODE])
 220
 221
 222 # Is a path a regular file?
 223 # This follows symbolic links, so both islink() and isdir() can be true
 224 # for the same path.
 225
 226 def isfile(path):
 227     """Test whether a path is a regular file"""
 228     try:
 229         st = os.stat(path)
 230     except os.error:
 231         return 0
 232     return stat.S_ISREG(st[stat.ST_MODE])
 233
 234
 235 # Is a path a mount point?  Either a root (with or without drive letter)
 236 # or an UNC path with at most a / or \ after the mount point.
 237
 238 def ismount(path):
 239     """Test whether a path is a mount point (defined as root of drive)"""
 240     unc, rest = splitunc(path)
 241     if unc:
 242         return rest in ("", "/", "\\")
 243     p = splitdrive(path)[1]
 244     return len(p)==1 and p[0] in '/\\'
 245
 246
 247 # Directory tree walk.
 248 # For each directory under top (including top itself, but excluding
 249 # '.' and '..'), func(arg, dirname, filenames) is called, where
 250 # dirname is the name of the directory and filenames is the list
 251 # files files (and subdirectories etc.) in the directory.
 252 # The func may modify the filenames list, to implement a filter,
 253 # or to impose a different order of visiting.
 254
 255 def walk(top, func, arg):
 256     """Directory tree walk whth callback function.
 257
 258     walk(top, func, arg) calls func(arg, d, files) for each directory d
 259     in the tree rooted at top (including top itself); files is a list
 260     of all the files and subdirs in directory d."""
 261     try:
 262         names = os.listdir(top)
 263     except os.error:
 264         return
 265     func(arg, top, names)
 266     exceptions = ('.', '..')
 267     for name in names:
 268         if name not in exceptions:
 269             name = join(top, name)
 270             if isdir(name):
 271                 walk(name, func, arg)
 272
 273
 274 # Expand paths beginning with '~' or '~user'.
 275 # '~' means $HOME; '~user' means that user's home directory.
 276 # If the path doesn't begin with '~', or if the user or $HOME is unknown,
 277 # the path is returned unchanged (leaving error reporting to whatever
 278 # function is called with the expanded path as argument).
 279 # See also module 'glob' for expansion of *, ? and [...] in pathnames.
 280 # (A function should also be defined to do full *sh-style environment
 281 # variable expansion.)
 282
 283 def expanduser(path):
 284     """Expand ~ and ~user constructs.
 285
 286     If user or $HOME is unknown, do nothing."""
 287     if path[:1] <> '~':
 288         return path
 289     i, n = 1, len(path)
 290     while i < n and path[i] not in '/\\':
 291         i = i+1
 292     if i == 1:
 293         if os.environ.has_key('HOME'):
 294             userhome = os.environ['HOME']
 295         elif not os.environ.has_key('HOMEPATH'):
 296             return path
 297         else:
 298             try:
 299                 drive=os.environ['HOMEDRIVE']
 300             except KeyError:
 301                 drive = ''
 302             userhome = join(drive, os.environ['HOMEPATH'])
 303     else:
 304         return path
 305     return userhome + path[i:]
 306
 307
 308 # Expand paths containing shell variable substitutions.
 309 # The following rules apply:
 310 #       - no expansion within single quotes
 311 #       - no escape character, except for '$$' which is translated into '$'
 312 #       - ${varname} is accepted.
 313 #       - varnames can be made out of letters, digits and the character '_'
 314 # XXX With COMMAND.COM you can use any characters in a variable name,
 315 # XXX except '^|<>='.
 316
 317 varchars = string.letters + string.digits + '_-'
 318
 319 def expandvars(path):
 320     """Expand shell variables of form $var and ${var}.
 321
 322     Unknown variables are left unchanged."""
 323     if '$' not in path:
 324         return path
 325     res = ''
 326     index = 0
 327     pathlen = len(path)
 328     while index < pathlen:
 329         c = path[index]
 330         if c == '\'':   # no expansion within single quotes
 331             path = path[index + 1:]
 332             pathlen = len(path)
 333             try:
 334                 index = string.index(path, '\'')
 335                 res = res + '\'' + path[:index + 1]
 336             except string.index_error:
 337                 res = res + path
 338                 index = pathlen -1
 339         elif c == '$':  # variable or '$$'
 340             if path[index + 1:index + 2] == '$':
 341                 res = res + c
 342                 index = index + 1
 343             elif path[index + 1:index + 2] == '{':
 344                 path = path[index+2:]
 345                 pathlen = len(path)
 346                 try:
 347                     index = string.index(path, '}')
 348                     var = path[:index]
 349                     if os.environ.has_key(var):
 350                         res = res + os.environ[var]
 351                 except string.index_error:
 352                     res = res + path
 353                     index = pathlen - 1
 354             else:
 355                 var = ''
 356                 index = index + 1
 357                 c = path[index:index + 1]
 358                 while c != '' and c in varchars:
 359                     var = var + c
 360                     index = index + 1
 361                     c = path[index:index + 1]
 362                 if os.environ.has_key(var):
 363                     res = res + os.environ[var]
 364                 if c != '':
 365                     res = res + c
 366         else:
 367             res = res + c
 368         index = index + 1
 369     return res
 370
 371
 372 # Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A/B.
 373 # Previously, this function also truncated pathnames to 8+3 format,
 374 # but as this module is called "ntpath", that's obviously wrong!
 375
 376 def normpath(path):
 377     """Normalize path, eliminating double slashes, etc."""
 378     path = string.replace(path, "/", "\\")
 379     prefix, path = splitdrive(path)
 380     while path[:1] == os.sep:
 381         prefix = prefix + os.sep
 382         path = path[1:]
 383     comps = string.splitfields(path, os.sep)
 384     i = 0
 385     while i < len(comps):
 386         if comps[i] == '.':
 387             del comps[i]
 388         elif comps[i] == '..' and i > 0 and comps[i-1] not in ('', '..'):
 389             del comps[i-1:i+1]
 390             i = i-1
 391         elif comps[i] == '' and i > 0 and comps[i-1] <> '':
 392             del comps[i]
 393         else:
 394             i = i+1
 395     # If the path is now empty, substitute '.'
 396     if not prefix and not comps:
 397         comps.append('.')
 398     return prefix + string.joinfields(comps, os.sep)
 399
 400
 401 # Return an absolute path.
 402 def abspath(path):
 403     """Return the absolute version of a path"""
 404     try:
 405         import win32api
 406         try:
 407             path = win32api.GetFullPathName(path)
 408         except win32api.error:
 409             pass # Bad path - return unchanged.
 410     except ImportError:
 411         if not isabs(path):
 412             path = join(os.getcwd(), path)
 413     return normpath(path)