Added doc strings and reindented according to new standard, without tabs.

(Like ntpath.py, this was contributed by "Charles G. Waldman" <cgw@pgt.com>)

Lib/posixpath.py

@@ -5,6 +5,10 @@
 # on other systems (e.g. Mac, Windows), os.path provides the same
 # operations in a manner specific to that platform, and is an alias
 # to another module (e.g. macpath, ntpath).
+"""Common pathname manipulations, Posix version. 
+Instead of importing this module
+directly, import os and refer to this module as os.path.
+"""
 
 import os
 import stat
@@ -16,6 +20,7 @@
 # (another function should be defined to do that).
 
 def normcase(s):
+    """Normalize case of pathname.  Has no effect under Posix"""
     return s
 
 
@@ -23,6 +28,7 @@ def normcase(s):
 # Trivial in Posix, harder on the Mac or MS-DOS.
 
 def isabs(s):
+    """Test whether a path is absolute"""
     return s[:1] == '/'
 
 
@@ -31,6 +37,7 @@ def isabs(s):
 # Insert a '/' unless the first part is empty or already ends in '/'.
 
 def join(a, *p):
+    """Join two or more pathname components, inserting '/' as needed"""
     path = a
     for b in p:
         if b[:1] == '/':
@@ -48,6 +55,8 @@ def join(a, *p):
 # Trailing '/'es are stripped from head unless it is the root.
 
 def split(p):
+    """Split a pathname.  Returns tuple "(head, tail)" where "tail" is 
+everything after the final slash.  Either part may be empty"""
     import string
     i = string.rfind(p, '/') + 1
     head, tail = p[:i], p[i:]
@@ -63,6 +72,8 @@ def split(p):
 # It is always true that root + ext == p.
 
 def splitext(p):
+    """Split the extension from a pathname.  Extension is everything from the
+last dot to the end.  Returns "(root, ext)", either part may be empty"""
     root, ext = '', ''
     for c in p:
         if c == '/':
@@ -83,24 +94,29 @@ def splitext(p):
 # path.  Useful on DOS/Windows/NT; on Unix, the drive is always empty.
 
 def splitdrive(p):
+    """Split a pathname into drive and path. On Posix, drive is always 
+empty"""
     return '', p
 
 
 # Return the tail (basename) part of a path.
 
 def basename(p):
+    """Returns the final component of a pathname"""
     return split(p)[1]
 
 
 # Return the head (dirname) part of a path.
 
 def dirname(p):
+    """Returns the directory component of a pathname"""
     return split(p)[0]
 
 
 # Return the longest prefix of all list elements.
 
 def commonprefix(m):
+    "Given a list of pathnames, returns the longest common leading component"
     if not m: return ''
     prefix = m[0]
     for item in m:
@@ -116,6 +132,7 @@ def commonprefix(m):
 # This will always return false on systems where os.lstat doesn't exist.
 
 def islink(path):
+    """Test whether a path is a symbolic link"""
     try:
         st = os.lstat(path)
     except (os.error, AttributeError):
@@ -127,6 +144,7 @@ def islink(path):
 # This is false for dangling symbolic links.
 
 def exists(path):
+    """Test whether a path exists.  Returns false for broken symbolic links"""
     try:
         st = os.stat(path)
     except os.error:
@@ -139,6 +157,7 @@ def exists(path):
 # for the same path.
 
 def isdir(path):
+    """Test whether a path is a directory"""
     try:
         st = os.stat(path)
     except os.error:
@@ -151,6 +170,7 @@ def isdir(path):
 # for the same path.
 
 def isfile(path):
+    """Test whether a path is a regular file"""
     try:
         st = os.stat(path)
     except os.error:
@@ -161,6 +181,7 @@ def isfile(path):
 # Are two filenames really pointing to the same file?
 
 def samefile(f1, f2):
+    """Test whether two pathnames reference the same actual file"""
     s1 = os.stat(f1)
     s2 = os.stat(f2)
     return samestat(s1, s2)
@@ -170,6 +191,7 @@ def samefile(f1, f2):
 # (Not necessarily the same file descriptor!)
 
 def sameopenfile(fp1, fp2):
+    """Test whether two open file objects reference the same file"""
     s1 = os.fstat(fp1)
     s2 = os.fstat(fp2)
     return samestat(s1, s2)
@@ -179,6 +201,7 @@ def sameopenfile(fp1, fp2):
 # describing the same file?
 
 def samestat(s1, s2):
+    """Test whether two stat buffers reference the same file"""
     return s1[stat.ST_INO] == s2[stat.ST_INO] and \
 	   s1[stat.ST_DEV] == s2[stat.ST_DEV]
 
@@ -187,6 +210,7 @@ def samestat(s1, s2):
 # (Does this work for all UNIXes?  Is it even guaranteed to work by Posix?)
 
 def ismount(path):
+    """Test whether a path is a mount point"""
     try:
         s1 = os.stat(path)
         s2 = os.stat(join(path, '..'))
@@ -207,11 +231,15 @@ def ismount(path):
 # For each directory under top (including top itself, but excluding
 # '.' and '..'), func(arg, dirname, filenames) is called, where
 # dirname is the name of the directory and filenames is the list
-# files files (and subdirectories etc.) in the directory.
+# of files (and subdirectories etc.) in the directory.
 # The func may modify the filenames list, to implement a filter,
 # or to impose a different order of visiting.
 
 def walk(top, func, arg):
+    """walk(top,func,args) calls func(arg, d, files) for each directory "d" 
+in the tree  rooted at "top" (including "top" itself).  "files" is a list
+of all the files and subdirs in directory "d".
+"""
     try:
         names = os.listdir(top)
     except os.error:
@@ -235,6 +263,8 @@ def walk(top, func, arg):
 # variable expansion.)
 
 def expanduser(path):
+    """Expand ~ and ~user constructions.  If user or $HOME is unknown, 
+do nothing"""
     if path[:1] <> '~':
         return path
     i, n = 1, len(path)
@@ -262,6 +292,8 @@ def expanduser(path):
 _varprog = None
 
 def expandvars(path):
+    """Expand shell variables of form $var and ${var}.  Unknown variables
+are left unchanged"""
     global _varprog
     if '$' not in path:
         return path
@@ -292,6 +324,7 @@ def expandvars(path):
 # if it contains symbolic links!
 
 def normpath(path):
+    """Normalize path, eliminating double slashes, etc."""
     import string
     # Treat initial slashes specially
     slashes = ''
@@ -303,8 +336,7 @@ def normpath(path):
     while i < len(comps):
         if comps[i] == '.':
             del comps[i]
-		elif comps[i] == '..' and i > 0 and \
-					  comps[i-1] not in ('', '..'):
+        elif comps[i] == '..' and i > 0 and comps[i-1] not in ('', '..'):
             del comps[i-1:i+1]
             i = i-1
         elif comps[i] == '' and i > 0 and comps[i-1] <> '':