1 # Module 'ntpath' -- common operations on WinNT/Win95 pathnames
2 """Common pathname manipulations, WindowsNT/95 version.
4 Instead of importing this module directly, import os and refer to this
12 from genericpath
import *
14 __all__
= ["normcase","isabs","join","splitdrive","split","splitext",
15 "basename","dirname","commonprefix","getsize","getmtime",
16 "getatime","getctime", "islink","exists","lexists","isdir","isfile",
17 "ismount","walk","expanduser","expandvars","normpath","abspath",
18 "splitunc","curdir","pardir","sep","pathsep","defpath","altsep",
19 "extsep","devnull","realpath","supports_unicode_filenames","relpath"]
21 # strings representing various path-related bits and pieces
29 if 'ce' in sys
.builtin_module_names
:
31 elif 'os2' in sys
.builtin_module_names
:
36 # Normalize the case of a pathname and map slashes to backslashes.
37 # Other normalizations (such as optimizing '../' away) are not done
38 # (this is done by normpath).
41 """Normalize case of pathname.
43 Makes all characters lowercase and all slashes into backslashes."""
44 return s
.replace("/", "\\").lower()
47 # Return whether a path is absolute.
48 # Trivial in Posix, harder on the Mac or MS-DOS.
49 # For DOS it is absolute if it starts with a slash or backslash (current
50 # volume), or if a pathname after the volume letter and colon / UNC resource
51 # starts with a slash or backslash.
54 """Test whether a path is absolute"""
56 return s
!= '' and s
[:1] in '/\\'
59 # Join two (or more) paths.
62 """Join two or more pathname components, inserting "\\" as needed"""
65 b_wins
= 0 # set to 1 iff b makes path irrelevant
70 # This probably wipes out path so far. However, it's more
71 # complicated if path begins with a drive letter:
72 # 1. join('c:', '/a') == 'c:/a'
73 # 2. join('c:/', '/a') == 'c:/a'
75 # 3. join('c:/a', '/b') == '/b'
76 # 4. join('c:', 'd:/') = 'd:/'
77 # 5. join('c:/', 'd:/') = 'd:/'
78 if path
[1:2] != ":" or b
[1:2] == ":":
79 # Path doesn't start with a drive letter, or cases 4 and 5.
82 # Else path has a drive letter, and b doesn't but is absolute.
83 elif len(path
) > 3 or (len(path
) == 3 and
84 path
[-1] not in "/\\"):
91 # Join, and ensure there's a separator.
94 if b
and b
[0] in "/\\":
106 # path is not empty and does not end with a backslash,
107 # but b is empty; since, e.g., split('a/') produces
108 # ('a', ''), it's best if join() adds a backslash in
115 # Split a path in a drive specification (a drive letter followed by a
116 # colon) and the path specification.
117 # It is always true that drivespec + pathspec == p
119 """Split a pathname into drive and path specifiers. Returns a 2-tuple
120 "(drive,path)"; either part may be empty"""
128 """Split a pathname into UNC mount point and relative path specifiers.
130 Return a 2-tuple (unc, rest); either part may be empty.
131 If unc is not empty, it has the form '//host/mount' (or similar
132 using backslashes). unc+rest is always the input path.
133 Paths containing drive letters never have an UNC part.
136 return '', p
# Drive letter present
138 if firstTwo
== '//' or firstTwo
== '\\\\':
140 # vvvvvvvvvvvvvvvvvvvv equivalent to drive letter
141 # \\machine\mountpoint\directories...
142 # directory ^^^^^^^^^^^^^^^
144 index
= normp
.find('\\', 2)
146 ##raise RuntimeError, 'illegal UNC path: "' + p + '"'
148 index
= normp
.find('\\', index
+ 1)
151 return p
[:index
], p
[index
:]
155 # Split a path in head (everything up to the last '/') and tail (the
156 # rest). After the trailing '/' is stripped, the invariant
157 # join(head, tail) == p holds.
158 # The resulting head won't end in '/' unless it is the root.
163 Return tuple (head, tail) where tail is everything after the final slash.
164 Either part may be empty."""
167 # set i to index beyond p's last slash
169 while i
and p
[i
-1] not in '/\\':
171 head
, tail
= p
[:i
], p
[i
:] # now tail has no slashes
172 # remove trailing slashes from head, unless it's all slashes
174 while head2
and head2
[-1] in '/\\':
177 return d
+ head
, tail
180 # Split a path in root and extension.
181 # The extension is everything starting at the last dot in the last
182 # pathname component; the root is everything before that.
183 # It is always true that root + ext == p.
186 return genericpath
._splitext
(p
, sep
, altsep
, extsep
)
187 splitext
.__doc
__ = genericpath
._splitext
.__doc
__
190 # Return the tail (basename) part of a path.
193 """Returns the final component of a pathname"""
197 # Return the head (dirname) part of a path.
200 """Returns the directory component of a pathname"""
203 # Is a path a symbolic link?
204 # This will always return false on systems where posix.lstat doesn't exist.
207 """Test for symbolic link.
208 On WindowsNT/95 and OS/2 always returns false
212 # alias exists to lexists
215 # Is a path a mount point? Either a root (with or without drive letter)
216 # or an UNC path with at most a / or \ after the mount point.
219 """Test whether a path is a mount point (defined as root of drive)"""
220 unc
, rest
= splitunc(path
)
222 return rest
in ("", "/", "\\")
223 p
= splitdrive(path
)[1]
224 return len(p
) == 1 and p
[0] in '/\\'
227 # Directory tree walk.
228 # For each directory under top (including top itself, but excluding
229 # '.' and '..'), func(arg, dirname, filenames) is called, where
230 # dirname is the name of the directory and filenames is the list
231 # of files (and subdirectories etc.) in the directory.
232 # The func may modify the filenames list, to implement a filter,
233 # or to impose a different order of visiting.
235 def walk(top
, func
, arg
):
236 """Directory tree walk with callback function.
238 For each directory in the directory tree rooted at top (including top
239 itself, but excluding '.' and '..'), call func(arg, dirname, fnames).
240 dirname is the name of the directory, and fnames a list of the names of
241 the files and subdirectories in dirname (excluding '.' and '..'). func
242 may modify the fnames list in-place (e.g. via del or slice assignment),
243 and walk will only recurse into the subdirectories whose names remain in
244 fnames; this can be used to implement a filter, or to impose a specific
245 order of visiting. No semantics are defined for, or required of, arg,
246 beyond that arg is always passed to func. It can be used, e.g., to pass
247 a filename pattern, or a mutable object designed to accumulate
248 statistics. Passing None for arg is common."""
251 names
= os
.listdir(top
)
254 func(arg
, top
, names
)
255 exceptions
= ('.', '..')
257 if name
not in exceptions
:
258 name
= join(top
, name
)
260 walk(name
, func
, arg
)
263 # Expand paths beginning with '~' or '~user'.
264 # '~' means $HOME; '~user' means that user's home directory.
265 # If the path doesn't begin with '~', or if the user or $HOME is unknown,
266 # the path is returned unchanged (leaving error reporting to whatever
267 # function is called with the expanded path as argument).
268 # See also module 'glob' for expansion of *, ? and [...] in pathnames.
269 # (A function should also be defined to do full *sh-style environment
270 # variable expansion.)
272 def expanduser(path
):
273 """Expand ~ and ~user constructs.
275 If user or $HOME is unknown, do nothing."""
279 while i
< n
and path
[i
] not in '/\\':
282 if 'HOME' in os
.environ
:
283 userhome
= os
.environ
['HOME']
284 elif 'USERPROFILE' in os
.environ
:
285 userhome
= os
.environ
['USERPROFILE']
286 elif not 'HOMEPATH' in os
.environ
:
290 drive
= os
.environ
['HOMEDRIVE']
293 userhome
= join(drive
, os
.environ
['HOMEPATH'])
296 userhome
= join(dirname(userhome
), path
[1:i
])
298 return userhome
+ path
[i
:]
301 # Expand paths containing shell variable substitutions.
302 # The following rules apply:
303 # - no expansion within single quotes
304 # - '$$' is translated into '$'
305 # - '%%' is translated into '%' if '%%' are not seen in %var1%%var2%
306 # - ${varname} is accepted.
307 # - $varname is accepted.
308 # - %varname% is accepted.
309 # - varnames can be made out of letters, digits and the characters '_-'
310 # (though is not verifed in the ${varname} and %varname% cases)
311 # XXX With COMMAND.COM you can use any characters in a variable name,
312 # XXX except '^|<>='.
314 def expandvars(path
):
315 """Expand shell variables of the forms $var, ${var} and %var%.
317 Unknown variables are left unchanged."""
318 if '$' not in path
and '%' not in path
:
321 varchars
= string
.ascii_letters
+ string
.digits
+ '_-'
325 while index
< pathlen
:
327 if c
== '\'': # no expansion within single quotes
328 path
= path
[index
+ 1:]
331 index
= path
.index('\'')
332 res
= res
+ '\'' + path
[:index
+ 1]
336 elif c
== '%': # variable or '%'
337 if path
[index
+ 1:index
+ 2] == '%':
341 path
= path
[index
+1:]
344 index
= path
.index('%')
346 res
= res
+ '%' + path
350 if var
in os
.environ
:
351 res
= res
+ os
.environ
[var
]
353 res
= res
+ '%' + var
+ '%'
354 elif c
== '$': # variable or '$$'
355 if path
[index
+ 1:index
+ 2] == '$':
358 elif path
[index
+ 1:index
+ 2] == '{':
359 path
= path
[index
+2:]
362 index
= path
.index('}')
364 if var
in os
.environ
:
365 res
= res
+ os
.environ
[var
]
367 res
= res
+ '${' + var
+ '}'
369 res
= res
+ '${' + path
374 c
= path
[index
:index
+ 1]
375 while c
!= '' and c
in varchars
:
378 c
= path
[index
:index
+ 1]
379 if var
in os
.environ
:
380 res
= res
+ os
.environ
[var
]
382 res
= res
+ '$' + var
391 # Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A\B.
392 # Previously, this function also truncated pathnames to 8+3 format,
393 # but as this module is called "ntpath", that's obviously wrong!
396 """Normalize path, eliminating double slashes, etc."""
397 path
= path
.replace("/", "\\")
398 prefix
, path
= splitdrive(path
)
399 # We need to be careful here. If the prefix is empty, and the path starts
400 # with a backslash, it could either be an absolute path on the current
401 # drive (\dir1\dir2\file) or a UNC filename (\\server\mount\dir1\file). It
402 # is therefore imperative NOT to collapse multiple backslashes blindly in
404 # The code below preserves multiple backslashes when there is no drive
405 # letter. This means that the invalid filename \\\a\b is preserved
406 # unchanged, where a\\\b is normalised to a\b. It's not clear that there
407 # is any better behaviour for such edge cases.
409 # No drive letter - preserve initial backslashes
410 while path
[:1] == "\\":
411 prefix
= prefix
+ "\\"
414 # We have a drive letter - collapse initial backslashes
415 if path
.startswith("\\"):
416 prefix
= prefix
+ "\\"
417 path
= path
.lstrip("\\")
418 comps
= path
.split("\\")
420 while i
< len(comps
):
421 if comps
[i
] in ('.', ''):
423 elif comps
[i
] == '..':
424 if i
> 0 and comps
[i
-1] != '..':
427 elif i
== 0 and prefix
.endswith("\\"):
433 # If the path is now empty, substitute '.'
434 if not prefix
and not comps
:
436 return prefix
+ "\\".join(comps
)
439 # Return an absolute path.
441 from nt
import _getfullpathname
443 except ImportError: # not running on Windows - mock up something sensible
445 """Return the absolute version of a path."""
447 path
= join(os
.getcwd(), path
)
448 return normpath(path
)
450 else: # use native Windows method on Windows
452 """Return the absolute version of a path."""
454 if path
: # Empty path must return current working directory.
456 path
= _getfullpathname(path
)
458 pass # Bad path - return unchanged.
461 return normpath(path
)
463 # realpath is a no-op on systems without islink support
465 # Win9x family and earlier have no Unicode filename support.
466 supports_unicode_filenames
= (hasattr(sys
, "getwindowsversion") and
467 sys
.getwindowsversion()[3] >= 2)
469 def relpath(path
, start
=curdir
):
470 """Return a relative version of a path"""
473 raise ValueError("no path specified")
474 start_list
= abspath(start
).split(sep
)
475 path_list
= abspath(path
).split(sep
)
476 if start_list
[0].lower() != path_list
[0].lower():
477 unc_path
, rest
= splitunc(path
)
478 unc_start
, rest
= splitunc(start
)
479 if bool(unc_path
) ^
bool(unc_start
):
480 raise ValueError("Cannot mix UNC and non-UNC paths (%s and %s)"
483 raise ValueError("path is on drive %s, start on drive %s"
484 % (path_list
[0], start_list
[0]))
485 # Work out how much of the filepath is shared by start and path.
486 for i
in range(min(len(start_list
), len(path_list
))):
487 if start_list
[i
].lower() != path_list
[i
].lower():
492 rel_list
= [pardir
] * (len(start_list
)-i
) + path_list
[i
:]
493 return join(*rel_list
)