1 # Module 'ntpath' -- common operations on WinNT/Win95 pathnames

     2 """Common pathname manipulations, WindowsNT/95 version.

     3 

     4 Instead of importing this module directly, import os and refer to this

     5 module as os.path.

     6 """

     7 

     8 import os

     9 import stat

    10 import sys

    11 

    12 __all__ = ["normcase","isabs","join","splitdrive","split","splitext",

    13            "basename","dirname","commonprefix","getsize","getmtime",

    14            "getatime","getctime", "islink","exists","lexists","isdir","isfile",

    15            "ismount","walk","expanduser","expandvars","normpath","abspath",

    16            "splitunc","curdir","pardir","sep","pathsep","defpath","altsep",

    17            "extsep","devnull","realpath","supports_unicode_filenames"]

    18 

    19 # strings representing various path-related bits and pieces

    20 curdir = '.'

    21 pardir = '..'

    22 extsep = '.'

    23 sep = '\\'

    24 pathsep = ';'

    25 altsep = '/'

    26 defpath = '.;C:\\bin'

    27 if 'ce' in sys.builtin_module_names:

    28     defpath = '\\Windows'

    29 elif 'os2' in sys.builtin_module_names:

    30     # OS/2 w/ VACPP

    31     altsep = '/'

    32 devnull = 'nul'

    33 

    34 # Normalize the case of a pathname and map slashes to backslashes.

    35 # Other normalizations (such as optimizing '../' away) are not done

    36 # (this is done by normpath).

    37 

    38 def normcase(s):

    39     """Normalize case of pathname.

    40 

    41     Makes all characters lowercase and all slashes into backslashes."""

    42     return s.replace("/", "\\").lower()

    43 

    44 

    45 # Return whether a path is absolute.

    46 # Trivial in Posix, harder on the Mac or MS-DOS.

    47 # For DOS it is absolute if it starts with a slash or backslash (current

    48 # volume), or if a pathname after the volume letter and colon / UNC resource

    49 # starts with a slash or backslash.

    50 

    51 def isabs(s):

    52     """Test whether a path is absolute"""

    53     s = splitdrive(s)[1]

    54     return s != '' and s[:1] in '/\\'

    55 

    56 

    57 # Join two (or more) paths.

    58 

    59 def join(a, *p):

    60     """Join two or more pathname components, inserting "\\" as needed"""

    61     path = a

    62     for b in p:

    63         b_wins = 0  # set to 1 iff b makes path irrelevant

    64         if path == "":

    65             b_wins = 1

    66 

    67         elif isabs(b):

    68             # This probably wipes out path so far.  However, it's more

    69             # complicated if path begins with a drive letter:

    70             #     1. join('c:', '/a') == 'c:/a'

    71             #     2. join('c:/', '/a') == 'c:/a'

    72             # But

    73             #     3. join('c:/a', '/b') == '/b'

    74             #     4. join('c:', 'd:/') = 'd:/'

    75             #     5. join('c:/', 'd:/') = 'd:/'

    76             if path[1:2] != ":" or b[1:2] == ":":

    77                 # Path doesn't start with a drive letter, or cases 4 and 5.

    78                 b_wins = 1

    79 

    80             # Else path has a drive letter, and b doesn't but is absolute.

    81             elif len(path) > 3 or (len(path) == 3 and

    82                                    path[-1] not in "/\\"):

    83                 # case 3

    84                 b_wins = 1

    85 

    86         if b_wins:

    87             path = b

    88         else:

    89             # Join, and ensure there's a separator.

    90             assert len(path) > 0

    91             if path[-1] in "/\\":

    92                 if b and b[0] in "/\\":

    93                     path += b[1:]

    94                 else:

    95                     path += b

    96             elif path[-1] == ":":

    97                 path += b

    98             elif b:

    99                 if b[0] in "/\\":

   100                     path += b

   101                 else:

   102                     path += "\\" + b

   103             else:

   104                 # path is not empty and does not end with a backslash,

   105                 # but b is empty; since, e.g., split('a/') produces

   106                 # ('a', ''), it's best if join() adds a backslash in

   107                 # this case.

   108                 path += '\\'

   109 

   110     return path

   111 

   112 

   113 # Split a path in a drive specification (a drive letter followed by a

   114 # colon) and the path specification.

   115 # It is always true that drivespec + pathspec == p

   116 def splitdrive(p):

   117     """Split a pathname into drive and path specifiers. Returns a 2-tuple

   118 "(drive,path)";  either part may be empty"""

   119     if p[1:2] == ':':

   120         return p[0:2], p[2:]

   121     return '', p

   122 

   123 

   124 # Parse UNC paths

   125 def splitunc(p):

   126     """Split a pathname into UNC mount point and relative path specifiers.

   127 

   128     Return a 2-tuple (unc, rest); either part may be empty.

   129     If unc is not empty, it has the form '//host/mount' (or similar

   130     using backslashes).  unc+rest is always the input path.

   131     Paths containing drive letters never have an UNC part.

   132     """

   133     if p[1:2] == ':':

   134         return '', p # Drive letter present

   135     firstTwo = p[0:2]

   136     if firstTwo == '//' or firstTwo == '\\\\':

   137         # is a UNC path:

   138         # vvvvvvvvvvvvvvvvvvvv equivalent to drive letter

   139         # \\machine\mountpoint\directories...

   140         #           directory ^^^^^^^^^^^^^^^

   141         normp = normcase(p)

   142         index = normp.find('\\', 2)

   143         if index == -1:

   144             ##raise RuntimeError, 'illegal UNC path: "' + p + '"'

   145             return ("", p)

   146         index = normp.find('\\', index + 1)

   147         if index == -1:

   148             index = len(p)

   149         return p[:index], p[index:]

   150     return '', p

   151 

   152 

   153 # Split a path in head (everything up to the last '/') and tail (the

   154 # rest).  After the trailing '/' is stripped, the invariant

   155 # join(head, tail) == p holds.

   156 # The resulting head won't end in '/' unless it is the root.

   157 

   158 def split(p):

   159     """Split a pathname.

   160 

   161     Return tuple (head, tail) where tail is everything after the final slash.

   162     Either part may be empty."""

   163 

   164     d, p = splitdrive(p)

   165     # set i to index beyond p's last slash

   166     i = len(p)

   167     while i and p[i-1] not in '/\\':

   168         i = i - 1

   169     head, tail = p[:i], p[i:]  # now tail has no slashes

   170     # remove trailing slashes from head, unless it's all slashes

   171     head2 = head

   172     while head2 and head2[-1] in '/\\':

   173         head2 = head2[:-1]

   174     head = head2 or head

   175     return d + head, tail

   176 

   177 

   178 # Split a path in root and extension.

   179 # The extension is everything starting at the last dot in the last

   180 # pathname component; the root is everything before that.

   181 # It is always true that root + ext == p.

   182 

   183 def splitext(p):

   184     """Split the extension from a pathname.

   185 

   186     Extension is everything from the last dot to the end.

   187     Return (root, ext), either part may be empty."""

   188 

   189     i = p.rfind('.')

   190     if i<=max(p.rfind('/'), p.rfind('\\')):

   191         return p, ''

   192     else:

   193         return p[:i], p[i:]

   194 

   195 

   196 # Return the tail (basename) part of a path.

   197 

   198 def basename(p):

   199     """Returns the final component of a pathname"""

   200     return split(p)[1]

   201 

   202 

   203 # Return the head (dirname) part of a path.

   204 

   205 def dirname(p):

   206     """Returns the directory component of a pathname"""

   207     return split(p)[0]

   208 

   209 

   210 # Return the longest prefix of all list elements.

   211 

   212 def commonprefix(m):

   213     "Given a list of pathnames, returns the longest common leading component"

   214     if not m: return ''

   215     s1 = min(m)

   216     s2 = max(m)

   217     n = min(len(s1), len(s2))

   218     for i in xrange(n):

   219         if s1[i] != s2[i]:

   220             return s1[:i]

   221     return s1[:n]

   222 

   223 

   224 # Get size, mtime, atime of files.

   225 

   226 def getsize(filename):

   227     """Return the size of a file, reported by os.stat()"""

   228     return os.stat(filename).st_size

   229 

   230 def getmtime(filename):

   231     """Return the last modification time of a file, reported by os.stat()"""

   232     return os.stat(filename).st_mtime

   233 

   234 def getatime(filename):

   235     """Return the last access time of a file, reported by os.stat()"""

   236     return os.stat(filename).st_atime

   237 

   238 def getctime(filename):

   239     """Return the creation time of a file, reported by os.stat()."""

   240     return os.stat(filename).st_ctime

   241 

   242 # Is a path a symbolic link?

   243 # This will always return false on systems where posix.lstat doesn't exist.

   244 

   245 def islink(path):

   246     """Test for symbolic link.  On WindowsNT/95 always returns false"""

   247     return False

   248 

   249 

   250 # Does a path exist?

   251 

   252 def exists(path):

   253     """Test whether a path exists"""

   254     try:

   255         st = os.stat(path)

   256     except os.error:

   257         return False

   258     return True

   259 

   260 lexists = exists

   261 

   262 

   263 # Is a path a dos directory?

   264 # This follows symbolic links, so both islink() and isdir() can be true

   265 # for the same path.

   266 

   267 def isdir(path):

   268     """Test whether a path is a directory"""

   269     try:

   270         st = os.stat(path)

   271     except os.error:

   272         return False

   273     return stat.S_ISDIR(st.st_mode)

   274 

   275 

   276 # Is a path a regular file?

   277 # This follows symbolic links, so both islink() and isdir() can be true

   278 # for the same path.

   279 

   280 def isfile(path):

   281     """Test whether a path is a regular file"""

   282     try:

   283         st = os.stat(path)

   284     except os.error:

   285         return False

   286     return stat.S_ISREG(st.st_mode)

   287 

   288 

   289 # Is a path a mount point?  Either a root (with or without drive letter)

   290 # or an UNC path with at most a / or \ after the mount point.

   291 

   292 def ismount(path):

   293     """Test whether a path is a mount point (defined as root of drive)"""

   294     unc, rest = splitunc(path)

   295     if unc:

   296         return rest in ("", "/", "\\")

   297     p = splitdrive(path)[1]

   298     return len(p) == 1 and p[0] in '/\\'

   299 

   300 

   301 # Directory tree walk.

   302 # For each directory under top (including top itself, but excluding

   303 # '.' and '..'), func(arg, dirname, filenames) is called, where

   304 # dirname is the name of the directory and filenames is the list

   305 # of files (and subdirectories etc.) in the directory.

   306 # The func may modify the filenames list, to implement a filter,

   307 # or to impose a different order of visiting.

   308 

   309 def walk(top, func, arg):

   310     """Directory tree walk with callback function.

   311 

   312     For each directory in the directory tree rooted at top (including top

   313     itself, but excluding '.' and '..'), call func(arg, dirname, fnames).

   314     dirname is the name of the directory, and fnames a list of the names of

   315     the files and subdirectories in dirname (excluding '.' and '..').  func

   316     may modify the fnames list in-place (e.g. via del or slice assignment),

   317     and walk will only recurse into the subdirectories whose names remain in

   318     fnames; this can be used to implement a filter, or to impose a specific

   319     order of visiting.  No semantics are defined for, or required of, arg,

   320     beyond that arg is always passed to func.  It can be used, e.g., to pass

   321     a filename pattern, or a mutable object designed to accumulate

   322     statistics.  Passing None for arg is common."""

   323 

   324     try:

   325         names = os.listdir(top)

   326     except os.error:

   327         return

   328     func(arg, top, names)

   329     exceptions = ('.', '..')

   330     for name in names:

   331         if name not in exceptions:

   332             name = join(top, name)

   333             if isdir(name):

   334                 walk(name, func, arg)

   335 

   336 

   337 # Expand paths beginning with '~' or '~user'.

   338 # '~' means $HOME; '~user' means that user's home directory.

   339 # If the path doesn't begin with '~', or if the user or $HOME is unknown,

   340 # the path is returned unchanged (leaving error reporting to whatever

   341 # function is called with the expanded path as argument).

   342 # See also module 'glob' for expansion of *, ? and [...] in pathnames.

   343 # (A function should also be defined to do full *sh-style environment

   344 # variable expansion.)

   345 

   346 def expanduser(path):

   347     """Expand ~ and ~user constructs.

   348 

   349     If user or $HOME is unknown, do nothing."""

   350     if path[:1] != '~':

   351         return path

   352     i, n = 1, len(path)

   353     while i < n and path[i] not in '/\\':

   354         i = i + 1

   355     if i == 1:

   356         if 'HOME' in os.environ:

   357             userhome = os.environ['HOME']

   358         elif not 'HOMEPATH' in os.environ:

   359             return path

   360         else:

   361             try:

   362                 drive = os.environ['HOMEDRIVE']

   363             except KeyError:

   364                 drive = ''

   365             userhome = join(drive, os.environ['HOMEPATH'])

   366     else:

   367         return path

   368     return userhome + path[i:]

   369 

   370 

   371 # Expand paths containing shell variable substitutions.

   372 # The following rules apply:

   373 #       - no expansion within single quotes

   374 #       - no escape character, except for '$$' which is translated into '$'

   375 #       - ${varname} is accepted.

   376 #       - varnames can be made out of letters, digits and the character '_'

   377 # XXX With COMMAND.COM you can use any characters in a variable name,

   378 # XXX except '^|<>='.

   379 

   380 def expandvars(path):

   381     """Expand shell variables of form $var and ${var}.

   382 

   383     Unknown variables are left unchanged."""

   384     if '$' not in path:

   385         return path

   386     import string

   387     varchars = string.ascii_letters + string.digits + '_-'

   388     res = ''

   389     index = 0

   390     pathlen = len(path)

   391     while index < pathlen:

   392         c = path[index]

   393         if c == '\'':   # no expansion within single quotes

   394             path = path[index + 1:]

   395             pathlen = len(path)

   396             try:

   397                 index = path.index('\'')

   398                 res = res + '\'' + path[:index + 1]

   399             except ValueError:

   400                 res = res + path

   401                 index = pathlen - 1

   402         elif c == '$':  # variable or '$$'

   403             if path[index + 1:index + 2] == '$':

   404                 res = res + c

   405                 index = index + 1

   406             elif path[index + 1:index + 2] == '{':

   407                 path = path[index+2:]

   408                 pathlen = len(path)

   409                 try:

   410                     index = path.index('}')

   411                     var = path[:index]

   412                     if var in os.environ:

   413                         res = res + os.environ[var]

   414                 except ValueError:

   415                     res = res + path

   416                     index = pathlen - 1

   417             else:

   418                 var = ''

   419                 index = index + 1

   420                 c = path[index:index + 1]

   421                 while c != '' and c in varchars:

   422                     var = var + c

   423                     index = index + 1

   424                     c = path[index:index + 1]

   425                 if var in os.environ:

   426                     res = res + os.environ[var]

   427                 if c != '':

   428                     res = res + c

   429         else:

   430             res = res + c

   431         index = index + 1

   432     return res

   433 

   434 

   435 # Normalize a path, e.g. A//B, A/./B and A/foo/../B all become A\B.

   436 # Previously, this function also truncated pathnames to 8+3 format,

   437 # but as this module is called "ntpath", that's obviously wrong!

   438 

   439 def normpath(path):

   440     """Normalize path, eliminating double slashes, etc."""

   441     path = path.replace("/", "\\")

   442     prefix, path = splitdrive(path)

   443     # We need to be careful here. If the prefix is empty, and the path starts

   444     # with a backslash, it could either be an absolute path on the current

   445     # drive (\dir1\dir2\file) or a UNC filename (\\server\mount\dir1\file). It

   446     # is therefore imperative NOT to collapse multiple backslashes blindly in

   447     # that case.

   448     # The code below preserves multiple backslashes when there is no drive

   449     # letter. This means that the invalid filename \\\a\b is preserved

   450     # unchanged, where a\\\b is normalised to a\b. It's not clear that there

   451     # is any better behaviour for such edge cases.

   452     if prefix == '':

   453         # No drive letter - preserve initial backslashes

   454         while path[:1] == "\\":

   455             prefix = prefix + "\\"

   456             path = path[1:]

   457     else:

   458         # We have a drive letter - collapse initial backslashes

   459         if path.startswith("\\"):

   460             prefix = prefix + "\\"

   461             path = path.lstrip("\\")

   462     comps = path.split("\\")

   463     i = 0

   464     while i < len(comps):

   465         if comps[i] in ('.', ''):

   466             del comps[i]

   467         elif comps[i] == '..':

   468             if i > 0 and comps[i-1] != '..':

   469                 del comps[i-1:i+1]

   470                 i -= 1

   471             elif i == 0 and prefix.endswith("\\"):

   472                 del comps[i]

   473             else:

   474                 i += 1

   475         else:

   476             i += 1

   477     # If the path is now empty, substitute '.'

   478     if not prefix and not comps:

   479         comps.append('.')

   480     return prefix + "\\".join(comps)

   481 

   482 

   483 # Return an absolute path.

   484 try:

   485     from nt import _getfullpathname

   486 

   487 except ImportError: # not running on Windows - mock up something sensible

   488     def abspath(path):

   489         """Return the absolute version of a path."""

   490         if not isabs(path):

   491             path = join(os.getcwd(), path)

   492         return normpath(path)

   493 

   494 else:  # use native Windows method on Windows

   495     def abspath(path):

   496         """Return the absolute version of a path."""

   497 

   498         if path: # Empty path must return current working directory.

   499             try:

   500                 path = _getfullpathname(path)

   501             except WindowsError:

   502                 pass # Bad path - return unchanged.

   503         else:

   504             path = os.getcwd()

   505         return normpath(path)

   506 

   507 # realpath is a no-op on systems without islink support

   508 realpath = abspath

   509 # Win9x family and earlier have no Unicode filename support.

   510 supports_unicode_filenames = (hasattr(sys, "getwindowsversion") and

   511                               sys.getwindowsversion()[3] >= 2)