blob: fb3b6a64f987638facd72da654d7ce4db5f61dcf [file] [log] [blame]
Guido van Rossumd3876d31996-07-23 03:47:28 +00001# Module 'posixpath' -- common operations on Posix pathnames.
2# Some of this can actually be useful on non-Posix systems too, e.g.
3# for manipulation of the pathname component of URLs.
4# The "os.path" name is an alias for this module on Posix systems;
5# on other systems (e.g. Mac, Windows), os.path provides the same
6# operations in a manner specific to that platform, and is an alias
7# to another module (e.g. macpath, ntpath).
Guido van Rossum346f7af1997-12-05 19:04:51 +00008"""Common pathname manipulations, Posix version.
9Instead of importing this module
10directly, import os and refer to this module as os.path.
11"""
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
27# Return wheter a path is absolute.
28# 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 ''
121 prefix = m[0]
122 for item in m:
123 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
128 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)
146 return st[stat.ST_MTIME]
147
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 Rossum346f7af1997-12-05 19:04:51 +0000257 """walk(top,func,args) calls func(arg, d, files) for each directory "d"
258in 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)
266 exceptions = ('.', '..')
267 for name in names:
268 if name not in exceptions:
269 name = join(top, name)
270 if isdir(name) and not islink(name):
271 walk(name, func, arg)
Guido van Rossum7ac48781992-01-14 18:29:32 +0000272
273
274# Expand paths beginning with '~' or '~user'.
275# '~' means $HOME; '~user' means that user's home directory.
276# If the path doesn't begin with '~', or if the user or $HOME is unknown,
277# the path is returned unchanged (leaving error reporting to whatever
278# function is called with the expanded path as argument).
279# See also module 'glob' for expansion of *, ? and [...] in pathnames.
280# (A function should also be defined to do full *sh-style environment
281# variable expansion.)
282
283def expanduser(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000284 """Expand ~ and ~user constructions. If user or $HOME is unknown,
285do nothing"""
286 if path[:1] <> '~':
287 return path
288 i, n = 1, len(path)
289 while i < n and path[i] <> '/':
290 i = i+1
291 if i == 1:
292 if not os.environ.has_key('HOME'):
293 return path
294 userhome = os.environ['HOME']
295 else:
296 import pwd
297 try:
298 pwent = pwd.getpwnam(path[1:i])
299 except KeyError:
300 return path
301 userhome = pwent[5]
302 if userhome[-1:] == '/': i = i+1
303 return userhome + path[i:]
Guido van Rossum4732ccf1992-08-09 13:54:50 +0000304
305
306# Expand paths containing shell variable substitutions.
Guido van Rossumb6775db1994-08-01 11:34:53 +0000307# This expands the forms $variable and ${variable} only.
308# Non-existant variables are left unchanged.
309
310_varprog = None
Guido van Rossum4732ccf1992-08-09 13:54:50 +0000311
312def expandvars(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000313 """Expand shell variables of form $var and ${var}. Unknown variables
314are left unchanged"""
315 global _varprog
316 if '$' not in path:
317 return path
318 if not _varprog:
319 import re
320 _varprog = re.compile(r'\$(\w+|\{[^}]*\})')
321 i = 0
322 while 1:
323 m = _varprog.search(path, i)
324 if not m:
325 break
326 i, j = m.span(0)
327 name = m.group(1)
328 if name[:1] == '{' and name[-1:] == '}':
329 name = name[1:-1]
330 if os.environ.has_key(name):
331 tail = path[j:]
332 path = path[:i] + os.environ[name]
333 i = len(path)
334 path = path + tail
335 else:
336 i = j
337 return path
Guido van Rossumc629d341992-11-05 10:43:02 +0000338
339
340# Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A/B.
341# It should be understood that this may change the meaning of the path
342# if it contains symbolic links!
343
344def normpath(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000345 """Normalize path, eliminating double slashes, etc."""
346 import string
347 # Treat initial slashes specially
348 slashes = ''
349 while path[:1] == '/':
350 slashes = slashes + '/'
351 path = path[1:]
352 comps = string.splitfields(path, '/')
353 i = 0
354 while i < len(comps):
355 if comps[i] == '.':
356 del comps[i]
Guido van Rossuma0633031998-09-08 22:28:06 +0000357 while i < len(comps) and comps[i] == '':
358 del comps[i]
Guido van Rossum346f7af1997-12-05 19:04:51 +0000359 elif comps[i] == '..' and i > 0 and comps[i-1] not in ('', '..'):
360 del comps[i-1:i+1]
361 i = i-1
362 elif comps[i] == '' and i > 0 and comps[i-1] <> '':
363 del comps[i]
364 else:
365 i = i+1
366 # If the path is now empty, substitute '.'
367 if not comps and not slashes:
368 comps.append('.')
369 return slashes + string.joinfields(comps, '/')