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 wheter 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     prefix = m[0]
 122     for item in m:
 123         for i in range(len(prefix)):
 124             if prefix[:i+1] <> item[:i+1]:
 125                 prefix = prefix[:i]
 126                 if i == 0: return ''
 127                 break
 128     return prefix
 129
 130
 131 # Get size, mtime, atime of files.
 132
 133 def getsize(filename):
 134     """Return the size of a file, reported by os.stat()."""
 135     st = os.stat(filename)
 136     return st[stat.ST_SIZE]
 137
 138 def getmtime(filename):
 139     """Return the last modification time of a file, reported by os.stat()."""
 140     st = os.stat(filename)
 141     return st[stat.ST_MTIME]
 142
 143 def getatime(filename):
 144     """Return the last access time of a file, reported by os.stat()."""
 145     st = os.stat(filename)
 146     return st[stat.ST_MTIME]
 147
 148
 149 # Is a path a symbolic link?
 150 # This will always return false on systems where os.lstat doesn't exist.
 151
 152 def islink(path):
 153     """Test whether a path is a symbolic link"""
 154     try:
 155         st = os.lstat(path)
 156     except (os.error, AttributeError):
 157         return 0
 158     return stat.S_ISLNK(st[stat.ST_MODE])
 159
 160
 161 # Does a path exist?
 162 # This is false for dangling symbolic links.
 163
 164 def exists(path):
 165     """Test whether a path exists.  Returns false for broken symbolic links"""
 166     try:
 167         st = os.stat(path)
 168     except os.error:
 169         return 0
 170     return 1
 171
 172
 173 # Is a path a directory?
 174 # This follows symbolic links, so both islink() and isdir() can be true
 175 # for the same path.
 176
 177 def isdir(path):
 178     """Test whether a path is a directory"""
 179     try:
 180         st = os.stat(path)
 181     except os.error:
 182         return 0
 183     return stat.S_ISDIR(st[stat.ST_MODE])
 184
 185
 186 # Is a path a regular file?
 187 # This follows symbolic links, so both islink() and isfile() can be true
 188 # for the same path.
 189
 190 def isfile(path):
 191     """Test whether a path is a regular file"""
 192     try:
 193         st = os.stat(path)
 194     except os.error:
 195         return 0
 196     return stat.S_ISREG(st[stat.ST_MODE])
 197
 198
 199 # Are two filenames really pointing to the same file?
 200
 201 def samefile(f1, f2):
 202     """Test whether two pathnames reference the same actual file"""
 203     s1 = os.stat(f1)
 204     s2 = os.stat(f2)
 205     return samestat(s1, s2)
 206
 207
 208 # Are two open files really referencing the same file?
 209 # (Not necessarily the same file descriptor!)
 210
 211 def sameopenfile(fp1, fp2):
 212     """Test whether two open file objects reference the same file"""
 213     s1 = os.fstat(fp1)
 214     s2 = os.fstat(fp2)
 215     return samestat(s1, s2)
 216
 217
 218 # Are two stat buffers (obtained from stat, fstat or lstat)
 219 # describing the same file?
 220
 221 def samestat(s1, s2):
 222     """Test whether two stat buffers reference the same file"""
 223     return s1[stat.ST_INO] == s2[stat.ST_INO] and \
 224            s1[stat.ST_DEV] == s2[stat.ST_DEV]
 225
 226
 227 # Is a path a mount point?
 228 # (Does this work for all UNIXes?  Is it even guaranteed to work by Posix?)
 229
 230 def ismount(path):
 231     """Test whether a path is a mount point"""
 232     try:
 233         s1 = os.stat(path)
 234         s2 = os.stat(join(path, '..'))
 235     except os.error:
 236         return 0 # It doesn't exist -- so not a mount point :-)
 237     dev1 = s1[stat.ST_DEV]
 238     dev2 = s2[stat.ST_DEV]
 239     if dev1 != dev2:
 240         return 1        # path/.. on a different device as path
 241     ino1 = s1[stat.ST_INO]
 242     ino2 = s2[stat.ST_INO]
 243     if ino1 == ino2:
 244         return 1        # path/.. is the same i-node as path
 245     return 0
 246
 247
 248 # Directory tree walk.
 249 # For each directory under top (including top itself, but excluding
 250 # '.' and '..'), func(arg, dirname, filenames) is called, where
 251 # dirname is the name of the directory and filenames is the list
 252 # of files (and subdirectories etc.) in the directory.
 253 # The func may modify the filenames list, to implement a filter,
 254 # or to impose a different order of visiting.
 255
 256 def walk(top, func, arg):
 257     """walk(top,func,arg) calls func(arg, d, files) for each directory "d"
 258 in the tree  rooted at "top" (including "top" itself).  "files" is a list
 259 of all the files and subdirs in directory "d".
 260 """
 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) and not islink(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 constructions.  If user or $HOME is unknown,
 285 do nothing"""
 286     if path[:1] <> '~':
 287         return path
 288     i, n = 1, len(path)
 289     while i < n and path[i] <> '/':
 290         i = i+1
 291     if i == 1:
 292         if not os.environ.has_key('HOME'):
 293             return path
 294         userhome = os.environ['HOME']
 295     else:
 296         import pwd
 297         try:
 298             pwent = pwd.getpwnam(path[1:i])
 299         except KeyError:
 300             return path
 301         userhome = pwent[5]
 302     if userhome[-1:] == '/': i = i+1
 303     return userhome + path[i:]
 304
 305
 306 # Expand paths containing shell variable substitutions.
 307 # This expands the forms $variable and ${variable} only.
 308 # Non-existant variables are left unchanged.
 309
 310 _varprog = None
 311
 312 def expandvars(path):
 313     """Expand shell variables of form $var and ${var}.  Unknown variables
 314 are left unchanged"""
 315     global _varprog
 316     if '$' not in path:
 317         return path
 318     if not _varprog:
 319         import re
 320         _varprog = re.compile(r'\$(\w+|\{[^}]*\})')
 321     i = 0
 322     while 1:
 323         m = _varprog.search(path, i)
 324         if not m:
 325             break
 326         i, j = m.span(0)
 327         name = m.group(1)
 328         if name[:1] == '{' and name[-1:] == '}':
 329             name = name[1:-1]
 330         if os.environ.has_key(name):
 331             tail = path[j:]
 332             path = path[:i] + os.environ[name]
 333             i = len(path)
 334             path = path + tail
 335         else:
 336             i = j
 337     return path
 338
 339
 340 # Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A/B.
 341 # It should be understood that this may change the meaning of the path
 342 # if it contains symbolic links!
 343
 344 def normpath(path):
 345     """Normalize path, eliminating double slashes, etc."""
 346     import string
 347     # Treat initial slashes specially
 348     slashes = ''
 349     while path[:1] == '/':
 350         slashes = slashes + '/'
 351         path = path[1:]
 352     comps = string.splitfields(path, '/')
 353     i = 0
 354     while i < len(comps):
 355         if comps[i] == '.':
 356             del comps[i]
 357             while i < len(comps) and comps[i] == '':
 358                 del comps[i]
 359         elif comps[i] == '..' and i > 0 and comps[i-1] not in ('', '..'):
 360             del comps[i-1:i+1]
 361             i = i-1
 362         elif comps[i] == '' and i > 0 and comps[i-1] <> '':
 363             del comps[i]
 364         else:
 365             i = i+1
 366     # If the path is now empty, substitute '.'
 367     if not comps and not slashes:
 368         comps.append('.')
 369     return slashes + string.joinfields(comps, '/')
 370
 371
 372 def abspath(path):
 373     """Return an absolute path."""
 374     if not isabs(path):
 375         path = join(os.getcwd(), path)
 376     return normpath(path)