blob: 51e60a2eddb32d81f773bfba7d49e33f2893224a [file] [log] [blame]
Guido van Rossum15e22e11997-12-05 19:03:01 +00001# Module 'ntpath' -- common operations on WinNT/Win95 pathnames
2"""Common pathname manipulations, WindowsNT/95 version.
Guido van Rossum534972b1999-02-03 17:20:50 +00003
4Instead of importing this module directly, import os and refer to this
5module as os.path.
Guido van Rossum15e22e11997-12-05 19:03:01 +00006"""
Guido van Rossum555915a1994-02-24 11:32:59 +00007
8import os
9import stat
10import string
11
12
Guido van Rossume2ad88c1997-08-12 14:46:58 +000013# Normalize the case of a pathname and map slashes to backslashes.
14# Other normalizations (such as optimizing '../' away) are not done
Guido van Rossum555915a1994-02-24 11:32:59 +000015# (this is done by normpath).
Guido van Rossume2ad88c1997-08-12 14:46:58 +000016
Guido van Rossum555915a1994-02-24 11:32:59 +000017def normcase(s):
Guido van Rossum16a0bc21998-02-18 13:48:31 +000018 """Normalize case of pathname.
19
Guido van Rossum534972b1999-02-03 17:20:50 +000020 Makes all characters lowercase and all slashes into backslashes."""
Guido van Rossum16a0bc21998-02-18 13:48:31 +000021 return string.lower(string.replace(s, "/", "\\"))
Guido van Rossum555915a1994-02-24 11:32:59 +000022
Guido van Rossum77e1db31997-06-02 23:11:57 +000023
Fred Drakeef0b5dd2000-02-17 17:30:40 +000024# Return whether a path is absolute.
Guido van Rossum555915a1994-02-24 11:32:59 +000025# Trivial in Posix, harder on the Mac or MS-DOS.
26# For DOS it is absolute if it starts with a slash or backslash (current
Guido van Rossum534972b1999-02-03 17:20:50 +000027# volume), or if a pathname after the volume letter and colon / UNC resource
28# starts with a slash or backslash.
Guido van Rossum555915a1994-02-24 11:32:59 +000029
30def isabs(s):
Guido van Rossum15e22e11997-12-05 19:03:01 +000031 """Test whether a path is absolute"""
32 s = splitdrive(s)[1]
33 return s != '' and s[:1] in '/\\'
Guido van Rossum555915a1994-02-24 11:32:59 +000034
35
Guido van Rossum77e1db31997-06-02 23:11:57 +000036# Join two (or more) paths.
37
Barry Warsaw384d2491997-02-18 21:53:25 +000038def join(a, *p):
Guido van Rossum15e22e11997-12-05 19:03:01 +000039 """Join two or more pathname components, inserting "\\" as needed"""
40 path = a
41 for b in p:
42 if isabs(b):
43 path = b
44 elif path == '' or path[-1:] in '/\\':
45 path = path + b
46 else:
47 path = path + os.sep + b
48 return path
Guido van Rossum555915a1994-02-24 11:32:59 +000049
50
51# Split a path in a drive specification (a drive letter followed by a
Guido van Rossumf3c695c1999-04-06 19:32:19 +000052# colon) and the path specification.
Guido van Rossum555915a1994-02-24 11:32:59 +000053# It is always true that drivespec + pathspec == p
54def splitdrive(p):
Guido van Rossumf3c695c1999-04-06 19:32:19 +000055 """Split a pathname into drive and path specifiers. Returns a 2-tuple
56"(drive,path)"; either part may be empty"""
Guido van Rossum15e22e11997-12-05 19:03:01 +000057 if p[1:2] == ':':
58 return p[0:2], p[2:]
Guido van Rossumf3c695c1999-04-06 19:32:19 +000059 return '', p
60
61
62# Parse UNC paths
63def splitunc(p):
64 """Split a pathname into UNC mount point and relative path specifiers.
65
66 Return a 2-tuple (unc, rest); either part may be empty.
67 If unc is not empty, it has the form '//host/mount' (or similar
68 using backslashes). unc+rest is always the input path.
69 Paths containing drive letters never have an UNC part.
70 """
71 if p[1:2] == ':':
72 return '', p # Drive letter present
Guido van Rossum534972b1999-02-03 17:20:50 +000073 firstTwo = p[0:2]
74 if firstTwo == '//' or firstTwo == '\\\\':
75 # is a UNC path:
76 # vvvvvvvvvvvvvvvvvvvv equivalent to drive letter
77 # \\machine\mountpoint\directories...
78 # directory ^^^^^^^^^^^^^^^
79 normp = normcase(p)
80 index = string.find(normp, '\\', 2)
81 if index == -1:
82 ##raise RuntimeError, 'illegal UNC path: "' + p + '"'
83 return ("", p)
84 index = string.find(normp, '\\', index + 1)
85 if index == -1:
86 index = len(p)
87 return p[:index], p[index:]
Guido van Rossum15e22e11997-12-05 19:03:01 +000088 return '', p
Guido van Rossum555915a1994-02-24 11:32:59 +000089
90
91# Split a path in head (everything up to the last '/') and tail (the
Guido van Rossum8f0fa9e1999-03-19 21:05:12 +000092# rest). After the trailing '/' is stripped, the invariant
Guido van Rossum555915a1994-02-24 11:32:59 +000093# join(head, tail) == p holds.
94# The resulting head won't end in '/' unless it is the root.
95
96def split(p):
Guido van Rossum534972b1999-02-03 17:20:50 +000097 """Split a pathname.
98
99 Return tuple (head, tail) where tail is everything after the final slash.
100 Either part may be empty."""
Guido van Rossum8f0fa9e1999-03-19 21:05:12 +0000101
Guido van Rossum15e22e11997-12-05 19:03:01 +0000102 d, p = splitdrive(p)
Guido van Rossum8f0fa9e1999-03-19 21:05:12 +0000103 # set i to index beyond p's last slash
104 i = len(p)
105 while i and p[i-1] not in '/\\':
106 i = i - 1
107 head, tail = p[:i], p[i:] # now tail has no slashes
108 # remove trailing slashes from head, unless it's all slashes
109 head2 = head
110 while head2 and head2[-1] in '/\\':
111 head2 = head2[:-1]
112 head = head2 or head
Guido van Rossum15e22e11997-12-05 19:03:01 +0000113 return d + head, tail
Guido van Rossum555915a1994-02-24 11:32:59 +0000114
115
116# Split a path in root and extension.
Guido van Rossum73e122f1997-01-22 00:17:26 +0000117# The extension is everything starting at the last dot in the last
Guido van Rossum555915a1994-02-24 11:32:59 +0000118# pathname component; the root is everything before that.
119# It is always true that root + ext == p.
120
121def splitext(p):
Guido van Rossum534972b1999-02-03 17:20:50 +0000122 """Split the extension from a pathname.
123
124 Extension is everything from the last dot to the end.
125 Return (root, ext), either part may be empty."""
Guido van Rossum15e22e11997-12-05 19:03:01 +0000126 root, ext = '', ''
127 for c in p:
128 if c in ['/','\\']:
129 root, ext = root + ext + c, ''
130 elif c == '.':
131 if ext:
132 root, ext = root + ext, c
133 else:
134 ext = c
135 elif ext:
136 ext = ext + c
137 else:
138 root = root + c
139 return root, ext
Guido van Rossum555915a1994-02-24 11:32:59 +0000140
141
142# Return the tail (basename) part of a path.
143
144def basename(p):
Guido van Rossum15e22e11997-12-05 19:03:01 +0000145 """Returns the final component of a pathname"""
146 return split(p)[1]
Guido van Rossum555915a1994-02-24 11:32:59 +0000147
148
149# Return the head (dirname) part of a path.
150
151def dirname(p):
Guido van Rossum15e22e11997-12-05 19:03:01 +0000152 """Returns the directory component of a pathname"""
153 return split(p)[0]
Guido van Rossum555915a1994-02-24 11:32:59 +0000154
155
156# Return the longest prefix of all list elements.
157
158def commonprefix(m):
Guido van Rossum15e22e11997-12-05 19:03:01 +0000159 "Given a list of pathnames, returns the longest common leading component"
160 if not m: return ''
161 prefix = m[0]
162 for item in m:
163 for i in range(len(prefix)):
164 if prefix[:i+1] <> item[:i+1]:
165 prefix = prefix[:i]
166 if i == 0: return ''
167 break
168 return prefix
Guido van Rossum555915a1994-02-24 11:32:59 +0000169
170
Guido van Rossum2bc1f8f1998-07-24 20:49:26 +0000171# Get size, mtime, atime of files.
172
173def getsize(filename):
Guido van Rossum534972b1999-02-03 17:20:50 +0000174 """Return the size of a file, reported by os.stat()"""
Guido van Rossum2bc1f8f1998-07-24 20:49:26 +0000175 st = os.stat(filename)
176 return st[stat.ST_SIZE]
177
178def getmtime(filename):
Guido van Rossum534972b1999-02-03 17:20:50 +0000179 """Return the last modification time of a file, reported by os.stat()"""
Guido van Rossum2bc1f8f1998-07-24 20:49:26 +0000180 st = os.stat(filename)
181 return st[stat.ST_MTIME]
182
183def getatime(filename):
Guido van Rossum534972b1999-02-03 17:20:50 +0000184 """Return the last access time of a file, reported by os.stat()"""
Guido van Rossum2bc1f8f1998-07-24 20:49:26 +0000185 st = os.stat(filename)
186 return st[stat.ST_MTIME]
187
188
Guido van Rossum555915a1994-02-24 11:32:59 +0000189# Is a path a symbolic link?
190# This will always return false on systems where posix.lstat doesn't exist.
191
192def islink(path):
Guido van Rossum15e22e11997-12-05 19:03:01 +0000193 """Test for symbolic link. On WindowsNT/95 always returns false"""
194 return 0
Guido van Rossum555915a1994-02-24 11:32:59 +0000195
196
197# Does a path exist?
198# This is false for dangling symbolic links.
199
200def exists(path):
Guido van Rossum15e22e11997-12-05 19:03:01 +0000201 """Test whether a path exists"""
202 try:
203 st = os.stat(path)
204 except os.error:
205 return 0
206 return 1
Guido van Rossum555915a1994-02-24 11:32:59 +0000207
208
209# Is a path a dos directory?
210# This follows symbolic links, so both islink() and isdir() can be true
211# for the same path.
212
213def isdir(path):
Guido van Rossum15e22e11997-12-05 19:03:01 +0000214 """Test whether a path is a directory"""
215 try:
216 st = os.stat(path)
217 except os.error:
218 return 0
219 return stat.S_ISDIR(st[stat.ST_MODE])
Guido van Rossum555915a1994-02-24 11:32:59 +0000220
221
222# Is a path a regular file?
223# This follows symbolic links, so both islink() and isdir() can be true
224# for the same path.
225
226def isfile(path):
Guido van Rossum15e22e11997-12-05 19:03:01 +0000227 """Test whether a path is a regular file"""
228 try:
229 st = os.stat(path)
230 except os.error:
231 return 0
232 return stat.S_ISREG(st[stat.ST_MODE])
Guido van Rossum555915a1994-02-24 11:32:59 +0000233
234
Guido van Rossumf3c695c1999-04-06 19:32:19 +0000235# Is a path a mount point? Either a root (with or without drive letter)
236# or an UNC path with at most a / or \ after the mount point.
Guido van Rossum555915a1994-02-24 11:32:59 +0000237
238def ismount(path):
Guido van Rossumca99c2c1998-01-19 22:25:59 +0000239 """Test whether a path is a mount point (defined as root of drive)"""
Guido van Rossumf3c695c1999-04-06 19:32:19 +0000240 unc, rest = splitunc(path)
241 if unc:
242 return rest in ("", "/", "\\")
Guido van Rossumca99c2c1998-01-19 22:25:59 +0000243 p = splitdrive(path)[1]
244 return len(p)==1 and p[0] in '/\\'
Guido van Rossum555915a1994-02-24 11:32:59 +0000245
246
247# Directory tree walk.
248# For each directory under top (including top itself, but excluding
249# '.' and '..'), func(arg, dirname, filenames) is called, where
250# dirname is the name of the directory and filenames is the list
251# files files (and subdirectories etc.) in the directory.
252# The func may modify the filenames list, to implement a filter,
253# or to impose a different order of visiting.
254
255def walk(top, func, arg):
Guido van Rossum534972b1999-02-03 17:20:50 +0000256 """Directory tree walk whth callback function.
257
Guido van Rossumf618a481999-11-02 13:29:08 +0000258 walk(top, func, arg) calls func(arg, d, files) for each directory d
Guido van Rossum534972b1999-02-03 17:20:50 +0000259 in the tree rooted at top (including top itself); files is a list
260 of all the files and subdirs in directory d."""
Guido van Rossum15e22e11997-12-05 19:03:01 +0000261 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):
271 walk(name, func, arg)
Guido van Rossum555915a1994-02-24 11:32:59 +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 Rossum534972b1999-02-03 17:20:50 +0000284 """Expand ~ and ~user constructs.
285
286 If user or $HOME is unknown, do nothing."""
Guido van Rossum15e22e11997-12-05 19:03:01 +0000287 if path[:1] <> '~':
288 return path
289 i, n = 1, len(path)
290 while i < n and path[i] not in '/\\':
291 i = i+1
292 if i == 1:
293 if os.environ.has_key('HOME'):
294 userhome = os.environ['HOME']
295 elif not os.environ.has_key('HOMEPATH'):
296 return path
297 else:
298 try:
299 drive=os.environ['HOMEDRIVE']
300 except KeyError:
301 drive = ''
302 userhome = join(drive, os.environ['HOMEPATH'])
303 else:
304 return path
305 return userhome + path[i:]
Guido van Rossum555915a1994-02-24 11:32:59 +0000306
307
308# Expand paths containing shell variable substitutions.
309# The following rules apply:
Guido van Rossum15e22e11997-12-05 19:03:01 +0000310# - no expansion within single quotes
311# - no escape character, except for '$$' which is translated into '$'
312# - ${varname} is accepted.
313# - varnames can be made out of letters, digits and the character '_'
Guido van Rossum555915a1994-02-24 11:32:59 +0000314# XXX With COMMAND.COM you can use any characters in a variable name,
315# XXX except '^|<>='.
316
317varchars = string.letters + string.digits + '_-'
318
Guido van Rossum15e22e11997-12-05 19:03:01 +0000319def expandvars(path):
Guido van Rossum534972b1999-02-03 17:20:50 +0000320 """Expand shell variables of form $var and ${var}.
321
322 Unknown variables are left unchanged."""
Guido van Rossum15e22e11997-12-05 19:03:01 +0000323 if '$' not in path:
324 return path
325 res = ''
326 index = 0
327 pathlen = len(path)
328 while index < pathlen:
329 c = path[index]
330 if c == '\'': # no expansion within single quotes
331 path = path[index + 1:]
332 pathlen = len(path)
333 try:
334 index = string.index(path, '\'')
335 res = res + '\'' + path[:index + 1]
336 except string.index_error:
337 res = res + path
338 index = pathlen -1
339 elif c == '$': # variable or '$$'
340 if path[index + 1:index + 2] == '$':
341 res = res + c
342 index = index + 1
343 elif path[index + 1:index + 2] == '{':
344 path = path[index+2:]
345 pathlen = len(path)
346 try:
347 index = string.index(path, '}')
348 var = path[:index]
349 if os.environ.has_key(var):
350 res = res + os.environ[var]
351 except string.index_error:
352 res = res + path
353 index = pathlen - 1
354 else:
355 var = ''
356 index = index + 1
357 c = path[index:index + 1]
358 while c != '' and c in varchars:
359 var = var + c
360 index = index + 1
361 c = path[index:index + 1]
362 if os.environ.has_key(var):
363 res = res + os.environ[var]
364 if c != '':
365 res = res + c
366 else:
367 res = res + c
368 index = index + 1
369 return res
Guido van Rossum555915a1994-02-24 11:32:59 +0000370
371
372# Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A/B.
Guido van Rossum3df7b5a1996-08-26 16:35:26 +0000373# Previously, this function also truncated pathnames to 8+3 format,
374# but as this module is called "ntpath", that's obviously wrong!
Guido van Rossum555915a1994-02-24 11:32:59 +0000375
376def normpath(path):
Guido van Rossum15e22e11997-12-05 19:03:01 +0000377 """Normalize path, eliminating double slashes, etc."""
Guido van Rossum16a0bc21998-02-18 13:48:31 +0000378 path = string.replace(path, "/", "\\")
Guido van Rossum15e22e11997-12-05 19:03:01 +0000379 prefix, path = splitdrive(path)
380 while path[:1] == os.sep:
381 prefix = prefix + os.sep
382 path = path[1:]
383 comps = string.splitfields(path, os.sep)
384 i = 0
385 while i < len(comps):
386 if comps[i] == '.':
387 del comps[i]
388 elif comps[i] == '..' and i > 0 and comps[i-1] not in ('', '..'):
389 del comps[i-1:i+1]
390 i = i-1
391 elif comps[i] == '' and i > 0 and comps[i-1] <> '':
392 del comps[i]
393 else:
394 i = i+1
395 # If the path is now empty, substitute '.'
396 if not prefix and not comps:
397 comps.append('.')
398 return prefix + string.joinfields(comps, os.sep)
Guido van Rossume294cf61999-01-29 18:05:18 +0000399
400
401# Return an absolute path.
402def abspath(path):
Guido van Rossum534972b1999-02-03 17:20:50 +0000403 """Return the absolute version of a path"""
Guido van Rossum9787bea1999-01-29 22:30:41 +0000404 try:
405 import win32api
Guido van Rossum9787bea1999-01-29 22:30:41 +0000406 except ImportError:
Guido van Rossum823e91c2000-02-02 16:54:39 +0000407 global abspath
408 def _abspath(path):
409 if not isabs(path):
410 path = join(os.getcwd(), path)
411 return normpath(path)
412 abspath = _abspath
413 return _abspath(path)
414 try:
415 path = win32api.GetFullPathName(path)
416 except win32api.error:
417 pass # Bad path - return unchanged.
Guido van Rossum6dfc7921999-11-30 15:00:00 +0000418 return normpath(path)