Move thorough docstring from os.walk to pathlib.Path.walk

pathlib's Path.walk() is generally more pleasant to use, but up to now
its docstring didn't describe the functionality except by reference to
os.walk. This change makes the docstring more helpful, and points users
of the old os.walk() API to pathlib.

Author: lheckemann

Lib/os.py

@@ -306,65 +306,7 @@ def renames(old, new):
 _walk_symlinks_as_files = object()
 
 def walk(top, topdown=True, onerror=None, followlinks=False):
-    """Directory tree generator.
-
-    For each directory in the directory tree rooted at top (including top
-    itself, but excluding '.' and '..'), yields a 3-tuple
-
-        dirpath, dirnames, filenames
-
-    dirpath is a string, the path to the directory.  dirnames is a list of
-    the names of the subdirectories in dirpath (including symlinks to directories,
-    and excluding '.' and '..').
-    filenames is a list of the names of the non-directory files in dirpath.
-    Note that the names in the lists are just names, with no path components.
-    To get a full path (which begins with top) to a file or directory in
-    dirpath, do os.path.join(dirpath, name).
-
-    If optional arg '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).
-
-    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 has no effect on the behavior of os.walk(), 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.scandir() call are ignored.  If
-    optional arg 'onerror' is specified, it should be a function; it
-    will be called with one argument, an OSError instance.  It can
-    report the error to continue with the walk, or raise the exception
-    to abort the walk.  Note that the filename is available as the
-    filename attribute of the exception object.
-
-    By default, os.walk does not follow symbolic links to subdirectories on
-    systems that support them.  In order to get this functionality, set the
-    optional argument 'followlinks' to true.
-
-    Caution:  if you pass a relative pathname for top, don't change the
-    current working directory between resumptions of walk.  walk never
-    changes the current directory, and assumes that the client doesn't
-    either.
-
-    Example:
-
-    import os
-    from os.path import join, getsize
-    for root, dirs, files in os.walk('python/Lib/xml'):
-        print(root, "consumes ")
-        print(sum(getsize(join(root, name)) for name in files), end=" ")
-        print("bytes in", len(files), "non-directory files")
-        if '__pycache__' in dirs:
-            dirs.remove('__pycache__')  # don't visit __pycache__ directories
-
-    """
+    """Walk the directory tree from 'top', similar to pathlib.Path.walk()."""
     sys.audit("os.walk", top, topdown, onerror, followlinks)
 
     stack = [fspath(top)]

Lib/pathlib/__init__.py

@@ -1078,7 +1078,63 @@ def rglob(self, pattern, *, case_sensitive=None, recurse_symlinks=False):
         return self.glob(pattern, case_sensitive=case_sensitive, recurse_symlinks=recurse_symlinks)
 
     def walk(self, top_down=True, on_error=None, follow_symlinks=False):
-        """Walk the directory tree from this directory, similar to os.walk()."""
+        """
+        Directory tree generator.
+
+        For each directory in the directory tree rooted at self (including self, but excluding '.' and '..'), yields a 3-tuple
+
+            dirpath, dirnames, filenames
+
+        'dirpath' is a Path, the path to the directory relative to self.  'dirnames'
+        is a list of the names of the subdirectories in 'dirpath' (including
+        symlinks to directories, and excluding '.' and '..'). 'filenames' is a
+        list of the names of the non-directory files in dirpath. Note that the
+        names in the lists are just names, with no path components. To get a
+        full path (which begins with top) to a file or directory in dirpath, use
+        (dirpath / name).
+
+        If optional arg 'top_down' 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 top_down is false, the
+        triple for a directory is generated after the triples for all of its
+        subdirectories (directories are generated bottom up).
+
+        When top_down 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 top_down is false has no effect on the behavior of walk(),
+        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.scandir() call are ignored.  If optional
+        arg 'onerror' is specified, it should be a function; it will be called
+        with one argument, an OSError instance.  It can report the error to
+        continue with the walk, or raise the exception to abort the walk.
+        Note that the filename is available as the filename attribute of the
+        exception object.
+
+        By default, walk() does not follow symbolic links to subdirectories on
+        systems that support them.  In order to get this functionality, set the
+        optional argument 'follow_symlinks' to true.
+
+        Caution:  if 'self' is relative, don't change the current working
+        directory between resumptions of walk.  walk never changes the current
+        directory, and assumes that the client doesn't either.
+
+        Example:
+
+        from pathlib import Path
+        for root, dirs, files in Path('python/Lib/xml').walk():
+            print(root, "consumes ")
+            print(sum((root / name).stat().st_size for name in files), end=" ")
+            print("bytes in", len(files), "non-directory files")
+            if '__pycache__' in dirs:
+                dirs.remove('__pycache__')  # don't visit __pycache__ directories
+
+        """
         sys.audit("pathlib.Path.walk", self, on_error, follow_symlinks)
         root_dir = str(self)
         if not follow_symlinks: