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 __all__ = ["normcase","isabs","join","splitdrive","split","splitext",
  17            "basename","dirname","commonprefix","getsize","getmtime",
  18            "getatime","islink","exists","isdir","isfile","ismount",
  19            "walk","expanduser","expandvars","normpath","abspath",
  20            "samefile","sameopenfile","samestat"]
  21
  22 # Normalize the case of a pathname.  Trivial in Posix, string.lower on Mac.
  23 # On MS-DOS this may also turn slashes into backslashes; however, other
  24 # normalizations (such as optimizing '../' away) are not allowed
  25 # (another function should be defined to do that).
  26
  27 def normcase(s):
  28     """Normalize case of pathname.  Has no effect under Posix"""
  29     return s
  30
  31
  32 # Return whether a path is absolute.
  33 # Trivial in Posix, harder on the Mac or MS-DOS.
  34
  35 def isabs(s):
  36     """Test whether a path is absolute"""
  37     return s[:1] == '/'
  38
  39
  40 # Join pathnames.
  41 # Ignore the previous parts if a part is absolute.
  42 # Insert a '/' unless the first part is empty or already ends in '/'.
  43
  44 def join(a, *p):
  45     """Join two or more pathname components, inserting '/' as needed"""
  46     path = a
  47     for b in p:
  48         if b[:1] == '/':
  49             path = b
  50         elif path == '' or path[-1:] == '/':
  51             path = path + b
  52         else:
  53             path = path + '/' + b
  54     return path
  55
  56
  57 # Split a path in head (everything up to the last '/') and tail (the
  58 # rest).  If the path ends in '/', tail will be empty.  If there is no
  59 # '/' in the path, head  will be empty.
  60 # Trailing '/'es are stripped from head unless it is the root.
  61
  62 def split(p):
  63     """Split a pathname.  Returns tuple "(head, tail)" where "tail" is
  64     everything after the final slash.  Either part may be empty."""
  65     i = p.rfind('/') + 1
  66     head, tail = p[:i], p[i:]
  67     if head and head != '/'*len(head):
  68         while head[-1] == '/':
  69             head = head[:-1]
  70     return head, tail
  71
  72
  73 # Split a path in root and extension.
  74 # The extension is everything starting at the last dot in the last
  75 # pathname component; the root is everything before that.
  76 # It is always true that root + ext == p.
  77
  78 def splitext(p):
  79     """Split the extension from a pathname.  Extension is everything from the
  80     last dot to the end.  Returns "(root, ext)", either part may be empty."""
  81     root, ext = '', ''
  82     for c in p:
  83         if c == '/':
  84             root, ext = root + ext + c, ''
  85         elif c == '.':
  86             if ext:
  87                 root, ext = root + ext, c
  88             else:
  89                 ext = c
  90         elif ext:
  91             ext = ext + c
  92         else:
  93             root = root + c
  94     return root, ext
  95
  96
  97 # Split a pathname into a drive specification and the rest of the
  98 # path.  Useful on DOS/Windows/NT; on Unix, the drive is always empty.
  99
 100 def splitdrive(p):
 101     """Split a pathname into drive and path. On Posix, drive is always
 102     empty."""
 103     return '', p
 104
 105
 106 # Return the tail (basename) part of a path.
 107
 108 def basename(p):
 109     """Returns the final component of a pathname"""
 110     return split(p)[1]
 111
 112
 113 # Return the head (dirname) part of a path.
 114
 115 def dirname(p):
 116     """Returns the directory component of a pathname"""
 117     return split(p)[0]
 118
 119
 120 # Return the longest prefix of all list elements.
 121
 122 def commonprefix(m):
 123     "Given a list of pathnames, returns the longest common leading component"
 124     if not m: return ''
 125     prefix = m[0]
 126     for item in m:
 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 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         try:
 273             st = os.lstat(name)
 274         except os.error:
 275             continue
 276         if stat.S_ISDIR(st[stat.ST_MODE]):
 277             walk(name, func, arg)
 278
 279
 280 # Expand paths beginning with '~' or '~user'.
 281 # '~' means $HOME; '~user' means that user's home directory.
 282 # If the path doesn't begin with '~', or if the user or $HOME is unknown,
 283 # the path is returned unchanged (leaving error reporting to whatever
 284 # function is called with the expanded path as argument).
 285 # See also module 'glob' for expansion of *, ? and [...] in pathnames.
 286 # (A function should also be defined to do full *sh-style environment
 287 # variable expansion.)
 288
 289 def expanduser(path):
 290     """Expand ~ and ~user constructions.  If user or $HOME is unknown,
 291     do nothing."""
 292     if path[:1] != '~':
 293         return path
 294     i, n = 1, len(path)
 295     while i < n and path[i] != '/':
 296         i = i + 1
 297     if i == 1:
 298         if not os.environ.has_key('HOME'):
 299             return path
 300         userhome = os.environ['HOME']
 301     else:
 302         import pwd
 303         try:
 304             pwent = pwd.getpwnam(path[1:i])
 305         except KeyError:
 306             return path
 307         userhome = pwent[5]
 308     if userhome[-1:] == '/': i = i + 1
 309     return userhome + path[i:]
 310
 311
 312 # Expand paths containing shell variable substitutions.
 313 # This expands the forms $variable and ${variable} only.
 314 # Non-existent variables are left unchanged.
 315
 316 _varprog = None
 317
 318 def expandvars(path):
 319     """Expand shell variables of form $var and ${var}.  Unknown variables
 320     are left unchanged."""
 321     global _varprog
 322     if '$' not in path:
 323         return path
 324     if not _varprog:
 325         import re
 326         _varprog = re.compile(r'\$(\w+|\{[^}]*\})')
 327     i = 0
 328     while 1:
 329         m = _varprog.search(path, i)
 330         if not m:
 331             break
 332         i, j = m.span(0)
 333         name = m.group(1)
 334         if name[:1] == '{' and name[-1:] == '}':
 335             name = name[1:-1]
 336         if os.environ.has_key(name):
 337             tail = path[j:]
 338             path = path[:i] + os.environ[name]
 339             i = len(path)
 340             path = path + tail
 341         else:
 342             i = j
 343     return path
 344
 345
 346 # Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A/B.
 347 # It should be understood that this may change the meaning of the path
 348 # if it contains symbolic links!
 349
 350 def normpath(path):
 351     """Normalize path, eliminating double slashes, etc."""
 352     if path == '':
 353         return '.'
 354     initial_slashes = path.startswith('/')
 355     # POSIX allows one or two initial slashes, but treats three or more
 356     # as single slash.
 357     if (initial_slashes and
 358         path.startswith('//') and not path.startswith('///')):
 359         initial_slashes = 2
 360     comps = path.split('/')
 361     new_comps = []
 362     for comp in comps:
 363         if comp in ('', '.'):
 364             continue
 365         if (comp != '..' or (not initial_slashes and not new_comps) or
 366              (new_comps and new_comps[-1] == '..')):
 367             new_comps.append(comp)
 368         elif new_comps:
 369             new_comps.pop()
 370     comps = new_comps
 371     path = '/'.join(comps)
 372     if initial_slashes:
 373         path = '/'*initial_slashes + path
 374     return path or '.'
 375
 376
 377 def abspath(path):
 378     """Return an absolute path."""
 379     if not isabs(path):
 380         path = join(os.getcwd(), path)
 381     return normpath(path)
 382
 383
 384 # Return a canonical path (i.e. the absolute location of a file on the
 385 # filesystem).
 386
 387 def realpath(filename):
 388     """Return the canonical path of the specified filename, eliminating any
 389 symbolic links encountered in the path."""
 390     filename = abspath(filename)
 391
 392     bits = ['/'] + filename.split('/')[1:]
 393     for i in range(2, len(bits)+1):
 394         component = join(*bits[0:i])
 395         if islink(component):
 396             resolved = os.readlink(component)
 397             (dir, file) = split(component)
 398             resolved = normpath(join(dir, resolved))
 399             newpath = join(*([resolved] + bits[i:]))
 400             return realpath(newpath)
 401
 402     return filename