GH-125413: Add `pathlib.Path.scandir()` method (#126060)

Add `pathlib.Path.scandir()` as a trivial wrapper of `os.scandir()`. This
will be used to implement several `PathBase` methods more efficiently,
including methods that provide `Path.copy()`.

2 files changed, 35 insertions, 0 deletions

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 4380122..b6fb365 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -1289,6 +1289,35 @@ Reading directories
    raised.
 
 
+.. method:: Path.scandir()
+
+   When the path points to a directory, return an iterator of
+   :class:`os.DirEntry` objects corresponding to entries in the directory. The
+   returned iterator supports the :term:`context manager` protocol. It is
+   implemented using :func:`os.scandir` and gives the same guarantees.
+
+   Using :meth:`~Path.scandir` instead of :meth:`~Path.iterdir` can
+   significantly increase the performance of code that also needs file type or
+   file attribute information, because :class:`os.DirEntry` objects expose
+   this information if the operating system provides it when scanning a
+   directory.
+
+   The following example displays the names of subdirectories. The
+   ``entry.is_dir()`` check will generally not make an additional system call::
+
+      >>> p = Path('docs')
+      >>> with p.scandir() as entries:
+      ...     for entry in entries:
+      ...         if entry.is_dir():
+      ...             entry.name
+      ...
+      '_templates'
+      '_build'
+      '_static'
+
+   .. versionadded:: 3.14
+
+
 .. method:: Path.glob(pattern, *, case_sensitive=None, recurse_symlinks=False)
 
    Glob the given relative *pattern* in the directory represented by this path,
diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
index 7f9e310..48314f9 100644
--- a/Doc/whatsnew/3.14.rst
+++ b/Doc/whatsnew/3.14.rst
@@ -380,6 +380,12 @@ pathlib
 
   (Contributed by Barney Gale in :gh:`73991`.)
 
+* Add :meth:`pathlib.Path.scandir` to scan a directory and return an iterator
+  of :class:`os.DirEntry` objects. This is exactly equivalent to calling
+  :func:`os.scandir` on a path object.
+
+  (Contributed by Barney Gale in :gh:`125413`.)
+
 
 pdb
 ---