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 5f60705..652b35f 100644
--- a/Lib/dospath.py
+++ b/Lib/dospath.py
@@ -183,13 +183,19 @@
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 1ef35ef..f8ca051 100644
--- a/Lib/macpath.py
+++ b/Lib/macpath.py
@@ -201,13 +201,19 @@
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 a1baf83..ed8a2dd 100644
--- a/Lib/ntpath.py
+++ b/Lib/ntpath.py
@@ -291,11 +291,20 @@
# 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.
- 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."""
+ 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/plat-riscos/riscospath.py b/Lib/plat-riscos/riscospath.py
index 8eda834..c25572b 100644
--- a/Lib/plat-riscos/riscospath.py
+++ b/Lib/plat-riscos/riscospath.py
@@ -350,11 +350,20 @@
# 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 c587b68..c342bbc 100644
--- a/Lib/posixpath.py
+++ b/Lib/posixpath.py
@@ -258,10 +258,20 @@
# 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: