blob: 6bf40f8336e56488739b0501fa08a009ef64bce0 [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
Skip Montanaroc62c81e2001-02-12 02:00:42 +000016__all__ = ["normcase","isabs","join","splitdrive","split","splitext",
17 "basename","dirname","commonprefix","getsize","getmtime",
18 "getatime","islink","exists","isdir","isfile","ismount",
19 "walk","expanduser","expandvars","normpath","abspath",
20 "samefile","sameopenfile","samestat"]
Guido van Rossumc6360141990-10-13 19:23:40 +000021
Guido van Rossum7ac48781992-01-14 18:29:32 +000022# Normalize the case of a pathname. Trivial in Posix, string.lower on Mac.
23# On MS-DOS this may also turn slashes into backslashes; however, other
24# normalizations (such as optimizing '../' away) are not allowed
25# (another function should be defined to do that).
26
27def normcase(s):
Guido van Rossum346f7af1997-12-05 19:04:51 +000028 """Normalize case of pathname. Has no effect under Posix"""
29 return s
Guido van Rossum7ac48781992-01-14 18:29:32 +000030
31
Jeremy Hyltona05e2932000-06-28 14:48:01 +000032# Return whether a path is absolute.
Guido van Rossum7ac48781992-01-14 18:29:32 +000033# Trivial in Posix, harder on the Mac or MS-DOS.
34
35def isabs(s):
Guido van Rossum346f7af1997-12-05 19:04:51 +000036 """Test whether a path is absolute"""
37 return s[:1] == '/'
Guido van Rossum7ac48781992-01-14 18:29:32 +000038
39
Barry Warsaw384d2491997-02-18 21:53:25 +000040# Join pathnames.
41# Ignore the previous parts if a part is absolute.
Guido van Rossum4d0fdc31991-08-16 13:27:58 +000042# Insert a '/' unless the first part is empty or already ends in '/'.
Guido van Rossum7ac48781992-01-14 18:29:32 +000043
Barry Warsaw384d2491997-02-18 21:53:25 +000044def join(a, *p):
Guido van Rossum346f7af1997-12-05 19:04:51 +000045 """Join two or more pathname components, inserting '/' as needed"""
46 path = a
47 for b in p:
48 if b[:1] == '/':
49 path = b
50 elif path == '' or path[-1:] == '/':
51 path = path + b
52 else:
53 path = path + '/' + b
54 return path
Guido van Rossumc6360141990-10-13 19:23:40 +000055
56
Guido van Rossum26847381992-03-31 18:54:35 +000057# Split a path in head (everything up to the last '/') and tail (the
Guido van Rossuma89b1ba1995-09-01 20:32:21 +000058# rest). If the path ends in '/', tail will be empty. If there is no
59# '/' in the path, head will be empty.
60# Trailing '/'es are stripped from head unless it is the root.
Guido van Rossum7ac48781992-01-14 18:29:32 +000061
Guido van Rossumc6360141990-10-13 19:23:40 +000062def split(p):
Tim Peters2344fae2001-01-15 00:50:52 +000063 """Split a pathname. Returns tuple "(head, tail)" where "tail" is
Fred Drakec0ab93e2000-09-28 16:22:52 +000064 everything after the final slash. Either part may be empty."""
Fred Drake22fb8392000-09-28 15:04:39 +000065 i = p.rfind('/') + 1
Guido van Rossum346f7af1997-12-05 19:04:51 +000066 head, tail = p[:i], p[i:]
Fred Drake8152d322000-12-12 23:20:45 +000067 if head and head != '/'*len(head):
Guido van Rossum346f7af1997-12-05 19:04:51 +000068 while head[-1] == '/':
69 head = head[:-1]
70 return head, tail
Guido van Rossumc6360141990-10-13 19:23:40 +000071
72
Guido van Rossum4d0fdc31991-08-16 13:27:58 +000073# Split a path in root and extension.
Guido van Rossum422869a1996-08-20 20:24:17 +000074# The extension is everything starting at the last dot in the last
Guido van Rossum4d0fdc31991-08-16 13:27:58 +000075# pathname component; the root is everything before that.
Guido van Rossum7ac48781992-01-14 18:29:32 +000076# It is always true that root + ext == p.
77
Guido van Rossum4d0fdc31991-08-16 13:27:58 +000078def splitext(p):
Guido van Rossum346f7af1997-12-05 19:04:51 +000079 """Split the extension from a pathname. Extension is everything from the
Fred Drakec0ab93e2000-09-28 16:22:52 +000080 last dot to the end. Returns "(root, ext)", either part may be empty."""
Guido van Rossum346f7af1997-12-05 19:04:51 +000081 root, ext = '', ''
82 for c in p:
83 if c == '/':
84 root, ext = root + ext + c, ''
85 elif c == '.':
86 if ext:
87 root, ext = root + ext, c
88 else:
89 ext = c
90 elif ext:
91 ext = ext + c
92 else:
93 root = root + c
94 return root, ext
Guido van Rossum4d0fdc31991-08-16 13:27:58 +000095
96
Guido van Rossum221df241995-08-07 20:17:55 +000097# Split a pathname into a drive specification and the rest of the
98# path. Useful on DOS/Windows/NT; on Unix, the drive is always empty.
99
100def splitdrive(p):
Tim Peters2344fae2001-01-15 00:50:52 +0000101 """Split a pathname into drive and path. On Posix, drive is always
Fred Drakec0ab93e2000-09-28 16:22:52 +0000102 empty."""
Guido van Rossum346f7af1997-12-05 19:04:51 +0000103 return '', p
Guido van Rossum221df241995-08-07 20:17:55 +0000104
105
Guido van Rossumc6360141990-10-13 19:23:40 +0000106# Return the tail (basename) part of a path.
Guido van Rossum7ac48781992-01-14 18:29:32 +0000107
Guido van Rossumc6360141990-10-13 19:23:40 +0000108def basename(p):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000109 """Returns the final component of a pathname"""
110 return split(p)[1]
Guido van Rossumc6360141990-10-13 19:23:40 +0000111
112
Guido van Rossumc629d341992-11-05 10:43:02 +0000113# Return the head (dirname) part of a path.
114
115def dirname(p):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000116 """Returns the directory component of a pathname"""
117 return split(p)[0]
Guido van Rossumc629d341992-11-05 10:43:02 +0000118
119
Guido van Rossumc6360141990-10-13 19:23:40 +0000120# Return the longest prefix of all list elements.
Guido van Rossum7ac48781992-01-14 18:29:32 +0000121
Guido van Rossumc6360141990-10-13 19:23:40 +0000122def commonprefix(m):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000123 "Given a list of pathnames, returns the longest common leading component"
124 if not m: return ''
Skip Montanaro62358312000-08-22 13:01:53 +0000125 prefix = m[0]
126 for item in m:
Guido van Rossum346f7af1997-12-05 19:04:51 +0000127 for i in range(len(prefix)):
Fred Drake8152d322000-12-12 23:20:45 +0000128 if prefix[:i+1] != item[:i+1]:
Guido van Rossum346f7af1997-12-05 19:04:51 +0000129 prefix = prefix[:i]
130 if i == 0: return ''
131 break
Skip Montanaro62358312000-08-22 13:01:53 +0000132 return prefix
Guido van Rossumc6360141990-10-13 19:23:40 +0000133
134
Guido van Rossum2bc1f8f1998-07-24 20:49:26 +0000135# Get size, mtime, atime of files.
136
137def getsize(filename):
138 """Return the size of a file, reported by os.stat()."""
139 st = os.stat(filename)
140 return st[stat.ST_SIZE]
141
142def getmtime(filename):
143 """Return the last modification time of a file, reported by os.stat()."""
144 st = os.stat(filename)
145 return st[stat.ST_MTIME]
146
147def getatime(filename):
148 """Return the last access time of a file, reported by os.stat()."""
149 st = os.stat(filename)
Guido van Rossum98118612000-02-24 02:26:51 +0000150 return st[stat.ST_ATIME]
Guido van Rossum2bc1f8f1998-07-24 20:49:26 +0000151
152
Guido van Rossum7ac48781992-01-14 18:29:32 +0000153# Is a path a symbolic link?
Guido van Rossumd3876d31996-07-23 03:47:28 +0000154# This will always return false on systems where os.lstat doesn't exist.
Guido van Rossum7ac48781992-01-14 18:29:32 +0000155
156def islink(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000157 """Test whether a path is a symbolic link"""
158 try:
159 st = os.lstat(path)
160 except (os.error, AttributeError):
161 return 0
162 return stat.S_ISLNK(st[stat.ST_MODE])
Guido van Rossum7ac48781992-01-14 18:29:32 +0000163
164
165# Does a path exist?
166# This is false for dangling symbolic links.
167
Guido van Rossumc6360141990-10-13 19:23:40 +0000168def exists(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000169 """Test whether a path exists. Returns false for broken symbolic links"""
170 try:
171 st = os.stat(path)
172 except os.error:
173 return 0
174 return 1
Guido van Rossumc6360141990-10-13 19:23:40 +0000175
176
Guido van Rossumd3876d31996-07-23 03:47:28 +0000177# Is a path a directory?
Guido van Rossum7ac48781992-01-14 18:29:32 +0000178# This follows symbolic links, so both islink() and isdir() can be true
179# for the same path.
180
Guido van Rossumc6360141990-10-13 19:23:40 +0000181def isdir(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000182 """Test whether a path is a directory"""
183 try:
184 st = os.stat(path)
185 except os.error:
186 return 0
187 return stat.S_ISDIR(st[stat.ST_MODE])
Guido van Rossumc6360141990-10-13 19:23:40 +0000188
189
Guido van Rossum26847381992-03-31 18:54:35 +0000190# Is a path a regular file?
Guido van Rossumb6775db1994-08-01 11:34:53 +0000191# This follows symbolic links, so both islink() and isfile() can be true
Guido van Rossum7ac48781992-01-14 18:29:32 +0000192# for the same path.
193
194def isfile(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000195 """Test whether a path is a regular file"""
196 try:
197 st = os.stat(path)
198 except os.error:
199 return 0
200 return stat.S_ISREG(st[stat.ST_MODE])
Guido van Rossumc6360141990-10-13 19:23:40 +0000201
202
Guido van Rossumd3778f91991-11-12 15:37:40 +0000203# Are two filenames really pointing to the same file?
Guido van Rossum7ac48781992-01-14 18:29:32 +0000204
Guido van Rossumd3778f91991-11-12 15:37:40 +0000205def samefile(f1, f2):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000206 """Test whether two pathnames reference the same actual file"""
207 s1 = os.stat(f1)
208 s2 = os.stat(f2)
209 return samestat(s1, s2)
Guido van Rossumd3778f91991-11-12 15:37:40 +0000210
211
212# Are two open files really referencing the same file?
213# (Not necessarily the same file descriptor!)
Guido van Rossum7ac48781992-01-14 18:29:32 +0000214
Guido van Rossumd3778f91991-11-12 15:37:40 +0000215def sameopenfile(fp1, fp2):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000216 """Test whether two open file objects reference the same file"""
217 s1 = os.fstat(fp1)
218 s2 = os.fstat(fp2)
219 return samestat(s1, s2)
Guido van Rossumd3778f91991-11-12 15:37:40 +0000220
221
222# Are two stat buffers (obtained from stat, fstat or lstat)
223# describing the same file?
Guido van Rossum7ac48781992-01-14 18:29:32 +0000224
Guido van Rossumd3778f91991-11-12 15:37:40 +0000225def samestat(s1, s2):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000226 """Test whether two stat buffers reference the same file"""
227 return s1[stat.ST_INO] == s2[stat.ST_INO] and \
Tim Peters2344fae2001-01-15 00:50:52 +0000228 s1[stat.ST_DEV] == s2[stat.ST_DEV]
Guido van Rossumc6360141990-10-13 19:23:40 +0000229
230
231# Is a path a mount point?
Guido van Rossumd3876d31996-07-23 03:47:28 +0000232# (Does this work for all UNIXes? Is it even guaranteed to work by Posix?)
Guido van Rossum7ac48781992-01-14 18:29:32 +0000233
Guido van Rossumc6360141990-10-13 19:23:40 +0000234def ismount(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000235 """Test whether a path is a mount point"""
236 try:
237 s1 = os.stat(path)
238 s2 = os.stat(join(path, '..'))
239 except os.error:
240 return 0 # It doesn't exist -- so not a mount point :-)
241 dev1 = s1[stat.ST_DEV]
242 dev2 = s2[stat.ST_DEV]
243 if dev1 != dev2:
244 return 1 # path/.. on a different device as path
245 ino1 = s1[stat.ST_INO]
246 ino2 = s2[stat.ST_INO]
247 if ino1 == ino2:
248 return 1 # path/.. is the same i-node as path
249 return 0
Guido van Rossumc6360141990-10-13 19:23:40 +0000250
251
252# Directory tree walk.
Guido van Rossum7ac48781992-01-14 18:29:32 +0000253# For each directory under top (including top itself, but excluding
254# '.' and '..'), func(arg, dirname, filenames) is called, where
255# dirname is the name of the directory and filenames is the list
Guido van Rossum346f7af1997-12-05 19:04:51 +0000256# of files (and subdirectories etc.) in the directory.
Guido van Rossum7ac48781992-01-14 18:29:32 +0000257# The func may modify the filenames list, to implement a filter,
Guido van Rossumc6360141990-10-13 19:23:40 +0000258# or to impose a different order of visiting.
Guido van Rossum7ac48781992-01-14 18:29:32 +0000259
Guido van Rossumc6360141990-10-13 19:23:40 +0000260def walk(top, func, arg):
Tim Peters2344fae2001-01-15 00:50:52 +0000261 """walk(top,func,arg) calls func(arg, d, files) for each directory "d"
Fred Drakec0ab93e2000-09-28 16:22:52 +0000262 in the tree rooted at "top" (including "top" itself). "files" is a list
263 of all the files and subdirs in directory "d".
264 """
Guido van Rossum346f7af1997-12-05 19:04:51 +0000265 try:
266 names = os.listdir(top)
267 except os.error:
268 return
269 func(arg, top, names)
Guido van Rossum346f7af1997-12-05 19:04:51 +0000270 for name in names:
Tim Peters2344fae2001-01-15 00:50:52 +0000271 name = join(top, name)
Guido van Rossuma490d582001-04-16 18:12:04 +0000272 try:
273 st = os.lstat(name)
274 except os.error:
275 continue
Tim Peters2344fae2001-01-15 00:50:52 +0000276 if stat.S_ISDIR(st[stat.ST_MODE]):
277 walk(name, func, arg)
Guido van Rossum7ac48781992-01-14 18:29:32 +0000278
279
280# Expand paths beginning with '~' or '~user'.
281# '~' means $HOME; '~user' means that user's home directory.
282# If the path doesn't begin with '~', or if the user or $HOME is unknown,
283# the path is returned unchanged (leaving error reporting to whatever
284# function is called with the expanded path as argument).
285# See also module 'glob' for expansion of *, ? and [...] in pathnames.
286# (A function should also be defined to do full *sh-style environment
287# variable expansion.)
288
289def expanduser(path):
Tim Peters2344fae2001-01-15 00:50:52 +0000290 """Expand ~ and ~user constructions. If user or $HOME is unknown,
Fred Drakec0ab93e2000-09-28 16:22:52 +0000291 do nothing."""
Fred Drake8152d322000-12-12 23:20:45 +0000292 if path[:1] != '~':
Guido van Rossum346f7af1997-12-05 19:04:51 +0000293 return path
294 i, n = 1, len(path)
Fred Drake8152d322000-12-12 23:20:45 +0000295 while i < n and path[i] != '/':
Fred Drakec0ab93e2000-09-28 16:22:52 +0000296 i = i + 1
Guido van Rossum346f7af1997-12-05 19:04:51 +0000297 if i == 1:
298 if not os.environ.has_key('HOME'):
299 return path
300 userhome = os.environ['HOME']
301 else:
302 import pwd
303 try:
304 pwent = pwd.getpwnam(path[1:i])
305 except KeyError:
306 return path
307 userhome = pwent[5]
Fred Drakec0ab93e2000-09-28 16:22:52 +0000308 if userhome[-1:] == '/': i = i + 1
Guido van Rossum346f7af1997-12-05 19:04:51 +0000309 return userhome + path[i:]
Guido van Rossum4732ccf1992-08-09 13:54:50 +0000310
311
312# Expand paths containing shell variable substitutions.
Guido van Rossumb6775db1994-08-01 11:34:53 +0000313# This expands the forms $variable and ${variable} only.
Jeremy Hyltona05e2932000-06-28 14:48:01 +0000314# Non-existent variables are left unchanged.
Guido van Rossumb6775db1994-08-01 11:34:53 +0000315
316_varprog = None
Guido van Rossum4732ccf1992-08-09 13:54:50 +0000317
318def expandvars(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000319 """Expand shell variables of form $var and ${var}. Unknown variables
Fred Drakec0ab93e2000-09-28 16:22:52 +0000320 are left unchanged."""
Guido van Rossum346f7af1997-12-05 19:04:51 +0000321 global _varprog
322 if '$' not in path:
323 return path
324 if not _varprog:
325 import re
326 _varprog = re.compile(r'\$(\w+|\{[^}]*\})')
327 i = 0
328 while 1:
329 m = _varprog.search(path, i)
330 if not m:
331 break
332 i, j = m.span(0)
333 name = m.group(1)
334 if name[:1] == '{' and name[-1:] == '}':
335 name = name[1:-1]
336 if os.environ.has_key(name):
337 tail = path[j:]
338 path = path[:i] + os.environ[name]
339 i = len(path)
340 path = path + tail
341 else:
342 i = j
343 return path
Guido van Rossumc629d341992-11-05 10:43:02 +0000344
345
346# Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A/B.
347# It should be understood that this may change the meaning of the path
348# if it contains symbolic links!
349
350def normpath(path):
Guido van Rossum346f7af1997-12-05 19:04:51 +0000351 """Normalize path, eliminating double slashes, etc."""
Skip Montanaro018dfae2000-07-19 17:09:51 +0000352 if path == '':
353 return '.'
Marc-André Lemburgbf222c92001-01-29 11:29:44 +0000354 initial_slashes = path.startswith('/')
355 # POSIX allows one or two initial slashes, but treats three or more
356 # as single slash.
Tim Peters658cba62001-02-09 20:06:00 +0000357 if (initial_slashes and
Marc-André Lemburgbf222c92001-01-29 11:29:44 +0000358 path.startswith('//') and not path.startswith('///')):
359 initial_slashes = 2
Fred Drake22fb8392000-09-28 15:04:39 +0000360 comps = path.split('/')
Skip Montanaro018dfae2000-07-19 17:09:51 +0000361 new_comps = []
362 for comp in comps:
363 if comp in ('', '.'):
364 continue
Marc-André Lemburgbf222c92001-01-29 11:29:44 +0000365 if (comp != '..' or (not initial_slashes and not new_comps) or
Skip Montanaro018dfae2000-07-19 17:09:51 +0000366 (new_comps and new_comps[-1] == '..')):
367 new_comps.append(comp)
368 elif new_comps:
369 new_comps.pop()
370 comps = new_comps
Fred Drake22fb8392000-09-28 15:04:39 +0000371 path = '/'.join(comps)
Marc-André Lemburgbf222c92001-01-29 11:29:44 +0000372 if initial_slashes:
373 path = '/'*initial_slashes + path
Skip Montanaro018dfae2000-07-19 17:09:51 +0000374 return path or '.'
Guido van Rossume294cf61999-01-29 18:05:18 +0000375
376
Guido van Rossume294cf61999-01-29 18:05:18 +0000377def abspath(path):
Guido van Rossum54f22ed2000-02-04 15:10:34 +0000378 """Return an absolute path."""
Guido van Rossume294cf61999-01-29 18:05:18 +0000379 if not isabs(path):
380 path = join(os.getcwd(), path)
381 return normpath(path)