blob: f7e01613cd71da022cca7b7cfedc3a858e91050f [file] [log] [blame]
Guido van Rossum54f22ed2000-02-04 15:10:34 +00001"""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.
Guido van Rossum346f7af1997-12-05 19:04:51 +000011"""
Guido van Rossumc6360141990-10-13 19:23:40 +000012
Guido van Rossumd3876d31996-07-23 03:47:28 +000013import os
Guido van Rossum40d93041990-10-21 16:17:34 +000014import stat
Guido van Rossumc6360141990-10-13 19:23:40 +000015
16
Guido van Rossum7ac48781992-01-14 18:29:32 +000017# 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
22def normcase(s):
Guido van Rossum346f7af1997-12-05 19:04:51 +000023 """Normalize case of pathname. Has no effect under Posix"""
24 return s
Guido van Rossum7ac48781992-01-14 18:29:32 +000025
26
Jeremy Hyltona05e2932000-06-28 14:48:01 +000027# Return whether a path is absolute.
Guido van Rossum7ac48781992-01-14 18:29:32 +000028# Trivial in Posix, harder on the Mac or MS-DOS.
29
30def isabs(s):
Guido van Rossum346f7af1997-12-05 19:04:51 +000031 """Test whether a path is absolute"""
32 return s[:1] == '/'
Guido van Rossum7ac48781992-01-14 18:29:32 +000033
34
Barry Warsaw384d2491997-02-18 21:53:25 +000035# Join pathnames.
36# Ignore the previous parts if a part is absolute.
Guido van Rossum4d0fdc31991-08-16 13:27:58 +000037# Insert a '/' unless the first part is empty or already ends in '/'.
Guido van Rossum7ac48781992-01-14 18:29:32 +000038
Barry Warsaw384d2491997-02-18 21:53:25 +000039def join(a, *p):
Guido van Rossum346f7af1997-12-05 19:04:51 +000040 """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
Guido van Rossumc6360141990-10-13 19:23:40 +000050
51
Guido van Rossum26847381992-03-31 18:54:35 +000052# Split a path in head (everything up to the last '/') and tail (the
Guido van Rossuma89b1ba1995-09-01 20:32:21 +000053# 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.
Guido van Rossum7ac48781992-01-14 18:29:32 +000056
Guido van Rossumc6360141990-10-13 19:23:40 +000057def split(p):
Guido van Rossum346f7af1997-12-05 19:04:51 +000058 """Split a pathname. Returns tuple "(head, tail)" where "tail" is
59everything 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
Guido van Rossumc6360141990-10-13 19:23:40 +000067
68
Guido van Rossum4d0fdc31991-08-16 13:27:58 +000069# Split a path in root and extension.
Guido van Rossum422869a1996-08-20 20:24:17 +000070# The extension is everything starting at the last dot in the last
Guido van Rossum4d0fdc31991-08-16 13:27:58 +000071# pathname component; the root is everything before that.
Guido van Rossum7ac48781992-01-14 18:29:32 +000072# It is always true that root + ext == p.
73
Guido van Rossum4d0fdc31991-08-16 13:27:58 +000074def splitext(p):
Guido van Rossum346f7af1997-12-05 19:04:51 +000075 """Split the extension from a pathname. Extension is everything from the
76last 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
Guido van Rossum4d0fdc31991-08-16 13:27:58 +000091
92
Guido van Rossum221df241995-08-07 20:17:55 +000093# 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
96def splitdrive(p):
Guido van Rossum346f7af1997-12-05 19:04:51 +000097 """Split a pathname into drive and path. On Posix, drive is always
98empty"""
99 return '', p
Guido van Rossum221df241995-08-07 20:17:55 +0000100
101
Guido van Rossumc6360141990-10-13 19:23:40 +0000102# Return the tail (basename) part of a path.
Guido van Rossum7ac48781992-01-14 18:29:32 +0000103
Guido van Rossumc6360141990-10-13 19:23:40 +0000104def basename(p):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000105 """Returns the final component of a pathname"""
106 return split(p)[1]
Guido van Rossumc6360141990-10-13 19:23:40 +0000107
108
Guido van Rossumc629d341992-11-05 10:43:02 +0000109# Return the head (dirname) part of a path.
110
111def dirname(p):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000112 """Returns the directory component of a pathname"""
113 return split(p)[0]
Guido van Rossumc629d341992-11-05 10:43:02 +0000114
115
Guido van Rossumc6360141990-10-13 19:23:40 +0000116# Return the longest prefix of all list elements.
Guido van Rossum7ac48781992-01-14 18:29:32 +0000117
Guido van Rossumc6360141990-10-13 19:23:40 +0000118def commonprefix(m):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000119 "Given a list of pathnames, returns the longest common leading component"
120 if not m: return ''
Skip Montanaro62358312000-08-22 13:01:53 +0000121 prefix = m[0]
122 for item in m:
Guido van Rossum346f7af1997-12-05 19:04:51 +0000123 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
Skip Montanaro62358312000-08-22 13:01:53 +0000128 return prefix
Guido van Rossumc6360141990-10-13 19:23:40 +0000129
130
Guido van Rossum2bc1f8f1998-07-24 20:49:26 +0000131# Get size, mtime, atime of files.
132
133def 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
138def 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
143def getatime(filename):
144 """Return the last access time of a file, reported by os.stat()."""
145 st = os.stat(filename)
Guido van Rossum98118612000-02-24 02:26:51 +0000146 return st[stat.ST_ATIME]
Guido van Rossum2bc1f8f1998-07-24 20:49:26 +0000147
148
Guido van Rossum7ac48781992-01-14 18:29:32 +0000149# Is a path a symbolic link?
Guido van Rossumd3876d31996-07-23 03:47:28 +0000150# This will always return false on systems where os.lstat doesn't exist.
Guido van Rossum7ac48781992-01-14 18:29:32 +0000151
152def islink(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000153 """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])
Guido van Rossum7ac48781992-01-14 18:29:32 +0000159
160
161# Does a path exist?
162# This is false for dangling symbolic links.
163
Guido van Rossumc6360141990-10-13 19:23:40 +0000164def exists(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000165 """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
Guido van Rossumc6360141990-10-13 19:23:40 +0000171
172
Guido van Rossumd3876d31996-07-23 03:47:28 +0000173# Is a path a directory?
Guido van Rossum7ac48781992-01-14 18:29:32 +0000174# This follows symbolic links, so both islink() and isdir() can be true
175# for the same path.
176
Guido van Rossumc6360141990-10-13 19:23:40 +0000177def isdir(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000178 """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])
Guido van Rossumc6360141990-10-13 19:23:40 +0000184
185
Guido van Rossum26847381992-03-31 18:54:35 +0000186# Is a path a regular file?
Guido van Rossumb6775db1994-08-01 11:34:53 +0000187# This follows symbolic links, so both islink() and isfile() can be true
Guido van Rossum7ac48781992-01-14 18:29:32 +0000188# for the same path.
189
190def isfile(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000191 """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])
Guido van Rossumc6360141990-10-13 19:23:40 +0000197
198
Guido van Rossumd3778f91991-11-12 15:37:40 +0000199# Are two filenames really pointing to the same file?
Guido van Rossum7ac48781992-01-14 18:29:32 +0000200
Guido van Rossumd3778f91991-11-12 15:37:40 +0000201def samefile(f1, f2):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000202 """Test whether two pathnames reference the same actual file"""
203 s1 = os.stat(f1)
204 s2 = os.stat(f2)
205 return samestat(s1, s2)
Guido van Rossumd3778f91991-11-12 15:37:40 +0000206
207
208# Are two open files really referencing the same file?
209# (Not necessarily the same file descriptor!)
Guido van Rossum7ac48781992-01-14 18:29:32 +0000210
Guido van Rossumd3778f91991-11-12 15:37:40 +0000211def sameopenfile(fp1, fp2):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000212 """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)
Guido van Rossumd3778f91991-11-12 15:37:40 +0000216
217
218# Are two stat buffers (obtained from stat, fstat or lstat)
219# describing the same file?
Guido van Rossum7ac48781992-01-14 18:29:32 +0000220
Guido van Rossumd3778f91991-11-12 15:37:40 +0000221def samestat(s1, s2):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000222 """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]
Guido van Rossumc6360141990-10-13 19:23:40 +0000225
226
227# Is a path a mount point?
Guido van Rossumd3876d31996-07-23 03:47:28 +0000228# (Does this work for all UNIXes? Is it even guaranteed to work by Posix?)
Guido van Rossum7ac48781992-01-14 18:29:32 +0000229
Guido van Rossumc6360141990-10-13 19:23:40 +0000230def ismount(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000231 """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
Guido van Rossumc6360141990-10-13 19:23:40 +0000246
247
248# Directory tree walk.
Guido van Rossum7ac48781992-01-14 18:29:32 +0000249# 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
Guido van Rossum346f7af1997-12-05 19:04:51 +0000252# of files (and subdirectories etc.) in the directory.
Guido van Rossum7ac48781992-01-14 18:29:32 +0000253# The func may modify the filenames list, to implement a filter,
Guido van Rossumc6360141990-10-13 19:23:40 +0000254# or to impose a different order of visiting.
Guido van Rossum7ac48781992-01-14 18:29:32 +0000255
Guido van Rossumc6360141990-10-13 19:23:40 +0000256def walk(top, func, arg):
Guido van Rossumf618a481999-11-02 13:29:08 +0000257 """walk(top,func,arg) calls func(arg, d, files) for each directory "d"
Guido van Rossum346f7af1997-12-05 19:04:51 +0000258in the tree rooted at "top" (including "top" itself). "files" is a list
259of 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)
Guido van Rossum346f7af1997-12-05 19:04:51 +0000266 for name in names:
Guido van Rossum346f7af1997-12-05 19:04:51 +0000267 name = join(top, name)
Guido van Rossum84a74592000-02-28 14:27:07 +0000268 st = os.lstat(name)
269 if stat.S_ISDIR(st[stat.ST_MODE]):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000270 walk(name, func, arg)
Guido van Rossum7ac48781992-01-14 18:29:32 +0000271
272
273# Expand paths beginning with '~' or '~user'.
274# '~' means $HOME; '~user' means that user's home directory.
275# If the path doesn't begin with '~', or if the user or $HOME is unknown,
276# the path is returned unchanged (leaving error reporting to whatever
277# function is called with the expanded path as argument).
278# See also module 'glob' for expansion of *, ? and [...] in pathnames.
279# (A function should also be defined to do full *sh-style environment
280# variable expansion.)
281
282def expanduser(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000283 """Expand ~ and ~user constructions. If user or $HOME is unknown,
284do nothing"""
285 if path[:1] <> '~':
286 return path
287 i, n = 1, len(path)
288 while i < n and path[i] <> '/':
289 i = i+1
290 if i == 1:
291 if not os.environ.has_key('HOME'):
292 return path
293 userhome = os.environ['HOME']
294 else:
295 import pwd
296 try:
297 pwent = pwd.getpwnam(path[1:i])
298 except KeyError:
299 return path
300 userhome = pwent[5]
301 if userhome[-1:] == '/': i = i+1
302 return userhome + path[i:]
Guido van Rossum4732ccf1992-08-09 13:54:50 +0000303
304
305# Expand paths containing shell variable substitutions.
Guido van Rossumb6775db1994-08-01 11:34:53 +0000306# This expands the forms $variable and ${variable} only.
Jeremy Hyltona05e2932000-06-28 14:48:01 +0000307# Non-existent variables are left unchanged.
Guido van Rossumb6775db1994-08-01 11:34:53 +0000308
309_varprog = None
Guido van Rossum4732ccf1992-08-09 13:54:50 +0000310
311def expandvars(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000312 """Expand shell variables of form $var and ${var}. Unknown variables
313are left unchanged"""
314 global _varprog
315 if '$' not in path:
316 return path
317 if not _varprog:
318 import re
319 _varprog = re.compile(r'\$(\w+|\{[^}]*\})')
320 i = 0
321 while 1:
322 m = _varprog.search(path, i)
323 if not m:
324 break
325 i, j = m.span(0)
326 name = m.group(1)
327 if name[:1] == '{' and name[-1:] == '}':
328 name = name[1:-1]
329 if os.environ.has_key(name):
330 tail = path[j:]
331 path = path[:i] + os.environ[name]
332 i = len(path)
333 path = path + tail
334 else:
335 i = j
336 return path
Guido van Rossumc629d341992-11-05 10:43:02 +0000337
338
339# Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A/B.
340# It should be understood that this may change the meaning of the path
341# if it contains symbolic links!
342
343def normpath(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000344 """Normalize path, eliminating double slashes, etc."""
Skip Montanaro018dfae2000-07-19 17:09:51 +0000345 if path == '':
346 return '.'
Guido van Rossum346f7af1997-12-05 19:04:51 +0000347 import string
Skip Montanaro018dfae2000-07-19 17:09:51 +0000348 initial_slash = (path[0] == '/')
349 comps = string.split(path, '/')
350 new_comps = []
351 for comp in comps:
352 if comp in ('', '.'):
353 continue
354 if (comp != '..' or (not initial_slash and not new_comps) or
355 (new_comps and new_comps[-1] == '..')):
356 new_comps.append(comp)
357 elif new_comps:
358 new_comps.pop()
359 comps = new_comps
360 path = string.join(comps, '/')
361 if initial_slash:
362 path = '/' + path
363 return path or '.'
Guido van Rossume294cf61999-01-29 18:05:18 +0000364
365
Guido van Rossume294cf61999-01-29 18:05:18 +0000366def abspath(path):
Guido van Rossum54f22ed2000-02-04 15:10:34 +0000367 """Return an absolute path."""
Guido van Rossume294cf61999-01-29 18:05:18 +0000368 if not isabs(path):
369 path = join(os.getcwd(), path)
370 return normpath(path)