clarify when the list of subdirectories is read (closes #13779)

2 files changed, 12 insertions, 8 deletions

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 20f3b25..ce19fd26 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -2228,9 +2228,11 @@ features:
 
    If optional argument *topdown* is ``True`` or not specified, the triple for a
    directory is generated before the triples for any of its subdirectories
-   (directories are generated top-down).  If *topdown* is ``False``, the triple for a
-   directory is generated after the triples for all of its subdirectories
-   (directories are generated bottom-up).
+   (directories are generated top-down).  If *topdown* is ``False``, the triple
+   for a directory is generated after the triples for all of its subdirectories
+   (directories are generated bottom-up). No matter the value of *topdown*, the
+   list of subdirectories is retrieved before the tuples for the directory and
+   its subdirectories are generated.
 
    When *topdown* is ``True``, the caller can modify the *dirnames* list in-place
    (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only
diff --git a/Lib/os.py b/Lib/os.py
index 8567f50..327656a 100644
--- a/Lib/os.py
+++ b/Lib/os.py
@@ -312,11 +312,12 @@ def walk(top, topdown=True, onerror=None, followlinks=False):
 
     When topdown is true, the caller can modify the dirnames list in-place
     (e.g., via del or slice assignment), and walk will only recurse into the
-    subdirectories whose names remain in dirnames; this can be used to prune
-    the search, or to impose a specific order of visiting.  Modifying
-    dirnames when topdown is false is ineffective, since the directories in
-    dirnames have already been generated by the time dirnames itself is
-    generated.
+    subdirectories whose names remain in dirnames; this can be used to prune the
+    search, or to impose a specific order of visiting.  Modifying dirnames when
+    topdown is false is ineffective, since the directories in dirnames have
+    already been generated by the time dirnames itself is generated. No matter
+    the value of topdown, the list of subdirectories is retrieved before the
+    tuples for the directory and its subdirectories are generated.
 
     By default errors from the os.listdir() call are ignored.  If
     optional arg 'onerror' is specified, it should be a function; it
@@ -344,6 +345,7 @@ def walk(top, topdown=True, onerror=None, followlinks=False):
         print("bytes in", len(files), "non-directory files")
         if 'CVS' in dirs:
             dirs.remove('CVS')  # don't visit CVS directories
+
     """
 
     islink, join, isdir = path.islink, path.join, path.isdir