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