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 import genericpath
  16 from genericpath import *
  17
  18 __all__ = ["normcase","isabs","join","splitdrive","split","splitext",
  19            "basename","dirname","commonprefix","getsize","getmtime",
  20            "getatime","getctime","islink","exists","lexists","isdir","isfile",
  21            "ismount","walk","expanduser","expandvars","normpath","abspath",
  22            "samefile","sameopenfile","samestat",
  23            "curdir","pardir","sep","pathsep","defpath","altsep","extsep",
  24            "devnull","realpath","supports_unicode_filenames","relpath"]
  25
  26 # strings representing various path-related bits and pieces
  27 curdir = '.'
  28 pardir = '..'
  29 extsep = '.'
  30 sep = '/'
  31 pathsep = ':'
  32 defpath = ':/bin:/usr/bin'
  33 altsep = None
  34 devnull = '/dev/null'
  35
  36 # Normalize the case of a pathname.  Trivial in Posix, string.lower on Mac.
  37 # On MS-DOS this may also turn slashes into backslashes; however, other
  38 # normalizations (such as optimizing '../' away) are not allowed
  39 # (another function should be defined to do that).
  40
  41 def normcase(s):
  42     """Normalize case of pathname.  Has no effect under Posix"""
  43     return s
  44
  45
  46 # Return whether a path is absolute.
  47 # Trivial in Posix, harder on the Mac or MS-DOS.
  48
  49 def isabs(s):
  50     """Test whether a path is absolute"""
  51     return s.startswith('/')
  52
  53
  54 # Join pathnames.
  55 # Ignore the previous parts if a part is absolute.
  56 # Insert a '/' unless the first part is empty or already ends in '/'.
  57
  58 def join(a, *p):
  59     """Join two or more pathname components, inserting '/' as needed"""
  60     path = a
  61     for b in p:
  62         if b.startswith('/'):
  63             path = b
  64         elif path == '' or path.endswith('/'):
  65             path +=  b
  66         else:
  67             path += '/' + b
  68     return path
  69
  70
  71 # Split a path in head (everything up to the last '/') and tail (the
  72 # rest).  If the path ends in '/', tail will be empty.  If there is no
  73 # '/' in the path, head  will be empty.
  74 # Trailing '/'es are stripped from head unless it is the root.
  75
  76 def split(p):
  77     """Split a pathname.  Returns tuple "(head, tail)" where "tail" is
  78     everything after the final slash.  Either part may be empty."""
  79     i = p.rfind('/') + 1
  80     head, tail = p[:i], p[i:]
  81     if head and head != '/'*len(head):
  82         head = head.rstrip('/')
  83     return head, tail
  84
  85
  86 # Split a path in root and extension.
  87 # The extension is everything starting at the last dot in the last
  88 # pathname component; the root is everything before that.
  89 # It is always true that root + ext == p.
  90
  91 def splitext(p):
  92     return genericpath._splitext(p, sep, altsep, extsep)
  93 splitext.__doc__ = genericpath._splitext.__doc__
  94
  95 # Split a pathname into a drive specification and the rest of the
  96 # path.  Useful on DOS/Windows/NT; on Unix, the drive is always empty.
  97
  98 def splitdrive(p):
  99     """Split a pathname into drive and path. On Posix, drive is always
 100     empty."""
 101     return '', p
 102
 103
 104 # Return the tail (basename) part of a path, same as split(path)[1].
 105
 106 def basename(p):
 107     """Returns the final component of a pathname"""
 108     i = p.rfind('/') + 1
 109     return p[i:]
 110
 111
 112 # Return the head (dirname) part of a path, same as split(path)[0].
 113
 114 def dirname(p):
 115     """Returns the directory component of a pathname"""
 116     i = p.rfind('/') + 1
 117     head = p[:i]
 118     if head and head != '/'*len(head):
 119         head = head.rstrip('/')
 120     return head
 121
 122
 123 # Is a path a symbolic link?
 124 # This will always return false on systems where os.lstat doesn't exist.
 125
 126 def islink(path):
 127     """Test whether a path is a symbolic link"""
 128     try:
 129         st = os.lstat(path)
 130     except (os.error, AttributeError):
 131         return False
 132     return stat.S_ISLNK(st.st_mode)
 133
 134 # Being true for dangling symbolic links is also useful.
 135
 136 def lexists(path):
 137     """Test whether a path exists.  Returns True for broken symbolic links"""
 138     try:
 139         st = os.lstat(path)
 140     except os.error:
 141         return False
 142     return True
 143
 144
 145 # Are two filenames really pointing to the same file?
 146
 147 def samefile(f1, f2):
 148     """Test whether two pathnames reference the same actual file"""
 149     s1 = os.stat(f1)
 150     s2 = os.stat(f2)
 151     return samestat(s1, s2)
 152
 153
 154 # Are two open files really referencing the same file?
 155 # (Not necessarily the same file descriptor!)
 156
 157 def sameopenfile(fp1, fp2):
 158     """Test whether two open file objects reference the same file"""
 159     s1 = os.fstat(fp1)
 160     s2 = os.fstat(fp2)
 161     return samestat(s1, s2)
 162
 163
 164 # Are two stat buffers (obtained from stat, fstat or lstat)
 165 # describing the same file?
 166
 167 def samestat(s1, s2):
 168     """Test whether two stat buffers reference the same file"""
 169     return s1.st_ino == s2.st_ino and \
 170            s1.st_dev == s2.st_dev
 171
 172
 173 # Is a path a mount point?
 174 # (Does this work for all UNIXes?  Is it even guaranteed to work by Posix?)
 175
 176 def ismount(path):
 177     """Test whether a path is a mount point"""
 178     try:
 179         s1 = os.stat(path)
 180         s2 = os.stat(join(path, '..'))
 181     except os.error:
 182         return False # It doesn't exist -- so not a mount point :-)
 183     dev1 = s1.st_dev
 184     dev2 = s2.st_dev
 185     if dev1 != dev2:
 186         return True     # path/.. on a different device as path
 187     ino1 = s1.st_ino
 188     ino2 = s2.st_ino
 189     if ino1 == ino2:
 190         return True     # path/.. is the same i-node as path
 191     return False
 192
 193
 194 # Directory tree walk.
 195 # For each directory under top (including top itself, but excluding
 196 # '.' and '..'), func(arg, dirname, filenames) is called, where
 197 # dirname is the name of the directory and filenames is the list
 198 # of files (and subdirectories etc.) in the directory.
 199 # The func may modify the filenames list, to implement a filter,
 200 # or to impose a different order of visiting.
 201
 202 def walk(top, func, arg):
 203     """Directory tree walk with callback function.
 204
 205     For each directory in the directory tree rooted at top (including top
 206     itself, but excluding '.' and '..'), call func(arg, dirname, fnames).
 207     dirname is the name of the directory, and fnames a list of the names of
 208     the files and subdirectories in dirname (excluding '.' and '..').  func
 209     may modify the fnames list in-place (e.g. via del or slice assignment),
 210     and walk will only recurse into the subdirectories whose names remain in
 211     fnames; this can be used to implement a filter, or to impose a specific
 212     order of visiting.  No semantics are defined for, or required of, arg,
 213     beyond that arg is always passed to func.  It can be used, e.g., to pass
 214     a filename pattern, or a mutable object designed to accumulate
 215     statistics.  Passing None for arg is common."""
 216
 217     try:
 218         names = os.listdir(top)
 219     except os.error:
 220         return
 221     func(arg, top, names)
 222     for name in names:
 223         name = join(top, name)
 224         try:
 225             st = os.lstat(name)
 226         except os.error:
 227             continue
 228         if stat.S_ISDIR(st.st_mode):
 229             walk(name, func, arg)
 230
 231
 232 # Expand paths beginning with '~' or '~user'.
 233 # '~' means $HOME; '~user' means that user's home directory.
 234 # If the path doesn't begin with '~', or if the user or $HOME is unknown,
 235 # the path is returned unchanged (leaving error reporting to whatever
 236 # function is called with the expanded path as argument).
 237 # See also module 'glob' for expansion of *, ? and [...] in pathnames.
 238 # (A function should also be defined to do full *sh-style environment
 239 # variable expansion.)
 240
 241 def expanduser(path):
 242     """Expand ~ and ~user constructions.  If user or $HOME is unknown,
 243     do nothing."""
 244     if not path.startswith('~'):
 245         return path
 246     i = path.find('/', 1)
 247     if i < 0:
 248         i = len(path)
 249     if i == 1:
 250         if 'HOME' not in os.environ:
 251             import pwd
 252             userhome = pwd.getpwuid(os.getuid()).pw_dir
 253         else:
 254             userhome = os.environ['HOME']
 255     else:
 256         import pwd
 257         try:
 258             pwent = pwd.getpwnam(path[1:i])
 259         except KeyError:
 260             return path
 261         userhome = pwent.pw_dir
 262     userhome = userhome.rstrip('/')
 263     return userhome + path[i:]
 264
 265
 266 # Expand paths containing shell variable substitutions.
 267 # This expands the forms $variable and ${variable} only.
 268 # Non-existent variables are left unchanged.
 269
 270 _varprog = None
 271
 272 def expandvars(path):
 273     """Expand shell variables of form $var and ${var}.  Unknown variables
 274     are left unchanged."""
 275     global _varprog
 276     if '$' not in path:
 277         return path
 278     if not _varprog:
 279         import re
 280         _varprog = re.compile(r'\$(\w+|\{[^}]*\})')
 281     i = 0
 282     while True:
 283         m = _varprog.search(path, i)
 284         if not m:
 285             break
 286         i, j = m.span(0)
 287         name = m.group(1)
 288         if name.startswith('{') and name.endswith('}'):
 289             name = name[1:-1]
 290         if name in os.environ:
 291             tail = path[j:]
 292             path = path[:i] + os.environ[name]
 293             i = len(path)
 294             path += tail
 295         else:
 296             i = j
 297     return path
 298
 299
 300 # Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A/B.
 301 # It should be understood that this may change the meaning of the path
 302 # if it contains symbolic links!
 303
 304 def normpath(path):
 305     """Normalize path, eliminating double slashes, etc."""
 306     if path == '':
 307         return '.'
 308     initial_slashes = path.startswith('/')
 309     # POSIX allows one or two initial slashes, but treats three or more
 310     # as single slash.
 311     if (initial_slashes and
 312         path.startswith('//') and not path.startswith('///')):
 313         initial_slashes = 2
 314     comps = path.split('/')
 315     new_comps = []
 316     for comp in comps:
 317         if comp in ('', '.'):
 318             continue
 319         if (comp != '..' or (not initial_slashes and not new_comps) or
 320              (new_comps and new_comps[-1] == '..')):
 321             new_comps.append(comp)
 322         elif new_comps:
 323             new_comps.pop()
 324     comps = new_comps
 325     path = '/'.join(comps)
 326     if initial_slashes:
 327         path = '/'*initial_slashes + path
 328     return path or '.'
 329
 330
 331 def abspath(path):
 332     """Return an absolute path."""
 333     if not isabs(path):
 334         path = join(os.getcwd(), path)
 335     return normpath(path)
 336
 337
 338 # Return a canonical path (i.e. the absolute location of a file on the
 339 # filesystem).
 340
 341 def realpath(filename):
 342     """Return the canonical path of the specified filename, eliminating any
 343 symbolic links encountered in the path."""
 344     if isabs(filename):
 345         bits = ['/'] + filename.split('/')[1:]
 346     else:
 347         bits = [''] + filename.split('/')
 348
 349     for i in range(2, len(bits)+1):
 350         component = join(*bits[0:i])
 351         # Resolve symbolic links.
 352         if islink(component):
 353             resolved = _resolve_link(component)
 354             if resolved is None:
 355                 # Infinite loop -- return original component + rest of the path
 356                 return abspath(join(*([component] + bits[i:])))
 357             else:
 358                 newpath = join(*([resolved] + bits[i:]))
 359                 return realpath(newpath)
 360
 361     return abspath(filename)
 362
 363
 364 def _resolve_link(path):
 365     """Internal helper function.  Takes a path and follows symlinks
 366     until we either arrive at something that isn't a symlink, or
 367     encounter a path we've seen before (meaning that there's a loop).
 368     """
 369     paths_seen = []
 370     while islink(path):
 371         if path in paths_seen:
 372             # Already seen this path, so we must have a symlink loop
 373             return None
 374         paths_seen.append(path)
 375         # Resolve where the link points to
 376         resolved = os.readlink(path)
 377         if not isabs(resolved):
 378             dir = dirname(path)
 379             path = normpath(join(dir, resolved))
 380         else:
 381             path = normpath(resolved)
 382     return path
 383
 384 supports_unicode_filenames = False
 385
 386 def relpath(path, start=curdir):
 387     """Return a relative version of a path"""
 388
 389     if not path:
 390         raise ValueError("no path specified")
 391
 392     start_list = abspath(start).split(sep)
 393     path_list = abspath(path).split(sep)
 394
 395     # Work out how much of the filepath is shared by start and path.
 396     i = len(commonprefix([start_list, path_list]))
 397
 398     rel_list = [pardir] * (len(start_list)-i) + path_list[i:]
 399     return join(*rel_list)