bpo-36602: Allow pathlib.Path.iterdir to list recursively

Doc/library/pathlib.rst

@@ -896,7 +896,7 @@ call fails (for example because the path doesn't exist).
    other errors (such as permission errors) are propagated.
 
 
-.. method:: Path.iterdir()
+.. method:: Path.iterdir(*, recursive=False)
 
    When the path points to a directory, yield path objects of the directory
    contents::
@@ -917,6 +917,19 @@ call fails (for example because the path doesn't exist).
    to the directory after creating the iterator, whether an path object for
    that file be included is unspecified.
 
+   Also supports recursing into subdirectories::
+
+      >>> p = Path('foo')
+      >>> for child in p.iterdir(recursive=True): child
+      ...
+      PosixPath('foo/a.txt')
+      PosixPath('foo/b.py')
+      PosixPath('foo/bar/c.txt')
+      PosixPath('foo/bar/spam/d.rst')
+
+   .. versionchanged:: 3.9
+      The *recursive* parameter was added.
+
 .. method:: Path.lchmod(mode)
 
    Like :meth:`Path.chmod` but, if the path points to a symbolic link, the

Lib/pathlib.py

@@ -920,10 +920,30 @@ def samefile(self, other_path):
             other_st = self.__class__(other_path).stat()
         return os.path.samestat(st, other_st)
 
-    def iterdir(self):
+    def _iterdir_recursive(self):
+        """Recursive directory listing."""
+        to_list = [self]
+        listed = set()
+        while len(to_list) > 0:
+            dirpath = to_list.pop(0)
+            for path in dirpath.iterdir(recursive=False):
+                if path.is_dir():
+                    resolved = path.resolve()
+                    if resolved not in listed:
+                        to_list.append(path)
+                        listed.add(resolved)
+                else:
+                    yield path
+
+    def iterdir(self, *, recursive=False):
         """Iterate over the files in this directory.  Does not yield any
-        result for the special paths '.' and '..'.
+        result for the special paths '.' and '..'. Yields from
+        subdirectories if recursive=True (but then doesn't yield any
+        directories).
         """
+        if recursive:
+            yield from self._iterdir_recursive()
+            return
         for name in os.listdir(self):
             yield self._make_child_relpath(name)
 

Lib/test/test_pathlib.py

@@ -1612,6 +1612,61 @@ def test_iterdir(self):
             expected += ['linkA', 'linkB', 'brokenLink', 'brokenLinkLoop']
         self.assertEqual(paths, { P(BASE, q) for q in expected })
 
+    def test_iterdir_recursive(self):
+        P = self.cls
+        p = P(join('dirC'))
+        it = p.iterdir(recursive=True)
+        paths = set(it)
+        expected = [('dirD', 'fileD'), ('fileC',)]
+        self.assertEqual(paths, { P(join('dirC'), *q) for q in expected })
+
+    @os_helper.skip_unless_symlink
+    def test_iterdir_recursive_symlink(self):
+        P = self.cls
+        p = P(join('dirB'))
+        it = p.iterdir(recursive=True)
+        paths = set(it)
+        expected = [('fileB',), ('linkD', 'fileB')]
+        self.assertEqual(paths, { P(join('dirB'), *q) for q in expected })
+
+    @os_helper.skip_unless_symlink
+    def test_iterdir_recursive_symlink_cycle(self):
+        P = self.cls
+        os.mkdir(join('dirF'))
+        os.mkdir(join('dirF', 'dirG'))
+        os.mkdir(join('dirF', 'dirH'))
+        P(join('dirF', 'fileF')).touch()
+        P(join('dirF', 'dirG', 'fileG')).touch()
+        P(join('dirF', 'dirH', 'fileH')).touch()
+        os.symlink(os.path.join('..', 'dirG'), join('dirF', 'dirH', 'linkG'))
+        os.symlink(os.path.join('..', 'dirH'), join('dirF', 'dirG', 'linkH'))
+        # Now have structure
+        # (BASE)
+        #  |
+        #  ...
+        #  |
+        #  |-- dirF
+        #  |   |-- dirG
+        #  |   |   |-- fileG
+        #  |   |   `-- linkH -> ../dirH
+        #  |   |-- dirH
+        #  |   |   |-- fileH
+        #  |   |   `-- linkG -> ../dirG
+        #  |   `-- fileF
+        #  |
+        #  ...
+        try:
+            p = P(join('dirF'))
+            it = p.iterdir(recursive=True)
+            paths = set(it)
+            expected = [
+                ('fileF',),
+                ('dirG', 'fileG'),
+                ('dirH', 'fileH')]
+            self.assertEqual(paths, { P(join('dirF'), *q) for q in expected })
+        finally:
+            os_helper.rmtree(join('dirF'))
+
     @os_helper.skip_unless_symlink
     def test_iterdir_symlink(self):
         # __iter__ on a symlink to a directory.

Misc/ACKS

@@ -1291,6 +1291,7 @@ Ethan Onstott
 Ken Jin Ooi
 Piet van Oostrum
 Tomas Oppelstrup
+Laurie Opperman
 Jason Orendorff
 Bastien Orivel
 orlnub123

Misc/NEWS.d/next/Library/2019-04-11-11-15-24.bpo-36602.zxNvQK.rst

@@ -0,0 +1 @@
+``pathlib.Path.iterdir`` can now list items in subdirectories with the optional argument ``recursive=True``. Note that directories will not be yielded in recursive listing