Expose os.DirEntry objects from pathlib

[barneygale]

Feature or enhancement

Path.iterdir() uses os.scandir() under-the-hood, but it throws away the resulting os.DirEntry objects, despite their numerous useful features.

I propose we add a new Path.dir_entry attribute that stores an os.DirEntry object or None. This attribute will be set to a directory entry in paths yielded from Path.iterdir().

This would allow users to call methods such as child.dir_entry.is_symlink() to check for symlinks without incurring a mandatory system call. It will help speed up the implementation of Path.copy() too.

This description needs a rework. I've found the above suggestion is a whole can of worms!

See discussion: https://discuss.python.org/t/is-there-a-pathlib-equivalent-of-os-scandir/46626

Linked PRs

• GH-125413: Add pathlib.Path.dir_entry attribute #125419
• GH-125413: pathlib.Path.copy(): get common metadata keys only once #125990
• GH-125413: Add pathlib.Path.scandir() method #126060
• GH-125413: pathlib ABCs: use scandir() to speed up glob() #126261
• GH-125413: pathlib ABCs: use scandir() to speed up walk() #126262
• GH-125413: pathlib: use scandir() to speed up copy() #126263

[ncoghlan]

I put this feedback on the PR, but it's probably better placed here: while I like the general idea, I don't think this specific API is the right way to do it.

• dir_entry potentially being None based on how the instance was created is inconvenient
• the docs having to excuse dir_entry existing on PurePath objects is awkward

I think we can eliminate both of those bits of awkwardness:

• define a new alternative construction method on os.DirEntry objects that allows one to be created from arbitrary os.PathLike objects
• make the slot on PurePath private rather than public (presumably as _dir_entry)
• define PathBase.dir_entry as a read-only property that returns the cached entry if it is already set, otherwise it uses the new constructor API to create a cached DirEntry instance for itself

If it's impractical to add os.DirEntry.from_path, then a pathlib._DirEntry class that just emulated the os.DirEntry API based on the real underlying Path object would also be fine

[barneygale]

To tie up the above loose ends, we went with a Path.scandir() method in the end.