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