Lib/posixpath.py

   1 """Common operations on Posix pathnames.
   2
   3 Instead of importing this module directly, import os and refer to
   4 this module as os.path.  The "os.path" name is an alias for this
   5 module on Posix systems; on other systems (e.g. Mac, Windows),
   6 os.path provides the same operations in a manner specific to that
   7 platform, and is an alias to another module (e.g. macpath, ntpath).
   8
   9 Some of this can actually be useful on non-Posix systems too, e.g.
  10 for manipulation of the pathname component of URLs.
  11 """
  12
  13 import os
  14 import stat
  15
  16
  17 # Normalize the case of a pathname.  Trivial in Posix, string.lower on Mac.
  18 # On MS-DOS this may also turn slashes into backslashes; however, other
  19 # normalizations (such as optimizing '../' away) are not allowed
  20 # (another function should be defined to do that).
  21
  22 def normcase(s):
  23     """Normalize case of pathname.  Has no effect under Posix"""
  24     return s
  25
  26
  27 # Return whether a path is absolute.
  28 # Trivial in Posix, harder on the Mac or MS-DOS.
  29
  30 def isabs(s):
  31     """Test whether a path is absolute"""
  32     return s[:1] == '/'
  33
  34
  35 # Join pathnames.
  36 # Ignore the previous parts if a part is absolute.
  37 # Insert a '/' unless the first part is empty or already ends in '/'.
  38
  39 def join(a, *p):
  40     """Join two or more pathname components, inserting '/' as needed"""
  41     path = a
  42     for b in p:
  43         if b[:1] == '/':
  44             path = b
  45         elif path == '' or path[-1:] == '/':
  46             path = path + b
  47         else:
  48             path = path + '/' + b
  49     return path
  50
  51
  52 # Split a path in head (everything up to the last '/') and tail (the
  53 # rest).  If the path ends in '/', tail will be empty.  If there is no
  54 # '/' in the path, head  will be empty.
  55 # Trailing '/'es are stripped from head unless it is the root.
  56
  57 def split(p):
  58     """Split a pathname.  Returns tuple "(head, tail)" where "tail" is
  59 everything after the final slash.  Either part may be empty"""
  60     import string
  61     i = string.rfind(p, '/') + 1
  62     head, tail = p[:i], p[i:]
  63     if head and head <> '/'*len(head):
  64         while head[-1] == '/':
  65             head = head[:-1]
  66     return head, tail
  67
  68
  69 # Split a path in root and extension.
  70 # The extension is everything starting at the last dot in the last
  71 # pathname component; the root is everything before that.
  72 # It is always true that root + ext == p.
  73
  74 def splitext(p):
  75     """Split the extension from a pathname.  Extension is everything from the
  76 last dot to the end.  Returns "(root, ext)", either part may be empty"""
  77     root, ext = '', ''
  78     for c in p:
  79         if c == '/':
  80             root, ext = root + ext + c, ''
  81         elif c == '.':
  82             if ext:
  83                 root, ext = root + ext, c
  84             else:
  85                 ext = c
  86         elif ext:
  87             ext = ext + c
  88         else:
  89             root = root + c
  90     return root, ext
  91
  92
  93 # Split a pathname into a drive specification and the rest of the
  94 # path.  Useful on DOS/Windows/NT; on Unix, the drive is always empty.
  95
  96 def splitdrive(p):
  97     """Split a pathname into drive and path. On Posix, drive is always
  98 empty"""
  99     return '', p
 100
 101
 102 # Return the tail (basename) part of a path.
 103
 104 def basename(p):
 105     """Returns the final component of a pathname"""
 106     return split(p)[1]
 107
 108
 109 # Return the head (dirname) part of a path.
 110
 111 def dirname(p):
 112     """Returns the directory component of a pathname"""
 113     return split(p)[0]
 114
 115
 116 # Return the longest prefix of all list elements.
 117
 118 def commonprefix(m):
 119     "Given a list of pathnames, returns the longest common leading component"
 120     if not m: return ''
 121     n = m[:]
 122     for i in range(len(n)):
 123         n[i] = n[i].split("/")
 124
 125     prefix = n[0]
 126     for item in n:
 127         for i in range(len(prefix)):
 128             if prefix[:i+1] <> item[:i+1]:
 129                 prefix = prefix[:i]
 130                 if i == 0: return ''
 131                 break
 132     return "/".join(prefix)
 133
 134
 135 # Get size, mtime, atime of files.
 136
 137 def getsize(filename):
 138     """Return the size of a file, reported by os.stat()."""
 139     st = os.stat(filename)
 140     return st[stat.ST_SIZE]
 141
 142 def getmtime(filename):
 143     """Return the last modification time of a file, reported by os.stat()."""
 144     st = os.stat(filename)
 145     return st[stat.ST_MTIME]
 146
 147 def getatime(filename):
 148     """Return the last access time of a file, reported by os.stat()."""
 149     st = os.stat(filename)
 150     return st[stat.ST_ATIME]
 151
 152
 153 # Is a path a symbolic link?
 154 # This will always return false on systems where os.lstat doesn't exist.
 155
 156 def islink(path):
 157     """Test whether a path is a symbolic link"""
 158     try:
 159         st = os.lstat(path)
 160     except (os.error, AttributeError):
 161         return 0
 162     return stat.S_ISLNK(st[stat.ST_MODE])
 163
 164
 165 # Does a path exist?
 166 # This is false for dangling symbolic links.
 167
 168 def exists(path):
 169     """Test whether a path exists.  Returns false for broken symbolic links"""
 170     try:
 171         st = os.stat(path)
 172     except os.error:
 173         return 0
 174     return 1
 175
 176
 177 # Is a path a directory?
 178 # This follows symbolic links, so both islink() and isdir() can be true
 179 # for the same path.
 180
 181 def isdir(path):
 182     """Test whether a path is a directory"""
 183     try:
 184         st = os.stat(path)
 185     except os.error:
 186         return 0
 187     return stat.S_ISDIR(st[stat.ST_MODE])
 188
 189
 190 # Is a path a regular file?
 191 # This follows symbolic links, so both islink() and isfile() can be true
 192 # for the same path.
 193
 194 def isfile(path):
 195     """Test whether a path is a regular file"""
 196     try:
 197         st = os.stat(path)
 198     except os.error:
 199         return 0
 200     return stat.S_ISREG(st[stat.ST_MODE])
 201
 202
 203 # Are two filenames really pointing to the same file?
 204
 205 def samefile(f1, f2):
 206     """Test whether two pathnames reference the same actual file"""
 207     s1 = os.stat(f1)
 208     s2 = os.stat(f2)
 209     return samestat(s1, s2)
 210
 211
 212 # Are two open files really referencing the same file?
 213 # (Not necessarily the same file descriptor!)
 214
 215 def sameopenfile(fp1, fp2):
 216     """Test whether two open file objects reference the same file"""
 217     s1 = os.fstat(fp1)
 218     s2 = os.fstat(fp2)
 219     return samestat(s1, s2)
 220
 221
 222 # Are two stat buffers (obtained from stat, fstat or lstat)
 223 # describing the same file?
 224
 225 def samestat(s1, s2):
 226     """Test whether two stat buffers reference the same file"""
 227     return s1[stat.ST_INO] == s2[stat.ST_INO] and \
 228            s1[stat.ST_DEV] == s2[stat.ST_DEV]
 229
 230
 231 # Is a path a mount point?
 232 # (Does this work for all UNIXes?  Is it even guaranteed to work by Posix?)
 233
 234 def ismount(path):
 235     """Test whether a path is a mount point"""
 236     try:
 237         s1 = os.stat(path)
 238         s2 = os.stat(join(path, '..'))
 239     except os.error:
 240         return 0 # It doesn't exist -- so not a mount point :-)
 241     dev1 = s1[stat.ST_DEV]
 242     dev2 = s2[stat.ST_DEV]
 243     if dev1 != dev2:
 244         return 1        # path/.. on a different device as path
 245     ino1 = s1[stat.ST_INO]
 246     ino2 = s2[stat.ST_INO]
 247     if ino1 == ino2:
 248         return 1        # path/.. is the same i-node as path
 249     return 0
 250
 251
 252 # Directory tree walk.
 253 # For each directory under top (including top itself, but excluding
 254 # '.' and '..'), func(arg, dirname, filenames) is called, where
 255 # dirname is the name of the directory and filenames is the list
 256 # of files (and subdirectories etc.) in the directory.
 257 # The func may modify the filenames list, to implement a filter,
 258 # or to impose a different order of visiting.
 259
 260 def walk(top, func, arg):
 261     """walk(top,func,arg) calls func(arg, d, files) for each directory "d"
 262 in the tree  rooted at "top" (including "top" itself).  "files" is a list
 263 of all the files and subdirs in directory "d".
 264 """
 265     try:
 266         names = os.listdir(top)
 267     except os.error:
 268         return
 269     func(arg, top, names)
 270     for name in names:
 271             name = join(top, name)
 272             st = os.lstat(name)
 273             if stat.S_ISDIR(st[stat.ST_MODE]):
 274                 walk(name, func, arg)
 275
 276
 277 # Expand paths beginning with '~' or '~user'.
 278 # '~' means $HOME; '~user' means that user's home directory.
 279 # If the path doesn't begin with '~', or if the user or $HOME is unknown,
 280 # the path is returned unchanged (leaving error reporting to whatever
 281 # function is called with the expanded path as argument).
 282 # See also module 'glob' for expansion of *, ? and [...] in pathnames.
 283 # (A function should also be defined to do full *sh-style environment
 284 # variable expansion.)
 285
 286 def expanduser(path):
 287     """Expand ~ and ~user constructions.  If user or $HOME is unknown,
 288 do nothing"""
 289     if path[:1] <> '~':
 290         return path
 291     i, n = 1, len(path)
 292     while i < n and path[i] <> '/':
 293         i = i+1
 294     if i == 1:
 295         if not os.environ.has_key('HOME'):
 296             return path
 297         userhome = os.environ['HOME']
 298     else:
 299         import pwd
 300         try:
 301             pwent = pwd.getpwnam(path[1:i])
 302         except KeyError:
 303             return path
 304         userhome = pwent[5]
 305     if userhome[-1:] == '/': i = i+1
 306     return userhome + path[i:]
 307
 308
 309 # Expand paths containing shell variable substitutions.
 310 # This expands the forms $variable and ${variable} only.
 311 # Non-existent variables are left unchanged.
 312
 313 _varprog = None
 314
 315 def expandvars(path):
 316     """Expand shell variables of form $var and ${var}.  Unknown variables
 317 are left unchanged"""
 318     global _varprog
 319     if '$' not in path:
 320         return path
 321     if not _varprog:
 322         import re
 323         _varprog = re.compile(r'\$(\w+|\{[^}]*\})')
 324     i = 0
 325     while 1:
 326         m = _varprog.search(path, i)
 327         if not m:
 328             break
 329         i, j = m.span(0)
 330         name = m.group(1)
 331         if name[:1] == '{' and name[-1:] == '}':
 332             name = name[1:-1]
 333         if os.environ.has_key(name):
 334             tail = path[j:]
 335             path = path[:i] + os.environ[name]
 336             i = len(path)
 337             path = path + tail
 338         else:
 339             i = j
 340     return path
 341
 342
 343 # Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A/B.
 344 # It should be understood that this may change the meaning of the path
 345 # if it contains symbolic links!
 346
 347 def normpath(path):
 348     """Normalize path, eliminating double slashes, etc."""
 349     if path == '':
 350         return '.'
 351     import string
 352     initial_slash = (path[0] == '/')
 353     comps = string.split(path, '/')
 354     new_comps = []
 355     for comp in comps:
 356         if comp in ('', '.'):
 357             continue
 358         if (comp != '..' or (not initial_slash and not new_comps) or
 359              (new_comps and new_comps[-1] == '..')):
 360             new_comps.append(comp)
 361         elif new_comps:
 362             new_comps.pop()
 363     comps = new_comps
 364     path = string.join(comps, '/')
 365     if initial_slash:
 366         path = '/' + path
 367     return path or '.'
 368
 369
 370 def abspath(path):
 371     """Return an absolute path."""
 372     if not isabs(path):
 373         path = join(os.getcwd(), path)
 374     return normpath(path)