SF bug [#469732] os.path.walk docstring inconsistent.

We have 5 implementations of walk(), and 5 different docstrings.  Combined
'em.  Let's see how long it takes before they're all different again!

diff --git a/Lib/dospath.py b/Lib/dospath.py
index 5f607057a35b0f7d505531fce07aa465a256a12f..652b35f51f92c6672ef0c04ff7940d5f6683c766 100644 (file)
--- a/Lib/dospath.py
+++ b/Lib/dospath.py
@@ -183,13 +183,19 @@ def ismount(path):
 
 
 def walk(top, func, arg):
-    """Directory tree walk.
-    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.
-    The func may modify the filenames list, to implement a filter,
-    or to impose a different order of visiting."""
+    """Directory tree walk with callback function.
+
+    For each directory in the directory tree rooted at top (including top
+    itself, but excluding '.' and '..'), call func(arg, dirname, fnames).
+    dirname is the name of the directory, and fnames a list of the names of
+    the files and subdirectories in dirname (excluding '.' and '..').  func
+    may modify the fnames list in-place (e.g. via del or slice assignment),
+    and walk will only recurse into the subdirectories whose names remain in
+    fnames; this can be used to implement a filter, or to impose a specific
+    order of visiting.  No semantics are defined for, or required of, arg,
+    beyond that arg is always passed to func.  It can be used, e.g., to pass
+    a filename pattern, or a mutable object designed to accumulate
+    statistics.  Passing None for arg is common."""
 
     try:
         names = os.listdir(top)

diff --git a/Lib/macpath.py b/Lib/macpath.py
index 1ef35ef11bdd042efac6a03dfb3b4ef4cf1e5831..f8ca05165ac9971603c71fe36a9dee5bf114746f 100644 (file)
--- a/Lib/macpath.py
+++ b/Lib/macpath.py
@@ -201,13 +201,19 @@ def normpath(s):
 
 
 def walk(top, func, arg):
-    """Directory tree walk.
-    For each directory under top (including top itself),
-    func(arg, dirname, filenames) is called, where
-    dirname is the name of the directory and filenames is the list
-    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."""
+    """Directory tree walk with callback function.
+
+    For each directory in the directory tree rooted at top (including top
+    itself, but excluding '.' and '..'), call func(arg, dirname, fnames).
+    dirname is the name of the directory, and fnames a list of the names of
+    the files and subdirectories in dirname (excluding '.' and '..').  func
+    may modify the fnames list in-place (e.g. via del or slice assignment),
+    and walk will only recurse into the subdirectories whose names remain in
+    fnames; this can be used to implement a filter, or to impose a specific
+    order of visiting.  No semantics are defined for, or required of, arg,
+    beyond that arg is always passed to func.  It can be used, e.g., to pass
+    a filename pattern, or a mutable object designed to accumulate
+    statistics.  Passing None for arg is common."""
 
     try:
         names = os.listdir(top)

diff --git a/Lib/ntpath.py b/Lib/ntpath.py
index a1baf83d2c1c3a73266cfdb4e7583a8f65d0bca3..ed8a2ddf4fa0c6f449e2d040674786ed698d6369 100644 (file)
--- a/Lib/ntpath.py
+++ b/Lib/ntpath.py
@@ -291,11 +291,20 @@ def ismount(path):
 # or to impose a different order of visiting.
 
 def walk(top, func, arg):
-    """Directory tree walk whth callback function.
+    """Directory tree walk with callback function.
+
+    For each directory in the directory tree rooted at top (including top
+    itself, but excluding '.' and '..'), call func(arg, dirname, fnames).
+    dirname is the name of the directory, and fnames a list of the names of
+    the files and subdirectories in dirname (excluding '.' and '..').  func
+    may modify the fnames list in-place (e.g. via del or slice assignment),
+    and walk will only recurse into the subdirectories whose names remain in
+    fnames; this can be used to implement a filter, or to impose a specific
+    order of visiting.  No semantics are defined for, or required of, arg,
+    beyond that arg is always passed to func.  It can be used, e.g., to pass
+    a filename pattern, or a mutable object designed to accumulate
+    statistics.  Passing None for arg is common."""
 
-    walk(top, func, arg) 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:

diff --git a/Lib/plat-riscos/riscospath.py b/Lib/plat-riscos/riscospath.py
index 8eda834d564894838e5d901bac80d13e1c5f2703..c25572b8b2cdf0c576d5cb4aad98ba89b6460ab1 100644 (file)
--- a/Lib/plat-riscos/riscospath.py
+++ b/Lib/plat-riscos/riscospath.py
@@ -350,11 +350,20 @@ def normpath(p):
 # Independent of host system. Why am I in os.path?
 
 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".
-  """
+    """Directory tree walk with callback function.
+
+    For each directory in the directory tree rooted at top (including top
+    itself, but excluding '.' and '..'), call func(arg, dirname, fnames).
+    dirname is the name of the directory, and fnames a list of the names of
+    the files and subdirectories in dirname (excluding '.' and '..').  func
+    may modify the fnames list in-place (e.g. via del or slice assignment),
+    and walk will only recurse into the subdirectories whose names remain in
+    fnames; this can be used to implement a filter, or to impose a specific
+    order of visiting.  No semantics are defined for, or required of, arg,
+    beyond that arg is always passed to func.  It can be used, e.g., to pass
+    a filename pattern, or a mutable object designed to accumulate
+    statistics.  Passing None for arg is common."""
+
     try:
         names= os.listdir(top)
     except os.error:

diff --git a/Lib/posixpath.py b/Lib/posixpath.py
index c587b68b89ea83fef1d1b069ed74dbcc5431a1cb..c342bbcf198e2498d9d4aac9985df0457a1449e6 100644 (file)
--- a/Lib/posixpath.py
+++ b/Lib/posixpath.py
@@ -258,10 +258,20 @@ def ismount(path):
 # or to impose a different order of visiting.
 
 def walk(top, func, arg):
-    """walk(top,func,arg) 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".
-    """
+    """Directory tree walk with callback function.
+
+    For each directory in the directory tree rooted at top (including top
+    itself, but excluding '.' and '..'), call func(arg, dirname, fnames).
+    dirname is the name of the directory, and fnames a list of the names of
+    the files and subdirectories in dirname (excluding '.' and '..').  func
+    may modify the fnames list in-place (e.g. via del or slice assignment),
+    and walk will only recurse into the subdirectories whose names remain in
+    fnames; this can be used to implement a filter, or to impose a specific
+    order of visiting.  No semantics are defined for, or required of, arg,
+    beyond that arg is always passed to func.  It can be used, e.g., to pass
+    a filename pattern, or a mutable object designed to accumulate
+    statistics.  Passing None for arg is common."""
+
     try:
         names = os.listdir(top)
     except os.error: